Wallet and API evidence

Nockchain Wallet

Wallet command, endpoint mode, fakenet balance, watch-only, public API exposure, and key-material safety context for Nocksperimental receipts.

Wallet API Fakenet Commands

Build

33ba97b1e206

Commands

Endpoint Modes

Unit

nicks

Balance Commands

show-balance

nockchain-wallet show-balance

Displays aggregate wallet balance, note count, and total nicks held.

evidenceUse

Use for aggregate wallet balance evidence after recording endpoint and sync context.

risk

sync-heavy command; stale endpoint or missing watched keys can make a balance look empty.

list-notes

nockchain-wallet list-notes

Lists all notes currently managed by the wallet, sorted by assets.

evidenceUse

Use for note-level balance evidence when a naked aggregate total is not enough.

risk

sync-heavy command; requires loaded keys or watched identifiers.

list-notes-by-address

nockchain-wallet list-notes-by-address <base58-address>

Lists notes for a specified public key or address.

evidenceUse

Use to bind fakenet rewards or test balances to the wallet address under test.

risk

the address must be present as a key or watch-only identifier before sync recognizes it.

watch-address

nockchain-wallet watch address <base58-pkh-or-pubkey>

Adds a watch-only address or public key without importing private signing material.

evidenceUse

Use for public test wallets and shared fakenet balance checks.

risk

watch-only balances are observable, not spendable.

Wallet Triage

balance-unknown

Balance unknown

A balance is not meaningful until the wallet address, endpoint and sync context, client mode, and Nockchain build are known.

symptom

balance command failed or produced ambiguous output

checks

Capture walletAddress, endpointMode, endpoint, command, outputHash, and Nockchain build., Regenerate balance evidence after changing peers, state jams, or endpoint mode., Prefer note-level evidence when aggregate balance output is surprising.

watch-only-missing

Watch-only identifier missing

The wallet only syncs balances for loaded signing keys and watch-only identifier entries.

symptom

address balance is empty even though the address should have funds

checks

Confirm the address was imported with nockchain-wallet watch address or watch pubkey., Use list-notes-by-address after adding the watch-only identifier., Do not import seed phrases merely to observe public test balances.

private-grpc-unreachable

Private gRPC unreachable

The private client expects a local Nockchain instance reachable at 127.0.0.1:5555 unless a different private port is configured.

symptom

private wallet client cannot connect

checks

Confirm the fakenet node was started with --bind-public-grpc-addr 127.0.0.1:5555., Check WSL localhost forwarding and whether the wallet command runs in the same network namespace., Use /api/fakenet/diagnostics before interpreting balance failures.

public-api-exposure-risk

Public API exposure risk

nockchain-api is alpha/test-grade and currently documents no authentication, authorization, or rate limiting.

symptom

operator wants to expose nockchain-api publicly

checks

Keep public API access behind trusted controls such as VPN, tunnel, mTLS proxy, or private network., Record observability and access-control posture in receipts that depend on public API output., Do not treat a public API response as protocol authority.

Endpoint Modes

public

Public API

endpoint

https://nockchain-api.zorp.io

commandPattern

nockchain-wallet --client public --public-grpc-server-addr <url> <command>

risk

default public endpoint is remote, public API behavior is alpha/test-grade, record the public endpoint URL and upstream build before trusting output

private

Private local API

endpoint

127.0.0.1:5555

commandPattern

nockchain-wallet --client private --private-grpc-server-port 5555 <command>

risk

requires a local running nockchain instance, endpoint reachability depends on WSL/localhost forwarding, sync-heavy commands can fail if the local node is behind tip

Balance Evidence Contract

walletAddress

AU6cMNQ9vMyBwSGkwTghPsTGf6uLREziKnpDrM3y6Jk2zNsvRWdYFVx

endpoint

127.0.0.1:5555

conversion

65536 nicks = 1 nock

requiredFields

walletAddress, endpoint, endpointMode, command, outputHash, noteCount, totalNicks, nockchainBuild, nockchainCommit, syncContext, keyMode

receiptRule

Store command transcript hashes and parsed totals, not seed phrases, private keys, exported key files, or raw wallet databases.

Public API Evidence Contract

Public API evidence is useful, but transaction acceptance, explorer cache responses, cache warm-up, metrics, and reorg windows must be recorded before treating a response as comparable test evidence.

sourceDoc

crates/nockchain-api/README.md

services

NockchainService, NockchainBlockService

metric

nockchain_public_grpc.*

txCaveat

accepted does not prove block inclusion

requiredFields

publicApiEndpoint, apiSurface, txId, acceptedAt, inclusionBlock, cacheWarmupState, heaviestChainFreshness, reorgWindow, metricsSnapshot, nockchainCommit, nockchainBuild

rules

Treat tx-accepted as node acceptance, not block inclusion., Treat pending transaction responses as pending status, not mempool streaming., Treat empty or missing explorer pages during warm-up as inconclusive until cache state and heaviest-chain freshness are recorded., Treat explorer results near reorg windows as provisional unless independently confirmed.

block-explorer-cache

Block explorer cache

Explorer-style responses are cache-backed views of the reported heaviest chain.

endpoints

GetBlocks, GetTransactionBlock, GetTransactionDetails

limits

does not stream mempool contents, pending transactions are only reported as pending, newest up to 1024 blocks become available first during cache warm-up, older heights backfill after the first cache range, short-lived stale data can appear after a reorg

observability

none

transaction-acceptance

Transaction acceptance

The public API node reports that it accepted the transaction request.

endpoints

tx-accepted

limits

