Rounds Management

​

What are Rounds?

1. Collects payment requests from multiple users
2. Constructs a shared VTXO tree
3. Creates an on-chain funding transaction
4. Issues new VTXOs to participants

​

Round Lifecycle

​

States

​

Phases

​

1. Attempt Initiation (< 1ms)

• Generate one-time cosign key
• Generate round attempt challenge
• Broadcast RoundAttempt event to clients

RoundAttempt {
    round_seq: 123456,
    attempt_seq: 0,
    challenge: [random bytes],
}

​

2. Receiving Payments (default: 2 seconds)

SubmitPaymentRequest {
    inputs: [VtxoIdInput],      // VTXOs to spend
    outputs: [SignedVtxoRequest], // New VTXOs to create
    unlock_preimage: bytes,      // For tree signing
}

• ✅ VTXOs exist and are unspent
• ✅ User owns input VTXOs (ownership proof)
• ✅ Input amount ≥ output amount + fees
• ✅ Output amounts ≥ dust limits
• ✅ Correct number of nonces provided

• Interactive: User submits during this phase (requires signatures)
• Non-Interactive (hArk): Pre-registered participations from database

​

3. Constructing VTXO Tree (< 100ms)

• Aggregate all outputs into a VTXO tree structure
• Add dummy VTXOs if needed (minimum 2 leaves)
• Calculate aggregate nonces for each internal node
• Build round funding transaction
• Lock wallet UTXO for round input

        Root (funding UTXO)
           /     \
       Node1     Node2
      /    \    /    \
   VTXO1 VTXO2 VTXO3 VTXO4

​

4. Sending VTXO Proposal (< 10ms)

VtxoProposal {
    round_seq: 123456,
    attempt_seq: 0,
    unsigned_round_tx: Transaction,
    vtxos_spec: VtxoTreeSpec,
    cosign_agg_nonces: Vec<AggregatedNonce>,
}

​

5. Receiving VTXO Signatures (default: 2 seconds)

SubmitVtxoSignaturesRequest {
    cosign_pubkey: bytes,
    signatures: [PartialSignature],
}

• ✅ Pubkey is a participant in this round
• ✅ Correct number of signatures
• ✅ Signatures verify against aggregate nonces

1. Ban non-signing users from this round
2. Restart from phase 2 with remaining users
3. Reuse the same round funding UTXO
4. Increment attempt_seq

​

6. Combining Signatures (< 50ms)

• Aggregate all partial signatures
• Verify combined signatures
• Finalize VTXO tree with witnesses

​

7. Signing On-chain Transaction (< 100ms)

• Sign round funding transaction with BDK wallet
• Commit wallet state (marks UTXOs as spent)
• Persist wallet changeset to database

​

8. Broadcasting (< 500ms)

• Submit signed transaction to Bitcoin network
• Broadcast RoundFinished event to clients:

RoundFinished {
    round_seq: 123456,
    attempt_seq: 0,
    cosign_sigs: Vec<Signature>,
    signed_round_tx: Transaction,
}

​

9. Persisting (< 500ms)

• Store round record to database
• Mark input VTXOs as spent
• Insert new output VTXOs
• Store virtual transactions
• Update round participations

​

Round Results

• Success: Round completed and broadcast
• Empty: No payments received, round skipped
• Abandoned: All retries exhausted, no signers left
• Error: Fatal error occurred (database, wallet, etc.)

​

Configuration

​

Timing Parameters

# How often to start new rounds
round_interval = "10s"

# Time for users to submit payments
round_submit_time = "2s"

# Time for users to submit signatures
round_sign_time = "2s"

​

Capacity Parameters

# Maximum VTXO tree size = 4^nb_round_nonces
nb_round_nonces = 8  # = 65,536 max VTXOs per round

# Maximum VTXO amount (optional)
# max_vtxo_amount = "1000000 sat"

​

Forfeit Parameters

# How long to store forfeit nonces
round_forfeit_nonces_timeout = "30s"

​

Monitoring Rounds

​

Admin RPC

captaind -C config.toml rpc trigger-round

​

Logs

{"msg":"RoundStarted","round_seq":123456}
{"msg":"ReceivedRoundPayments","round_seq":123456,"input_count":5,"output_count":8}
{"msg":"SendVtxoProposal","round_seq":123456,"attempt_seq":0}
{"msg":"ReceivedRoundVtxoSignatures","round_seq":123456,"attempt_seq":0}
{"msg":"BroadcastRoundFundingTx","round_seq":123456,"txid":"abc123..."}
{"msg":"RoundFinished","round_seq":123456,"attempt_seq":0}

​

Metrics

• bark_round_seq: Current round sequence number
• bark_round_state: Current round state (enum)
• bark_round_attempt: Current attempt within round
• bark_round_input_volume: Total input sats
• bark_round_input_count: Number of input VTXOs
• bark_round_output_count: Number of output VTXOs
• bark_round_step_duration: Time spent in each phase

​

Round Events Stream

rpc ListenRoundEvents(ListenRoundEventsRequest) 
    returns (stream RoundEvent);

1. Attempt: Round started, provides challenge
2. VtxoProposal: VTXO tree proposed
3. Finished: Round completed with transaction

if let Some(last_event) = server.rounds.last_event() {
    stream.send(last_event).await?;
}
while let Some(event) = events.recv().await {
    stream.send(event).await?;
}

​

Common Issues

​

Empty Rounds

• No users connected
• Users not submitting payments
• Round interval too short for users to prepare

• Increase round_interval
• Check client connectivity
• Verify users have spendable VTXOs

​

Abandoned Rounds

• All users failed to sign
• Network issues preventing signature delivery
• Client bugs

• Increase round_sign_time
• Check server network latency
• Update client software

​

Slow Rounds

• Database slow (many VTXOs)
• Large VTXO tree (many outputs)
• Slow Bitcoin Core RPC

• Optimize PostgreSQL (indexes, vacuum)
• Reduce nb_round_nonces
• Use faster hardware (SSD)
• Reduce max_output_vtxos

​

Failed Broadcasts

• Bitcoin Core connectivity issues
• Transaction rejected (fees, conflicts)
• Mempool full

• Check Bitcoin Core logs
• Verify round tx meets policy rules
• Increase fee rates
• Wait and let TX Nursery rebroadcast

​

Advanced Topics

​

Non-Interactive Participations (hArk)

SELECT * FROM round_participation 
WHERE round_id IS NULL;  -- Pending participations

• Async payments when user offline
• Server-initiated rebalancing
• Automated liquidity management

​

Round Sequence Numbers

let epoch = UNIX_EPOCH + Duration::from_secs(1741015334);
let round_seq = SystemTime::now().duration_since(epoch).unwrap().as_secs();

• Globally unique (assuming server time is accurate)
• Sortable
• Human-readable (Unix timestamp offset)

​

Forfeit Nonces

forfeit_nonces: Mutex<TimedEntryMap<VtxoId, HarkForfeitNonces>>

​

Wallet UTXO Locking

pub struct WalletUtxoGuard {
    utxo: OutPoint,
    wallet: Arc<Mutex<PersistedWallet>>,
}

impl Drop for WalletUtxoGuard {
    fn drop(&mut self) {
        // Unlock UTXO when guard is dropped
    }
}

​

Best Practices