Rust execution source

Bridge Source Trace

Commit-pinned Rust and bridge-doc anchors for the current withdrawal path: kernel effects, proposal assembly, sequencer authorization, public Nockchain submission, confirmation polling, orphan retry, journal continuity, kernel reconciliation, and opt-in bridge-dev scenario evidence.

Source API Bridge Trace

Commit

33ba97b1e206

Source Anchors

Execution Flow

Signals

Source Anchors

bridge-withdrawals-spec

Bridge withdrawals spec

Canonical bridge withdrawal spec for peer-canonical proposals, sequencer authorization, submission, confirmation, and kernel reconciliation.

file

crates/bridge/docs/bridge-withdrawals.md

symbols

bridge-withdrawals, peer-canonical, kernel reconciliation

lineRange

L199-L280

receiptFields

withdrawalId, proposalHash, sequencerState, confirmedHeight, confirmedBlockId, kernelReconciliationStatus

Upstream source

runtime-loop-bootstrap

Runtime loop bootstrap

Bootstraps withdrawal restore and starts activation-gated assembly, signing, and submission loops.

file

crates/bridge/src/withdrawal/runtime.rs

symbols

bootstrap_runtime, spawn_runtime_loops, WithdrawalRuntimeContext

lineRange

L25-L101

receiptFields

withdrawalActivationCutoff, activationRestored, assemblyLoopStarted, signingLoopStarted, submissionLoopStarted

Upstream source

execution-driver-effects

Execution driver effects

Consumes withdrawal-related kernel effects and converts them into durable Rust proposal state, peer broadcasts, or local stop on durable conflict.

file

crates/bridge/src/withdrawal/assembly.rs

symbols

create_withdrawal_execution_driver, WithdrawalExecutionEffect

lineRange

L529-L789

receiptFields

withdrawalProposalBuilt, withdrawalTxSigned, baseBlockWithdrawalsPending, acceptedPeers, canonicalized, localStopReason

Upstream source

assembly-tick

Assembly tick

Selects the next stageable withdrawal, enforces deterministic proposer ownership, refreshes the bridge note snapshot, subtracts sequencer-reserved inputs, and asks the kernel to build a proposal.

file

crates/bridge/src/withdrawal/assembly.rs

symbols

withdrawal_assembly_tick_once, WithdrawalAssemblyTickOutcome

lineRange

L864-L940

receiptFields

withdrawalId, withdrawalEpoch, selectedInputs, snapshotHeight, snapshotBlockId, reservedInputNames

Upstream source

submission-tick

Submission tick

Bridge-side tick registers the sequencer frontier, authorizes fully signed peer-canonical proposals, and asks the sequencer to submit authorized proposals.

file

crates/bridge/src/withdrawal/submission.rs

symbols

withdrawal_submission_tick_once, WithdrawalSubmissionTickOutcome

lineRange

L660-L796

receiptFields

sequencerAuthorizationState, commitCertificate, mempoolAccepted, frontierNonce, callerNodeId

Upstream source

public-submitter

Public Nockchain submitter

Submits authorized raw transactions through the public Nockchain API and separately checks tx acceptance, block inclusion, and tip height.

file

crates/bridge/src/withdrawal/submission.rs

symbols

PublicNockchainWithdrawalSubmitter, WithdrawalSubmitPort

lineRange

L380-L611

receiptFields

publicApiEndpoint, submittedRawTxId, txAccepted, includedBlock, tipHeight

Upstream source

confirmation-loop

Sequencer confirmation loop

Sequencer-owned confirmation poll checks included block and current tip height, then records confirmed lifecycle state when confirmation depth is satisfied.

file

crates/bridge/src/withdrawal/submission.rs

symbols

withdrawal_sequencer_confirmation_tick_once, run_withdrawal_sequencer_confirmation_loop

lineRange

L849-L949

receiptFields

confirmedHeight, confirmedBlockId, includedHeight, includedBlockId, confirmationDepth

Upstream source

orphan-retry-loop

Orphan retry loop

Resubmits exact authorized raw transactions for stale mempool-accepted withdrawals that have not appeared in an included block.

file