accepted does not prove block inclusion

observability

none

observability

Public API observability

API evidence should include cache and heaviest-chain freshness signals when available.

endpoints

none

limits

metrics prove service health context, not consensus finality

observability

nockchain_public_grpc.*, cache timings, heaviest-chain freshness, RPC success/error counts

Transaction Source Contract

Transaction construction evidence cites current released wallet Rust source from wallet-tx-builder and nockchain-wallet. Receipts should keep planner metadata and source hashes, not raw transaction files.

release

build-33ba97b1e206dd89b15c61b72b7802caf2136c18 (33ba97b1e206dd89b15c61b72b7802caf2136c18)

sourceAuthority

current-released-nockchain-rust

crateSurfaces

wallet-tx-builder, nockchain-wallet

verification

npm run test:nockchain-upstream-drift-check, npm run test:nockchain-wallet-atlas, npm run test:nockchain-upstream-drift-check, npm run test:registry-checkpoint-api

receiptFields

walletTransactionSourceCommit, feeBreakdown, wordCountBreakdown, lockResolutionSource, walletTransactionSourceCommit, walletTransactionSourceHash, createTxPlanningMode, selectionMode, candidateVersionPolicy, feeInputs, feeBreakdown, wordCountBreakdown, lockResolutionSource, noteDataKeys, recipientSpecKind, transactionName, allowLowFee, txId, nockchainBuild

forbiddenFields

rawUnsignedTx, rawTransactionJam, rawUnsignedTx, rawSignedTx, rawTransactionJam, walletSeedPhrase, walletPrivateKey, keys.export, walletDatabase, privateSpendKey

wallet-tx-builder

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

Defines transaction planning, selection, fee recomputation, note-data propagation, lock resolution, and word-count inputs.

sha256

bbb80bb18f47c20c4c095138b402d339787650ebe4428ef375f1c82c3bc795e8

symbols

line 9: compute_bridge_fee, compute_minimum_fee, FeeInputs, line 10: LockResolutionSource and ResolveLockRequest, lines 12-13: CandidateVersionPolicy, ChainContext, PlanRequest, RawNoteDataEntry, SelectionMode, line 16: WitnessWordInput and WordCountEstimator

nockchain-wallet

crates/nockchain-wallet/src/create_tx.rs

Pins the create-tx CLI request boundary that turns recipients, fees, selection strategy, and planner mode into wallet transaction intent.

sha256

544d662fffc4b239cd0aa81ac23613fee621d0f790e91d3172a40486d5168fc8

symbols

line 8: CandidateNote and CreateTxPlanningMode, line 12: ensure_manual_planner_parity, line 173: CreateTxRequest, line 432: CandidateVersionPolicy resolver

open-pr-early-warning

feat(wallet): support blobs and memo on transactions in wallet cli

signals

memo, blob, open-pr-early-warning, memo, blob

interpretation

Open PR #116 would add memo/blob transaction note data to the wallet CLI; track it as early warning, not released authority.

Local Fakenet Profile

localWrapper

fakenock --balance, npm run lab:local:balance, npm run lab:local:chain

upstreamEquivalents

nockchain-wallet --client private show-balance, nockchain-wallet --client private list-notes-by-address AU6cMNQ9vMyBwSGkwTghPsTGf6uLREziKnpDrM3y6Jk2zNsvRWdYFVx, nockchain-wallet --client private list-notes

evidenceUse

Treat fakenock --balance as local wrapper evidence; preserve the upstream wallet command, endpoint, and output hash in receipts.

Safety Boundary

secretAnchors

seed phrases, private keys, keys.export

doNotStore

seed phrases, private keys, keys.export, wallet databases, unsigned transaction intent files, signed transaction files unless explicitly public test artifacts

safeWithHashing

walletAddress, endpoint, endpointMode, command, outputHash, noteCount, totalNicks, txId

publicApiWarnings

alpha/test-grade software, no authentication, no authorization, no rate limiting, cache warm-up and reorg windows can affect explorer-style responses

Additional Commands

export-keys

nockchain-wallet export-keys

Exports wallet keys to a jam file, defaulting to keys.export.

evidenceUse

Use only outside Nocksperimental receipts for key backup or migration.

risk

key backup material must never be stored in git, receipts, support bundles, or public artifacts.

create-tx

nockchain-wallet create-tx --recipient '{"kind":"p2pkh","address":"<p2pkh-b58>","amount":10000}'

Creates a transaction with auto-selected notes and planner-computed fee.

evidenceUse

Use for transaction-construction provenance when testing wallet flows.

risk

amounts are denominated in nicks and transaction files written under ./txs can contain sensitive intent.

send-tx

nockchain-wallet send-tx ./txs/<transaction-name>.tx

Broadcasts a signed transaction file.

evidenceUse

Use only when a test explicitly needs submission evidence.

risk

broadcasting is state-changing; receipts should record tx id, endpoint, and build context.

tx-accepted

nockchain-wallet --client public tx-accepted <base58-tx-id>

Checks whether a public API node accepted a transaction.

evidenceUse

Use as a lightweight post-submit acceptance check; accepted does not prove block inclusion.

risk

public API only; private API cannot be queried with this request.

Additional Scenarios

tx-accepted-public-only

Transaction acceptance check is public-only

The wallet docs state that tx-accepted asks a public API node whether it accepted a transaction; the private API cannot be queried with this request.

symptom

tx-accepted was attempted against private API

checks

Use --client public for tx-accepted checks., Treat true as accepted by the node, not proof of mempool residency or block inclusion., Record tx id, endpoint, and latest observed chain context.