ark-sdk-batch-session

name	ark-sdk-batch-session
description	Batch session event handling and round participation - joining rounds, signing trees, processing events

SDK Batch Session for Ark

When to Use

Use this skill when:

• Implementing round participation for Settle operations
• Handling batch session events (tree signing, nonces, finalization)
• Understanding the client-side round lifecycle
• Processing streaming events from the ASP
• Implementing custom batch event handlers
• Debugging round participation issues

Key Concepts

1. Batch Session Flow

┌─────────────────────────────────────────────────────────────────┐
│                    BATCH SESSION FLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. JoinBatchSession(intent) ──► Connects to ASP stream          │
│                          │                                       │
│                          ▼                                       │
│  2. BatchStarted ──► Receive batch parameters (round ID, etc.)  │
│                          │                                       │
│                          ▼                                       │
│  3. TreeSigningStarted ──► Receive unsigned VTXO tree           │
│                          │                                       │
│                          ▼                                       │
│  4. Create tree signer, generate nonces, send to server         │
│                          │                                       │
│                          ▼                                       │
│  5. TreeNoncesAggregated ──► Receive aggregated nonces          │
│                          │                                       │
│                          ▼                                       │
│  6. Sign tree with aggregated nonces, send partial sigs         │
│                          │                                       │
│                          ▼                                       │
│  7. BatchFinalization ──► Round is being finalized              │
│                          │                                       │
│                          ▼                                       │
│  8. BatchFinalized ──► Round complete, VTXOs created            │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

2. Batch States

State	Description
start	Initial state, waiting for batch to begin
batchStarted	Batch parameters received
treeSigningStarted	Tree received, ready for nonce generation
treeNoncesAggregated	Aggregated nonces received, ready for signing
batchFinalization	Signing complete, finalization in progress

3. Event Types

Event	Purpose
BatchStarted	Round initiated, contains batch ID and parameters
TreeSigningStarted	VTXO tree ready for signing
TreeNonces	Individual signer's nonces (for debugging)
TreeNoncesAggregated	Combined nonces from all signers
BatchFinalization	Round being committed on-chain
BatchFinalized	Round complete, commitment confirmed

Code Patterns

Pattern 1: BatchEventsHandler Interface

type BatchEventsHandler interface {
    // Called when batch starts - receive round parameters
    HandleBatchStarted(
        roundID string,
        unsignedVtxoTree *tree.TxTree,
        batchOutSweepTapscript []byte,
    ) error

    // Called when tree is ready for signing
    HandleTreeSigningStarted(
        cosigners []*btcec.PublicKey,
        unsignedVtxoTree *tree.TxTree,
    ) (nonces tree.TreeNonces, err error)

    // Called when all nonces are aggregated
    HandleTreeNoncesAggregated(
        aggregatedNonces tree.TreeNonces,
    ) (sigs tree.TreePartialSigs, err error)

    // Called during finalization
    HandleBatchFinalization(
        signedVtxoTree *tree.TxTree,
        connectorTxs []*wire.MsgTx,
        roundTx string,
    ) error

    // Called when batch is fully finalized
    HandleBatchFinalized(
        roundTxid string,
    ) error
}

Source: go-sdk/batch_session.go:26-53

Pattern 2: JoinBatchSession Function

func JoinBatchSession(
    ctx context.Context,
    arkClient client.TransportClient,  // gRPC/REST client
    handler BatchEventsHandler,         // Event handler
    intent client.Intent,               // User's settlement intent
) error {
    // Create batch event stream from server
    eventCh, err := arkClient.JoinBatchSession(ctx, intent)
    if err != nil {
        return err
    }

    // Current state in the state machine
    currentState := start

    // Process events from stream
    for event := range eventCh {
        if event.Err != nil {
            return event.Err
        }

        switch e := event.Event.(type) {
        case client.BatchStarted:
            // Handle batch start...
        case client.TreeSigningStarted:
            // Handle tree signing...
        // ... other events
        }
    }

    return nil
}

Source: go-sdk/batch_session.go:55-166

Pattern 3: State Machine Transitions

const (
    start                 = "start"
    batchStarted          = "batchStarted"
    treeSigningStarted    = "treeSigningStarted"
    treeNoncesAggregated  = "treeNoncesAggregated"
    batchFinalization     = "batchFinalization"
)