crates/bridge/src/withdrawal/submission.rs

symbols

withdrawal_sequencer_orphan_retry_tick_once, run_withdrawal_sequencer_orphan_retry_loop

lineRange

L951-L1076

receiptFields

retryAfterBaseBlocks, lastSubmitAttemptBaseHeight, mempoolRetryAttempted, retryError, submittedRawTxId

Upstream source

sequencer-rpc-service

Sequencer RPC service

API-node-hosted private sequencer RPC service that validates caller turn, Base withdrawal facts, and submission retry windows.

file

crates/bridge/src/withdrawal/sequencer/rpc.rs

symbols

WithdrawalSequencerRpcService, register_withdrawal

lineRange

L92-L230

receiptFields

sequencerEndpoint, callerNodeId, expectedProposer, baseWithdrawalVerified, handoffWindowBlocks

Upstream source

sequencer-store

Sequencer store

SQLite projection plus journal-backed sequencer state for ordered withdrawals, reserved inputs, authorization, submit outcome, mempool acceptance, retries, and confirmation.

file

crates/bridge/src/withdrawal/sequencer/store.rs

symbols

WithdrawalSequencerStore, sequencer_authorize_proposal, record_tx_confirmed

lineRange

L437-L940

receiptFields

singleFlightWithdrawal, reservedInputNames, withdrawalNonce, proposalHash, sequencerState, confirmedHeight, confirmedBlockId

Upstream source

sequencer-journal

Sequencer journal

Append-only journal record identity for sequencer events, previous-event linkage, record hashes, optional signature, and event type.

file

crates/bridge/src/withdrawal/sequencer/journal.rs

symbols

SequencerJournalRecord, SequencerJournalEventType, SequencerJournal

lineRange

L28-L123

receiptFields

sequencerJournalId, journalSequence, previousEventId, recordHash, eventType, signature

Upstream source

bridge-dev-scenario-readme

Bridge-dev scenario README

Ignored bridge-dev scenarios run against fresh Tenderly VNET state and release-built bridge binaries; they are opt-in external-state fixtures, not default CI.

file

crates/bridge-dev/tests/README.md

symbols

bridge-dev Scenario Tests, BRIDGE_DEV_RUN_E2E, BRIDGE_R2_RUN_E2E

lineRange

L1-L66

receiptFields

scenarioName, scenarioRunRootHash, scenarioPortOffset, tenderlyVnetId, bridgeDevRunE2e, r2JournalEventPrefixHash, scenarioArtifactHash

Upstream source

bridge-dev-withdrawal-scenarios

Bridge-dev withdrawal scenarios

Opt-in withdrawal scenarios cover happy path execution, bridge restart, sequencer restart, R2 journal replay after SQLite wipe, full bridge downtime recovery, and degraded two-node execution.

file

crates/bridge-dev/tests/scenarios.rs

symbols

withdrawal_happy_path_reaches_executed, withdrawal_sequencer_rebuilds_from_r2_after_sqlite_wipe, two_node_degraded_withdrawal_still_executes

lineRange

L953-L1125

receiptFields

withdrawalScenarioPhase, proposalHash, authorizedTransactionName, sequencedState, handoffOwner, scenarioRecoveryMode, componentStopSet

Upstream source

withdrawal-kernel-port

Withdrawal kernel port

Typed Rust boundary for poking create-withdrawal-tx/sign-tx and peeking/acking Base withdrawal state in the Hoon bridge kernel.

file

crates/bridge/src/withdrawal/assembly.rs

symbols

WithdrawalKernelPort, BridgeRuntimeHandle

lineRange

L70-L162

receiptFields

baseBlockWithdrawalsPending, baseBlockWithdrawalsCommitted, createWithdrawalTx, signTx, kernelProjectionCursor

Upstream source

Execution Flow

base-burn-pending

Base burn becomes pending withdrawal

Base burn events become kernel-tracked withdrawal requests keyed by as_of Base hash and base_event_id.

sourceAnchorId

bridge-withdrawals-spec

receiptImplication

Record Base tx/log identity, lock root, base_event_id, base_batch_end, and kernel pending/commit ack.

