replayEvents

Replays blockchain events into this DustLocalState to sync wallet state.

What is Event Replay? When DustRegistration transactions are applied to the blockchain, the ledger emits events (DustInitialUtxo, DustSpendProcessed, etc.). Replaying these events into DustLocalState syncs the wallet with the blockchain.

Event Flow:

1. Submit DustRegistration transaction to blockchain

2. Blockchain emits DustInitialUtxo event

3. Call replayEvents() with these events

4. DustLocalState now tracks the new dust UTXO

5. Balance increases as dust accumulates over time

Event Format: Events must be SCALE-encoded as Vec<Event<InMemoryDB>> from midnight-ledger, then hex-encoded. This matches how events are transmitted from the blockchain.

Usage:

val state = DustLocalState.create()!!
try {
    // Get events from blockchain (hex-encoded SCALE bytes)
    val eventsHex = "0x..." // From blockchain indexer

    // Replay events to sync wallet
    val newState = state.replayEvents(seed, eventsHex)

    if (newState != null) {
        // Use new state (old state is now invalid)
        state.close()

        // Check new balance
        val balance = newState.getBalance(System.currentTimeMillis())
        println("New balance: $balance Specks")

        newState.close()
    }
} finally {
    if (!state.isClosed()) state.close()
}

Important:

• This method returns a NEW DustLocalState instance

• The old state (this instance) becomes invalid after replay

• You MUST close both the old state and the new state

• Events are immutable - replay returns a new state rather than mutating

Error Handling: Returns null if:

• State is closed

• Seed is invalid (not 32 bytes)

• Events hex is malformed

• Event deserialization fails

• Event replay fails (e.g., non-linear insertion)

Parameters