// Valid state transitions
switch currentState {
case start:
    // Can transition to: batchStarted
    if event is BatchStarted {
        currentState = batchStarted
    }

case batchStarted:
    // Can transition to: treeSigningStarted
    if event is TreeSigningStarted {
        currentState = treeSigningStarted
    }

case treeSigningStarted:
    // Can transition to: treeNoncesAggregated
    if event is TreeNoncesAggregated {
        currentState = treeNoncesAggregated
    }

case treeNoncesAggregated:
    // Can transition to: batchFinalization
    if event is BatchFinalization {
        currentState = batchFinalization
    }

case batchFinalization:
    // Terminal state - BatchFinalized ends the loop
}

Source: go-sdk/batch_session.go:57-165

Pattern 4: Handling BatchStarted Event

case client.BatchStarted:
    if currentState != start {
        return fmt.Errorf(
            "invalid state transition: %s -> batchStarted",
            currentState,
        )
    }

    // Parse the unsigned VTXO tree
    unsignedVtxoTree, err := tree.FromFlatTxTree(e.UnsignedVtxoTree)
    if err != nil {
        return err
    }

    // Notify handler
    if err := handler.HandleBatchStarted(
        e.RoundID,
        unsignedVtxoTree,
        e.BatchOutSweepTapscript,
    ); err != nil {
        return err
    }

    currentState = batchStarted

Source: go-sdk/batch_session.go:72-96

Pattern 5: Handling TreeSigningStarted Event

case client.TreeSigningStarted:
    if currentState != batchStarted {
        return fmt.Errorf(
            "invalid state transition: %s -> treeSigningStarted",
            currentState,
        )
    }

    // Parse cosigner public keys
    cosigners := make([]*btcec.PublicKey, 0, len(e.Cosigners))
    for _, c := range e.Cosigners {
        pubkeyBytes, _ := hex.DecodeString(c)
        pubkey, _ := schnorr.ParsePubKey(pubkeyBytes)
        cosigners = append(cosigners, pubkey)
    }

    // Parse unsigned tree
    unsignedVtxoTree, _ := tree.FromFlatTxTree(e.UnsignedVtxoTree)

    // Handler generates nonces
    nonces, err := handler.HandleTreeSigningStarted(cosigners, unsignedVtxoTree)
    if err != nil {
        return err
    }

    // Send nonces to server
    serializedNonces := serializeNonces(nonces)
    if err := arkClient.SendTreeNonces(ctx, e.RoundID, serializedNonces); err != nil {
        return err
    }

    currentState = treeSigningStarted

Source: go-sdk/batch_session.go:98-131

Pattern 6: Handling TreeNoncesAggregated Event

case client.TreeNoncesAggregated:
    if currentState != treeSigningStarted {
        return fmt.Errorf(
            "invalid state transition: %s -> treeNoncesAggregated",
            currentState,
        )
    }

    // Parse aggregated nonces
    aggregatedNonces := deserializeNonces(e.AggregatedNonces)

    // Handler signs the tree
    sigs, err := handler.HandleTreeNoncesAggregated(aggregatedNonces)
    if err != nil {
        return err
    }

    // Send partial signatures to server
    serializedSigs := serializeSigs(sigs)
    if err := arkClient.SendTreeSigs(ctx, e.RoundID, serializedSigs); err != nil {
        return err
    }

    currentState = treeNoncesAggregated

Source: go-sdk/batch_session.go:133-158

Pattern 7: Default Batch Events Handler

type defaultBatchEventsHandler struct {
    wallet              wallet.WalletService
    explorer            explorer.Explorer
    signerSession       tree.SignerSession
    batchOutSweepClosure []byte
    cosigners           []*btcec.PublicKey
    unsignedVtxoTree    *tree.TxTree
    signedVtxoTree      *tree.TxTree
    connectorTxs        []*wire.MsgTx
    roundTx             string
    roundTxid           string
}

func NewDefaultBatchEventsHandler(
    wallet wallet.WalletService,
    explorer explorer.Explorer,
) BatchEventsHandler {
    return &defaultBatchEventsHandler{
        wallet:   wallet,
        explorer: explorer,
    }
}

Source: go-sdk/batch_session.go:168-190

Pattern 8: Default Handler - BatchStarted

func (h *defaultBatchEventsHandler) HandleBatchStarted(
    roundID string,
    unsignedVtxoTree *tree.TxTree,
    batchOutSweepTapscript []byte,
) error {
    h.unsignedVtxoTree = unsignedVtxoTree
    h.batchOutSweepClosure = batchOutSweepTapscript
    return nil
}

Source: go-sdk/batch_session.go:192-200