kernel-effects-to-driver

Kernel effects enter Rust driver

Withdrawal kernel effects are decoded and persisted by Rust before peer or sequencer state advances.

sourceAnchorId

execution-driver-effects

receiptImplication

Record the effect type and durable persistence outcome before treating a proposal as live.

assembly-builds-proposal

Assembly builds proposal

A deterministic proposer uses safe snapshot data and sequencer-reserved-input context to request a kernel-built proposal.

sourceAnchorId

assembly-tick

receiptImplication

Bind proposal hash to snapshot height/block id, selected inputs, and reserved-input exclusions.

peer-canonical-not-submit-ready

Peer canonical is not submit-ready

Peer canonicalization fixes a proposal hash, but sequencer authorization is still required before submission.

sourceAnchorId

sequencer-store

receiptImplication

Do not mark a withdrawal submit-ready unless sequencerState is authorized or later.

sequencer-authorizes

Sequencer authorizes

The bridge-side submission tick asks the sequencer to authorize a fully signed canonical proposal.

sourceAnchorId

submission-tick

receiptImplication

Record commit certificate, caller node id, sequencer endpoint, and authorization state.

sequencer-submits

Sequencer submits

The sequencer submits the exact authorized raw transaction through the colocated public Nockchain API.

sourceAnchorId

public-submitter

receiptImplication

Record submittedRawTxId and txAccepted separately from confirmed block evidence.

sequencer-confirms

Sequencer confirms

The confirmation loop records confirmed lifecycle state only after included block and tip-depth checks.

sourceAnchorId

confirmation-loop

receiptImplication

Record confirmedHeight, confirmedBlockId, includedHeight, tipHeight, and confirmationDepth.

kernel-reconciles

Kernel reconciles

Kernel reconciliation independently checks counterpart identity, destination, and amount bounds after Nockchain settlement.

sourceAnchorId

bridge-withdrawals-spec

receiptImplication

Record kernelReconciliationStatus in addition to sequencer confirmation.

Trace Contract

required

nockchainCommit, nockchainBuild, upstreamFile, upstreamSymbol, lineRange, withdrawalId, baseEventId, proposalHash, sequencerState, journalEventId, confirmationEvidence

forbidden

rawTransactionJam, sequencerJournalSigningKey, tenderlyAccessKey, r2TestToken, rawAuthorizedRawTx, sequencerObjectStoreSecret, bridgeNodePrivateKey, walletSeedPhrase, walletPrivateKey, tenderlyTestPrivateKey, r2AccessKeyId, r2SecretAccessKey, sequencerJournalObjectStoreSecretAccessKey, bridgeDevOwnerPrivateKey, rawTenderlyVnetEnv, rawScenarioStdout, rawScenarioStderr, rawR2JournalObject

rule

Use bridge docs and current bridge Rust source for bridge-specific operational claims.

rule

Treat peer-canonical as a proposal-hash agreement, not submission authorization.

rule

Treat tx-accepted as diagnostic and submitted as advisory until confirmation depth is observed.

rule

Treat sequencer journal records as append-only metadata; never publish signing keys or object-store secrets.

rule

Keep kernel reconciliation separate from sequencer confirmation evidence.

rule

Bridge-dev scenarios are opt-in external-state fixtures, not default CI proof.

Operator Invariants

peer-canonical is not submit-ready

submitted is advisory until confirmation depth

sequencer journal secrets never enter receipts

reserved inputs are sequencer-owned until confirmed settlement

kernel reconciliation is separate from sequencer confirmation

External Scenario Contract

command

cargo test -p bridge-dev --test scenarios -- --ignored --test-threads=1

buildCommand

cargo build --release -p bridge -p nockchain-bridge-sequencer -p nockchain-wallet

requiredEnv

BRIDGE_DEV_RUN_E2E, TENDERLY_ACCESS_KEY, TENDERLY_ACCOUNT_ID, TENDERLY_PROJECT_SLUG, TENDERLY_TEST_PRIVATE_KEY

optionalEnv

