batchsession

Documentation

Index

• Variables
• func BuildAndSignDeleteIntent(ctx context.Context, args IntentArgs) (string, string, error)
• func BuildAndSignGetPendingTxIntent(ctx context.Context, args IntentArgs) (string, string, error)
• func BuildAndSignRegisterIntent(ctx context.Context, args IntentArgs) (string, string, extension.Extension, error)
• type BaseArgs
• type BatchTxRes
  • func CollaborativeExit(ctx context.Context, args CollaborativeExitArgs, opts ...Option) (*BatchTxRes, error)
  • func JoinBatch(ctx context.Context, args JoinBatchArgs, opts ...Option) (*BatchTxRes, error)
  • func RedeemNotes(ctx context.Context, args RedeemNotesArgs, opts ...Option) (*BatchTxRes, error)
  • func Settle(ctx context.Context, args SettleArgs, opts ...Option) (*BatchTxRes, error)
• type CollaborativeExitArgs
• type IntentArgs
• type JoinBatchArgs
• type Option
  • func WithCancelCh(ch <-chan struct{}) Option
  • func WithEventsCh(ch chan<- any) Option
  • func WithExpiryThreshold(threshold int64) Option
  • func WithExtraSigner(signerSessions ...tree.SignerSession) Option
  • func WithHandler(handler batchsessionhandler.Handler) Option
  • func WithRecoverableVtxos() Option
  • func WithRetries(num int) Option
  • func WithoutTreeSigner() Option
• type RedeemNotesArgs
• type SettleArgs

Variables

var WithSubDustVtxos = WithRecoverableVtxos

name alias, sub-dust vtxos are recoverable vtxos

Functions

func BuildAndSignDeleteIntent

func BuildAndSignDeleteIntent(ctx context.Context, args IntentArgs) (string, string, error)

BuildAndSignDeleteIntent builds and signs an intent message used to withdraw a previously registered intent from the server's pending batch. It does NOT submit the request — the caller is responsible for sending it.

func BuildAndSignGetPendingTxIntent

func BuildAndSignGetPendingTxIntent(ctx context.Context, args IntentArgs) (string, string, error)

BuildAndSignGetPendingTxIntent builds and signs an intent message used to fetch a pending offchain transaction for the provided vtxos. It does NOT submit the request — the caller is responsible for sending it.

func BuildAndSignRegisterIntent

func BuildAndSignRegisterIntent(
	ctx context.Context, args IntentArgs,
) (string, string, extension.Extension, error)

BuildAndSignRegisterIntent builds and signs an intent to be registered for joining a batch

Types

type BaseArgs

type BaseArgs struct {
	Notes         []string
	Vtxos         []clientlib.Vtxo
	BoardingUtxos []clientlib.Utxo
	Outputs       []clientlib.Receiver
	SignTx        clientlib.SignFn
}

BaseArgs groups the inputs and outputs common to all batch-session operations (Settle, CollaborativeExit, RedeemNotes, JoinBatch) along with the SignTx callback used to sign the intent proof PSBT and any forfeit / commitment artifacts produced during the batch.

type BatchTxRes

type BatchTxRes struct {
	CommitmentTxid string
	CommitmentTx   string
	IntentTx       string
	ForfeitTxs     []string
	VtxoInputs     []clientlib.Vtxo
	UtxoInputs     []clientlib.Utxo
	VtxoOutputs    []clientlib.Vtxo
	UtxoOutputs    []clientlib.Receiver
	Extension      extension.Extension
}

BatchTxRes is the result of a completed batch session. CommitmentTxid and CommitmentTx identify the on-chain commitment transaction the server broadcasts; IntentTx is the signed intent proof PSBT that registered this participant; ForfeitTxs are the signed forfeit transactions for spent vtxos; VtxoInputs / UtxoInputs record the consumed inputs and VtxoOutputs / UtxoOutputs the produced offchain vtxos and on-chain receivers. Extension carries any asset packet attached to the batch.

func CollaborativeExit

func CollaborativeExit(
	ctx context.Context, args CollaborativeExitArgs, opts ...Option,
) (*BatchTxRes, error)

CollaborativeExit performs the full lifecycle of an on-chain exit through a batch session: selects vtxos to fund the on-chain output, builds, signs, and submits the intent, and then joins the batch session.

func JoinBatch

func JoinBatch(ctx context.Context, args JoinBatchArgs, opts ...Option) (*BatchTxRes, error)

JoinBatch joins a batch session whose intent has already been registered with the server. It subscribes to the batch event stream, drives the per-participant signing flow (tree signing, forfeit signing, commitment-tx signing), and returns the finalized batch result on success.

Callers normally use Settle, CollaborativeExit, or RedeemNotes — those orchestrators take care of registering the intent and retrying on transient failures before delegating to JoinBatch.