Pattern 9: Default Handler - TreeSigningStarted

func (h *defaultBatchEventsHandler) HandleTreeSigningStarted(
    cosigners []*btcec.PublicKey,
    unsignedVtxoTree *tree.TxTree,
) (tree.TreeNonces, error) {
    ctx := context.Background()
    h.cosigners = cosigners
    h.unsignedVtxoTree = unsignedVtxoTree

    // Create a new tree signer session using the wallet
    signerSession, err := h.wallet.NewVtxoTreeSigner(ctx, "")
    if err != nil {
        return nil, err
    }
    h.signerSession = signerSession

    // Calculate batch output amount from tree root
    batchOutAmount := h.unsignedVtxoTree.Root.Outputs[0].Value

    // Initialize the signer session
    if err := signerSession.Init(
        h.batchOutSweepClosure,
        batchOutAmount,
        h.unsignedVtxoTree,
    ); err != nil {
        return nil, err
    }

    // Generate and return nonces
    return signerSession.GetNonces()
}

Source: go-sdk/batch_session.go:202-232

Pattern 10: Default Handler - TreeNoncesAggregated

func (h *defaultBatchEventsHandler) HandleTreeNoncesAggregated(
    aggregatedNonces tree.TreeNonces,
) (tree.TreePartialSigs, error) {
    // Set the aggregated nonces on the signer session
    h.signerSession.SetAggregatedNonces(aggregatedNonces)

    // Generate partial signatures for all tree transactions
    return h.signerSession.Sign()
}

Source: go-sdk/batch_session.go:234-243

Pattern 11: Default Handler - BatchFinalization

func (h *defaultBatchEventsHandler) HandleBatchFinalization(
    signedVtxoTree *tree.TxTree,
    connectorTxs []*wire.MsgTx,
    roundTx string,
) error {
    h.signedVtxoTree = signedVtxoTree
    h.connectorTxs = connectorTxs
    h.roundTx = roundTx
    return nil
}

Source: go-sdk/batch_session.go:245-255

Pattern 12: Default Handler - BatchFinalized

func (h *defaultBatchEventsHandler) HandleBatchFinalized(
    roundTxid string,
) error {
    h.roundTxid = roundTxid
    return nil
}

// Getter methods for results
func (h *defaultBatchEventsHandler) SignedVtxoTree() *tree.TxTree {
    return h.signedVtxoTree
}

func (h *defaultBatchEventsHandler) ConnectorTxs() []*wire.MsgTx {
    return h.connectorTxs
}

func (h *defaultBatchEventsHandler) RoundTx() string {
    return h.roundTx
}

func (h *defaultBatchEventsHandler) RoundTxid() string {
    return h.roundTxid
}

Source: go-sdk/batch_session.go:257-280

Pattern 13: Nonce Serialization

func serializeNonces(nonces tree.TreeNonces) map[string]string {
    result := make(map[string]string, len(nonces))
    for txid, nonce := range nonces {
        result[txid] = hex.EncodeToString(nonce.PubNonce[:])
    }
    return result
}

func deserializeNonces(serialized map[string]string) tree.TreeNonces {
    result := make(tree.TreeNonces, len(serialized))
    for txid, nonceHex := range serialized {
        nonceBytes, _ := hex.DecodeString(nonceHex)
        nonce := &tree.Musig2Nonce{}
        copy(nonce.PubNonce[:], nonceBytes)
        result[txid] = nonce
    }
    return result
}

Source: go-sdk/batch_session.go:282-310

Pattern 14: Signature Serialization

func serializeSigs(sigs tree.TreePartialSigs) map[string]string {
    result := make(map[string]string, len(sigs))
    for txid, sig := range sigs {
        result[txid] = hex.EncodeToString(sig.S[:])
    }
    return result
}

Source: go-sdk/batch_session.go:312-330

Pattern 15: Using Batch Session in Settle

// Inside arkClient.Settle():
func (a *arkClient) Settle(ctx context.Context, opts ...Option) (string, error) {
    // Create settlement intent
    intent := client.Intent{
        Inputs:  selectedCoins,
        Outputs: receivers,
    }

    // Create event handler
    handler := NewDefaultBatchEventsHandler(a.wallet, a.explorer)

    // Join the batch session and process all events
    if err := JoinBatchSession(ctx, a.client, handler, intent); err != nil {
        return "", err
    }

    // Get results from handler
    roundTxid := handler.RoundTxid()
    signedTree := handler.SignedVtxoTree()

    // Update local state with new VTXOs...

    return roundTxid, nil
}