BRIDGE_DEV_E2E_PORT_OFFSET, BRIDGE_DEV_TEST_RUN_ROOT, BRIDGE_DEV_PORT_OFFSET, BRIDGE_DEV_FAKENET_GENESIS_JAM, BRIDGE_DEV_FAKENET_POW_LEN, BRIDGE_DEV_FAKENET_LOG_DIFFICULTY, BRIDGE_DEV_BASE_BLOCKS_CHUNK, BRIDGE_NOCK_OBSERVER_POLL_MILLIS, BRIDGE_DEV_BRIDGE_SAVE_INTERVAL_MILLIS

r2Env

BRIDGE_R2_RUN_E2E, BRIDGE_R2_TEST_URL, BRIDGE_R2_TEST_ENDPOINT, BRIDGE_R2_TEST_BUCKET, BRIDGE_R2_TEST_REGION, BRIDGE_R2_TEST_PREFIX, BRIDGE_R2_TEST_TOKEN, BRIDGE_R2_TEST_ACCESS_KEY_ID, BRIDGE_R2_TEST_SECRET_ACCESS_KEY, BRIDGE_R2_KEEP_OBJECTS

scenarioIds

fresh-vnet-boot, deposit-happy-path, deposit-downtime-recovery, all-bridge-restart-after-deposit, multiple-deposits, withdrawal-happy-path, withdrawal-ready-restart, withdrawal-submitted-sequencer-restart, withdrawal-r2-sequencer-recovery, withdrawal-bridge-downtime, two-node-degraded-withdrawal, two-node-degraded-deposit

receiptSafeFields

scenarioName, scenarioRunId, scenarioRunRootHash, scenarioPortOffset, componentStopSet, withdrawalScenarioPhase, proposalHash, authorizedTransactionName, sequencedState, handoffOwner, scenarioRecoveryMode, r2JournalIdHash, r2JournalEventPrefixHash, scenarioArtifactHash

forbiddenFields

tenderlyAccessKey, tenderlyTestPrivateKey, r2TestToken, r2AccessKeyId, r2SecretAccessKey, sequencerJournalObjectStoreSecretAccessKey, bridgeDevOwnerPrivateKey, rawTenderlyVnetEnv, rawScenarioStdout, rawScenarioStderr, rawR2JournalObject, rawAuthorizedRawTx

Bridge-dev scenarios are opt-in external-state fixtures, not default CI proof.

A passing scenario can support integration evidence only with commit, release build, command, env gate, and artifact hashes.

Tenderly, R2, wallet, owner, sequencer journal, and raw transaction secrets stay outside public receipts.

R2-backed recovery evidence should publish hashed journal ids or prefixes, never raw object keys with credentials.

Upstream Signals

PR #127

bridge: add end-to-end withdrawal execution

Introduced the current bridge withdrawal execution path that this source trace maps into Nocksperimental receipt fields.

status

merged

PR #126

nockchain-bench: Potential future benchmark evidence source for bridge/runtime performance receipts.

Evidence Links

bridgeTrace

https://nocksperimental.com/api/nockchain/bridge

rustAtlas

https://nocksperimental.com/api/nockchain/rust-atlas

sourceDriftCheck

npm run check:nockchain-bridge-source-drift -- --json

bridgePr127

https://github.com/nockchain/nockchain/pull/127

bridgeDevScenarios

https://github.com/nockchain/nockchain/blob/33ba97b1e206dd89b15c61b72b7802caf2136c18/crates/bridge-dev/tests/README.md

bridgeDocs

https://github.com/nockchain/nockchain/blob/33ba97b1e206dd89b15c61b72b7802caf2136c18/crates/bridge/docs/bridge-withdrawals.md

Next Uses

Attach bridge sourceAnchorId fields to Launch Evidence bridge withdrawal receipts.

Use the sequencer journal fields to distinguish append-only lifecycle metadata from raw transaction artifacts.

Add bridge support-bundle checks for peer-canonical, authorized, mempool-accepted, confirmed, and kernel-reconciled states.

Use bridge-dev scenario receipts only as opt-in external-state evidence with redacted Tenderly/R2 fields and hashed artifacts.

Monitor PR #126 for benchmark evidence that could extend bridge runtime performance receipts.