groundinglab

Technical · Raw markdown

Reference implementation, Rust

Source: pcoc at commit aaa8946. Assumes: you have read the SPEC reading guide. Next: make a hike with it (Integrate a producer) or check one (Verifier and policy).

  1. What it is and isn't. It is one of three independent reference implementations ("refs": Rust, Go, Java). Each is tested against spec/conformance/v2.0. It is a guide and optional. If it disagrees with the SPEC, the SPEC wins and the ref has a bug. Rust is the only one that writes the vectors (PCOC_REGEN_V2=1); Go and Java compare against those bytes. (source: reference/README.md, reference/rust/README.md) Disagreements. Only values fixed by a hash count as evidence. Report a text-vs-vector conflict as a defect and don't pick a side. (source: CONTRIBUTING.md)
  2. Pins. Tip tag ref-rust-v2.0.5. Bari (bari-v0.6.8), the Gate (gate-v0.4.1), and the desktop app (desktop-v0.1.3) pin ref-rust-v2.0.5; the index still pins pcoc-bari at bari-v0.6.7 (and reaches hike through that). Android 3.5.47 (primal-pcoc tag android-v3.5.47) vendors ref-rust-v2.0.5. reference/SPEC_PIN names spec-v2.0.3 plus a vector hash. Check it with python3 reference/tools/check_spec_pin.py from the repo root. Toolchain is Rust 1.99.0 (rust-toolchain.toml); the hike crate's rust-version is 1.83. (source: reference/rust/README.md, reference/SPEC_PIN, reference/tools/check_spec_pin.py) Bari and the index: Bari is 0.6.8 (services/bari/Cargo.toml, tag bari-v0.6.8). The index still pins pcoc-bari at bari-v0.6.7 (services/index/Cargo.toml) (the Cargo.toml pin; a build from tag bari-v0.6.7 reports crate 0.6.6 because that tag points at the commit before the version bump).
  3. Crates. hike is the shared library (fill, leg, bind, object, path body, Hashcash; src/ has produce.rs, verify.rs, section14.rs, terrain.rs …). hike-net holds network and test-plane policy kept out of measurement (chainrpc.rs, policy.rs). nip06 holds DEMO keys only. satoshi-hike-produce and satoshi-hike-verify are the CLIs. (source: reference/README.md)
  4. Build and test. cargo test --locked --release in reference/rust runs the conformance pack; leave PCOC_REGEN_V2 unset. To regenerate: PCOC_REGEN_V2=1 cargo test --manifest-path reference/rust/hike/Cargo.toml --test conformance_v2 -- --exact conformance_v2_pack. (source: reference/rust/README.md, spec/conformance/v2.0/README.md)
  5. Verify. This comes first because checking the vectors needs no network, so it is the easiest first result. The rest of the docs go produce, then verify. satoshi-hike-verify --input OBJECT --index-url URL. The default --profile test never dials index.groundinglab.io and reads PCOC_TEST_INDEX_URL. --profile live --index-url https://index.groundinglab.io uses the hosted index, which is opt-in. To run your own index, use pcoc-index rebuild --source esplora|rpc (public API or a pruned node). Output is the §14 record only, with no policy. (source: reference/rust/README.md, reference/rust/hike/src/args.rs, services/index/README.md)
  6. Produce. satoshi-hike-produce takes --pubkey-hex, --output, --gossip-peer, --bari-url, and optional --report, --profile test|live|slow-lan, --clock-source gossip and --gossip-network mainnet|regtest; or a demo seed phrase in place of --pubkey-hex (flag in the reference README). The test profile fills them from PCOC_TEST_BARI_URL / PCOC_TEST_GOSSIP_PEER. The live default Bari is https://bari.groundinglab.io (consts DEFAULT_BARI_URL), which is opt-in. To run your own: start bari from services/bari and pass --bari-url with its address (setup in Integrate a producer, beat 3). The demo seed phrase is a lab derivation, not a production seed. (source: reference/rust/satoshi-hike-produce/src/main.rs, reference/rust/hike/src/args.rs, reference/rust/hike/src/consts.rs, services/bari/README.md) On the live profile, any https Bari or index origin (no path) is accepted; a host other than groundinglab's prints a warning and proceeds. Live produce does not need its own gossip peer: with no --gossip-peer and no PCOC_LIVE_GOSSIP_PEER it falls back to Bitcoin's public DNS seeds (mainnet). A named peer wins, and the command line wins over the variable. --tip-url and --clock-source http are usage errors. (source: reference/rust/satoshi-hike-produce/src/main.rs, reference/rust/hike/src/args.rs)
  7. Embedding (calling the library from your own program). The Gate, groundinglab's admission service (Admission gate), calls hike::verify_with_bind_threads (services/admission-gate/src/verifier.rs linked_measure). Android calls hike::produce_with_settlement_sized and verifies with hike::Sizes::production() through JNI; primal-pcoc 3.5.47 vendors hike at ref-rust-v2.0.5 (android-v3.5.47). The CLI reads PCOC_BIND_THREADS: default 6, 1 runs serially, and the record doesn't change. (source: reference/README.md, reference/rust/hike/src/verify.rs) API stability: nothing in the repo declares a stable public API for hike yet (hike/src/lib.rs states none). Pin a tag. (source: reference/rust/hike/src/lib.rs)

Checked against pcoc aaa8946. Raw markdown.