Source: go-sdk/client.go:523-600 (conceptual - actual implementation in Settle)

File References

Purpose	File	Key Types/Functions
Batch session	go-sdk/batch_session.go	JoinBatchSession, BatchEventsHandler
Default handler	go-sdk/batch_session.go	defaultBatchEventsHandler, NewDefaultBatchEventsHandler
Transport client	go-sdk/client/interface.go	TransportClient, Intent
Event types	go-sdk/client/types.go	BatchStarted, TreeSigningStarted, etc.
Tree nonces	arkd/pkg/ark-lib/tree/musig2.go	TreeNonces, TreePartialSigs
Signer session	arkd/pkg/ark-lib/tree/musig2.go	SignerSession
Wallet service	go-sdk/wallet/wallet.go	WalletService, NewVtxoTreeSigner

Common Operations

Operation 1: Basic Settlement with Batch Session

// The Settle function internally uses JoinBatchSession
txid, err := client.Settle(ctx)
if err != nil {
    return err
}
fmt.Printf("Settled in round: %s\n", txid)

Operation 2: Custom Batch Events Handler

type myHandler struct {
    *defaultBatchEventsHandler
    onProgress func(state string)
}

func (h *myHandler) HandleBatchStarted(
    roundID string,
    unsignedVtxoTree *tree.TxTree,
    batchOutSweepTapscript []byte,
) error {
    h.onProgress("batch_started")
    return h.defaultBatchEventsHandler.HandleBatchStarted(
        roundID, unsignedVtxoTree, batchOutSweepTapscript,
    )
}

// Use custom handler
handler := &myHandler{
    defaultBatchEventsHandler: NewDefaultBatchEventsHandler(wallet, explorer),
    onProgress: func(state string) {
        log.Printf("Progress: %s", state)
    },
}

Operation 3: Monitoring Batch Progress

type progressHandler struct {
    BatchEventsHandler
    states []string
}

func (h *progressHandler) HandleBatchStarted(...) error {
    h.states = append(h.states, "started")
    return h.BatchEventsHandler.HandleBatchStarted(...)
}

func (h *progressHandler) HandleTreeSigningStarted(...) (tree.TreeNonces, error) {
    h.states = append(h.states, "signing")
    return h.BatchEventsHandler.HandleTreeSigningStarted(...)
}

// After JoinBatchSession completes:
fmt.Printf("States traversed: %v\n", handler.states)

Operation 4: Error Handling in Batch Session

err := JoinBatchSession(ctx, arkClient, handler, intent)
if err != nil {
    switch {
    case strings.Contains(err.Error(), "invalid state transition"):
        // Server sent events out of order - bug or network issue
        log.Error("Protocol violation - out of order events")
    case strings.Contains(err.Error(), "context canceled"):
        // Client canceled the operation
        log.Info("Batch session canceled by user")
    case strings.Contains(err.Error(), "round failed"):
        // Round was aborted by server
        log.Warn("Round failed - will retry in next round")
    default:
        log.Errorf("Batch session error: %v", err)
    }
}

Gotchas & Edge Cases

1. State Machine Ordering: Events MUST arrive in order: BatchStarted → TreeSigningStarted → TreeNoncesAggregated → BatchFinalization → BatchFinalized. Out-of-order events cause errors.

2. Single Round Per Session: Each JoinBatchSession call participates in exactly ONE round. For multiple rounds, call it multiple times.

3. Nonce Security: Nonces generated in HandleTreeSigningStarted contain secret data. The signer session manages this internally - don't expose the secret nonce.

4. Aggregated Nonces Required: You CANNOT sign until you receive TreeNoncesAggregated. Attempting to sign earlier will fail.

5. Handler Reuse: Don't reuse a defaultBatchEventsHandler across multiple rounds. Create a fresh handler for each round.

6. Context Cancellation: If the context is canceled mid-session, the round continues server-side. Your VTXOs may still be locked in that round.

7. Tree Validation: The signed tree in BatchFinalization should be validated before storing. Use tree.ValidateTreeSigs().

8. Connector Transactions: connectorTxs in BatchFinalization are used for connector tree spending. Store them if you need to trace fund flow.

9. Round Failures: If any signer fails to respond, the round may be aborted. Handle round failed errors gracefully.

10. Concurrent Settling: Don't call Settle concurrently from the same wallet. The wallet's signer session is not thread-safe for concurrent rounds.

---

Skill Owner: ark-developer Repos: go-sdk