Rust source anchors

Nockchain Rust Source Guide

Exact upstream Rust files, symbols, line ranges, cargo gates, receipt fields, and forbidden raw artifacts for learning Nockchain as source code instead of only as crate names.

Source API Rust Atlas Runtime Safety NockApp Source

Domains

Source Anchors

Commit

33ba97b1e206

Release

build-33ba97b1e206dd89b15c61b72b7802caf2136c18

Learning Path

node-runtime

Start from node and miner entrypoints so fakenet evidence has process, key, and build context.

nockchain-node-main, mining-key-config

p2p-sync-gossip

Learn sync state before diagnosing no peers, empty route tables, or wrong block commitments.

libp2p-catch-up-signal, libp2p-gossip-suppression, libp2p-driver-gossip-metric

nockapp-runtime

Separate poke, peek, and effect evidence before interpreting NockApp lab output.

nockapp-poke-peek

pma-durability

Treat PMA and state jams as provenance metadata, never as raw artifacts to persist.

nockapp-snapshot-safety, pma-open-growth

wallet-cli

Connect wallet commands, transaction planning, and endpoint mode to balance and withdrawal receipts.

wallet-cli-commands, wallet-create-tx-with-planner, wallet-tx-planner

bridge-withdrawal

Map withdrawal lifecycle evidence into bridge and VESL receipts without leaking raw transactions or signing keys.

bridge-withdrawal-runtime, bridge-sequencer-journal

bridge-dev-scenarios

Use bridge-dev opt-in scenarios to learn withdrawal execution and recovery behavior while preserving test-secret boundaries.

bridge-dev-scenario-readme, bridge-dev-withdrawal-scenarios

nockup-scaffold

Use upstream nockup entrypoints to turn scaffold/build/run evidence into reusable NockApp fixtures.

nockup-main

Source Trace Contract

requiredFields

sourceAnchorId, domainId, crateName, sourcePath, symbol, lineRange, sourceCommit, sourceUrl, cargoGate, receiptFields

forbiddenFields

rawPmaSlab, walletSeedPhrase, sequencerJournalSigningKey, tenderlyAccessKey, r2TestToken, rawStateJam, rawEventLog, rawTransactionJam, rawGrpcPayload, privateSpendKey, objectStoreSecret, tenderlyTestPrivateKey, bridgeNodePrivateKey

reviewRule

Treat line ranges as implementation evidence, not protocol authority.

reviewRule

Tie every source anchor to the exact Nockchain commit and release before accepting receipts.

reviewRule

Use Tier 0 docs for protocol claims and these anchors for current Rust implementation boundaries.

reviewRule

Promote an upstream change into Nocksperimental only after naming the receipt fields, forbidden fields, and validation gate.

Source Domains

node-runtime

Node runtime

nockchain

Anchor local fakenet readiness, process command provenance, data-dir policy, and node startup assumptions.

mining-runtime

Mining runtime

nockchain

Tie miner receipts to key configuration, public key hash context, mining data, and block-commitment diagnostics.

p2p-sync-gossip

P2P sync and gossip

nockchain-libp2p-io

Explain empty routing tables, no peers, quiet tx gossip, and wrong-commitment symptoms through catch-up state.

nockapp-runtime

NockApp runtime

nockapp

Ground poke, peek, effects, event-log, and NockApp lab evidence in current Rust runtime boundaries.

pma-durability

PMA durability

nockvm, nockapp

Keep PMA/state-jam/checkpoint evidence metadata-only while recording runtime durability and recovery context.

runtime-stack-safety

Runtime stack safety

nockvm

Track issue #121 and any stack-frame safety changes that can affect replay or PMA-backed runtime evidence.

wallet-cli

Wallet CLI

nockchain-wallet

Pin wallet commands, endpoint mode, balance checks, transaction creation, and operator-facing evidence fields.

wallet-transaction-builder

Wallet transaction builder

wallet-tx-builder

Anchor create-tx and withdrawal planning, fee behavior, and bridge settlement assumptions.

public-api-grpc

Public API and gRPC

nockchain-api, nockapp-grpc

Separate hosted public API evidence from local/private gRPC probes and wire conversion receipts.

bridge-withdrawal

Bridge withdrawal

bridge

Trace withdrawal runtime and kernel port evidence without storing raw transaction jams or bridge secrets.

bridge-sequencer

Bridge sequencer

nockchain-bridge-sequencer

Explain sequencer journals, submission state, and VESL bridge evidence while excluding signing keys.

bridge-dev-scenarios

Bridge-dev scenarios

bridge-dev

Use opt-in bridge development scenarios as implementation fixtures while keeping Tenderly, R2, and signing secrets out of public receipts.

nockup-scaffold

Nockup scaffold

nockup

Connect scaffold build/run receipts to the upstream nockup entrypoint and template UX.

Source Anchors

nockchain-node-main

main

Node startup is the first source boundary for fakenet and operator evidence; receipts need command, network, data-dir, and build provenance.

domainId

node-runtime

sourcePath

crates/nockchain/src/main.rs L20-L80

cargoGate

cargo check -p nockchain

receiptFields

nodeCommand, dataDir, networkId, nockchainCommit, nockchainBuild

forbiddenFields

rawPmaSlab, rawStateJam, walletSeedPhrase

libp2p-catch-up-signal

CatchUpSignal::is_catching_up

Behind-tip state can make missing gossip intentional; receipts need sync mode before interpreting quiet peers as network failure.

domainId

p2p-sync-gossip

sourcePath

crates/nockchain-libp2p-io/src/catch_up.rs L77-L160

cargoGate

cargo check -p nockchain-libp2p-io

receiptFields

syncMode, tipHeight, peerCount, routeTableSize

forbiddenFields