func RedeemNotes

func RedeemNotes(
	ctx context.Context, args RedeemNotesArgs, opts ...Option,
) (*BatchTxRes, error)

RedeemNotes performs the full lifecycle of redeeming one or more notes into a fresh vtxo via a batch session: builds, signs, submits the register intent, handles batch events, and finalizes the commitment transaction via JoinBatch.

func Settle

func Settle(ctx context.Context, args SettleArgs, opts ...Option) (*BatchTxRes, error)

Settle performs the full lifecycle of refreshing vtxos and/or boarding utxos into a new vtxo via a batch session: selects funds, then builds, signs, submits the register intent, handles batch events, and finalizes the commitment transaction via JoinBatch.

type CollaborativeExitArgs

type CollaborativeExitArgs struct {
	Client       clientlib.Client
	ServerParams clientlib.ServerParams
	SignTx       clientlib.SignFn
	Vtxos        []clientlib.Vtxo
	Receiver     clientlib.Receiver
	ChangeAddr   string
}

CollaborativeExitArgs configures a CollaborativeExit call: the Vtxos to spend and the on-chain Receiver to credit. FeeEstimator is used to size the on-chain output, SignTx signs the intent proof, and ServerParams/Client are used to talk to the server.

type IntentArgs

type IntentArgs struct {
	BaseArgs
	Cosigners []string
}

IntentArgs configures the BuildAndSign*Intent primitives (Register, Delete, GetPendingTx). Cosigners holds the public keys of vtxo-tree signer sessions and is only required when registering an intent that will participate in tree signing.

type JoinBatchArgs

type JoinBatchArgs struct {
	BaseArgs
	TreeSigners  []tree.SignerSession
	IntentId     string
	Client       clientlib.Client
	ServerParams clientlib.ServerParams
}

JoinBatchArgs configures a JoinBatch call: the funds to consume (Notes/Vtxos/BoardingUtxos from BaseArgs), the desired Outputs, the SignTx callback used to sign the intent proof and ark-side artifacts, plus the Client used to talk to the server and the cached ServerParams.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option customizes the behavior of a batch-session operation (Settle, CollaborativeExit, RedeemNotes, JoinBatch). Use the With* helpers in this package to construct instances.

func WithCancelCh

func WithCancelCh(ch <-chan struct{}) Option

WithCancelCh allows to cancel the settlement process

func WithEventsCh

func WithEventsCh(ch chan<- any) Option

WithEventsCh registers a channel that receives a copy of every batch event observed by the session handler. Useful for tests or for surfacing progress to the caller. Can only be set once per session.

func WithExpiryThreshold

func WithExpiryThreshold(threshold int64) Option

WithExpiryThreshold overrides the default vtxo-expiry filter (in seconds): vtxos expiring later than the threshold are excluded from coin selection.

func WithExtraSigner

func WithExtraSigner(signerSessions ...tree.SignerSession) Option

WithExtraSigner allows to use a set of custom signer for the vtxo tree signing process

func WithHandler

func WithHandler(handler batchsessionhandler.Handler) Option

WithHandler allows to make use of a custom batch-event handler in place of the default one. Handler cannot be nil and can only be set once per session.

func WithRecoverableVtxos

func WithRecoverableVtxos() Option

WithRecoverableVtxos opts the session into spending sub-dust (recoverable) vtxos as inputs alongside regular vtxos.

func WithRetries

func WithRetries(num int) Option

WithRetries sets the maximum number of attempts to join a batch on transient failures. Must be in the range [1, maxRetries]. Can only be set once.

func WithoutTreeSigner

func WithoutTreeSigner() Option

WithoutTreeSigner disables the tree signer for the batch session

type RedeemNotesArgs

type RedeemNotesArgs struct {
	Client       clientlib.Client
	SignTx       clientlib.SignFn
	ServerParams clientlib.ServerParams
	Notes        []string
	ReceiverAddr string
}

RedeemNotesArgs configures a RedeemNotes call: the Notes to redeem and the ReceiverAddr that will receive the resulting vtxo. SignTx signs the intent proof, and Client/ServerParams are used to talk to the server.

type SettleArgs

type SettleArgs struct {
	Client        clientlib.Client
	ServerParams  clientlib.ServerParams
	SignTx        clientlib.SignFn
	BoardingUtxos []clientlib.Utxo
	Vtxos         []clientlib.Vtxo
	ReceiverAddr  string
}

SettleArgs configures a Settle call: the BoardingUtxos and Vtxos to settle into a fresh vtxo at ReceiverAddr. ExpiryThreshold (in seconds) filters out vtxos expiring later than the threshold. FeeEstimator sizes the change output; SignTx signs the intent proof; Client/ServerInfo are used to talk to the server.