rawPmaSlab, rawStateJam

libp2p-gossip-suppression

P2PState::should_suppress_outgoing_gossip

This is the source anchor for interpreting tx gossip silence while the node catches up.

domainId

p2p-sync-gossip

sourcePath

crates/nockchain-libp2p-io/src/p2p_state.rs L2518-L2525

cargoGate

cargo check -p nockchain-libp2p-io

receiptFields

gossipSuppressedBehindTip, syncMode, peerCount, routeTableSize

forbiddenFields

rawPmaSlab, rawStateJam

nockapp-poke-peek

NockApp::poke / NockApp::peek

NockApp receipts should distinguish read-only peeks from state-changing pokes and summarize effects without storing raw logs.

domainId

nockapp-runtime

sourcePath

crates/nockapp/src/nockapp/mod.rs L278-L355

cargoGate

cargo check -p nockapp

receiptFields

pokeOrPeek, kernelIdentity, effectSummary, stateBoundary

forbiddenFields

rawEventLog, rawPmaSlab, rawStateJam

pma-open-growth

Pma::open

PMA open/growth behavior is implementation evidence for memory and durability claims, not a portable state artifact.

domainId

pma-durability

sourcePath

crates/nockvm/rust/nockvm/src/pma.rs L617-L640

cargoGate

cargo check -p nockvm

receiptFields

pmaMetadata, pmaMinimumWords, pmaOpenMode, stateJamFingerprint

forbiddenFields

rawPmaSlab, rawStateJam, rawEventLog

nockstack-frame-safety

NockStack::is_in_frame

Stack-frame safety remains a high-signal runtime watch item because it can affect replay reliability and PMA-backed execution.

domainId

runtime-stack-safety

sourcePath

crates/nockvm/rust/nockvm/src/mem.rs L1338-L1356

cargoGate

cargo check -p nockvm

receiptFields

runtimeStackFrameCheck, nockvmCommit, stackSafetyIssue

forbiddenFields

rawPmaSlab, rawStateJam

wallet-cli-commands

Commands

Wallet receipts should cite the command variant and endpoint mode while keeping seed material and private keys out of evidence.

domainId

wallet-cli

sourcePath

crates/nockchain-wallet/src/command.rs L306-L650

cargoGate

cargo check -p nockchain-wallet

receiptFields

walletCommand, walletAddress, walletEndpointMode, nockchainBuild

forbiddenFields

walletSeedPhrase, privateSpendKey, rawGrpcPayload

wallet-tx-planner

plan_create_tx / plan_withdrawal_tx

Withdrawal planning sits between wallet evidence and bridge evidence; receipts need deterministic planner metadata.

domainId

wallet-transaction-builder

sourcePath

crates/wallet-tx-builder/src/planner.rs L1018-L1056

cargoGate

cargo check -p wallet-tx-builder

receiptFields

withdrawalPlan, feeSummary, noteSelection, bridgeAmount

forbiddenFields

walletSeedPhrase, privateSpendKey, rawTransactionJam

bridge-sequencer-journal

build_sequencer_journal

Sequencer evidence can cite journal entry metadata and submission state while keeping signing material private.

domainId

bridge-sequencer

sourcePath

crates/nockchain-bridge-sequencer/src/main.rs L154-L240

cargoGate

cargo check -p nockchain-bridge-sequencer

receiptFields

sequencerJournalEntry, authorizedTransactionHash, submissionState

forbiddenFields

sequencerJournalSigningKey, objectStoreSecret, rawTransactionJam

bridge-dev-scenario-readme

bridge-dev Scenario Tests

The bridge-dev scenarios are opt-in fixture evidence that provisions remote state; receipts should record scenario metadata and environment posture, not credentials or raw remote artifacts.

domainId

bridge-dev-scenarios

sourcePath

crates/bridge-dev/tests/README.md L1-L58

cargoGate

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

receiptFields

bridgeDevScenarioName, releaseBinarySet, bridgeDevTestRunRoot, bridgeDevPortOffset, tenderlyVnetId, r2JournalReplay

forbiddenFields

tenderlyAccessKey, tenderlyTestPrivateKey, r2TestToken, objectStoreSecret

bridge-dev-withdrawal-scenarios

withdrawal_happy_path_reaches_executed / withdrawal_sequencer_rebuilds_from_r2_after_sqlite_wipe

Withdrawal scenario tests are implementation fixtures for happy-path, restart, R2 replay, downtime, and degraded-node behavior; public evidence should cite stable artifacts and phases without replaying secrets.

domainId

bridge-dev-scenarios

sourcePath

crates/bridge-dev/tests/scenarios.rs L955-L1084

cargoGate

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

receiptFields

bridgeDevWithdrawalPhase, stableProposalHash, authorizedTransactionArtifact, executedWithdrawalId, sequencerR2Recovery, bridgeProcessRestart

forbiddenFields

r2TestToken, tenderlyAccessKey, tenderlyTestPrivateKey, rawTransactionJam, sequencerJournalSigningKey

Implementation Links

rustAtlas

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

syncGossip

https://nocksperimental.com/api/nockchain/sync-gossip

bridgeSource

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

stateJams

https://nocksperimental.com/api/nockchain/state-jams

Nocksperimental Implications

implication

Use this guide when a receipt needs exact Rust source evidence, not just crate-level provenance.

implication

Refresh anchors when the upstream commit, release, source line range, or open issue watch changes.

implication

Pair every source anchor with a cargo gate and forbidden-field guard before accepting user-connected fakenet evidence.

implication

Treat bridge-dev scenarios as implementation fixtures; do not turn Tenderly or R2-backed test artifacts into public receipt payloads.

implication

Treat source URLs as implementation proof and Tier 0 docs as protocol authority.