groundinglab

Technical · Raw markdown

Integrate a producer

Assumes: the SPEC reading guide; flags are in the Rust reference (Rust reference).

Minimal checklist (inputs → CBOR file):

  1. A public key (x-only) for the object.

  2. A Bari URL and a gossip peer (or live DNS-seed fallback).

  3. Run produce until the hike finishes; write the CBOR object.

  4. Verify the file against an index; keep the §14 record for your policy.

  5. Output. A producer is the program that makes a hike object. Its output is a hike object of kind satoshi-hike-v2.0-object: 18 stages, deterministic CBOR (SPEC §7.3, §8 Rule A3). STEPS_PER_LEG 2000000, SAMPLE_BYTES 1024, checkpoint preimage 1096 bytes (SPEC header, §6).

  6. Inputs. (a) A tip sequence of Bitcoin headers. It is the public sequencer that paces and orders stages (reference/README.md; SPEC §9). (b) A Bari, a service that timestamps the producer's waypoints (32-byte values recorded at each stage) against Bitcoin. It must accept waypoints (POST /waypoint with Hashcash, 21 leading zero bits, in X-Bari-Hashcash-Nonce) and serve Merkle paths (GET /path/{leaf}) (services/README.md). (c) The producer's x-only public key (--pubkey-hex). Keys. nip06 holds demo keys only and isn't the hike's production_seed (reference/rust/README.md). production_seed is public_key ‖ seed_beacon, 64 bytes, read as eight little-endian lanes (SPEC §10, P10.1; §4 glossary "Seed").

  7. Endpoints, all opt-in. The hosted Bari is https://bari.groundinglab.io. To run your own: bari with BARI_TIP_SOURCE=bitcoin-gossip, your own peer (PCOC_LIVE_GOSSIP_PEER) and Bitcoin Core RPC plus a wallet for the plant, or synth for the test plane (services/bari/README.md, deploy/env.example). If you run your own Bari: fees are BARI_FEE_CAP_SAT_VB, default 1.1 sat/vB, and other values are refused (env.example); a plant (the Bitcoin transaction output that timestamps a batch of waypoints) is a 39-byte tag: OP_RETURN ‖ push-37 ‖ BARI ‖ 0x02 ‖ 32-byte root (services/index/README.md). An app that uses a Bari doesn't pay plant fees itself. For the initial release, plants are identified by that tag alone; operator-key attribution is planned and optional (spec/plant-attribution.md).

  8. The procedure at a high level. The seed is the latest header already known at start, with no wait (SPEC §9; stage0-start.json). Each stage runs its legs (fixed blocks of memory-bound work), then its checkpoints (§11), then a waypoint per stage (§12.2). After each header in the anchor window, offsets 2, 3, 4 (§13.1), the producer asks W_1…W_16; W_17 is posted but not asked. Event order at stage boundaries follows Rule A1 (§13). Procedure: §13.2.

  9. Integration routes. Shell out to satoshi-hike-produce (flags: Rust reference, beat 6), or link hike as the Android demonstrator does (JNI, pcoc-bridge/bridge/src/produce.rs → hike::produce_with_settlement_sized; apps/android/README.md). Android is the one named example.

  10. Restart and log. Bari restart is §13.4 (Informative): replacing a live Bari during produce is normal, a pooled waypoint survives a quick restart, and the worst case is a skip, not a fee bump. The live event log is §13.5 (Normative): live profile only, an append-only file at the object path plus .events, one compact JSON line per record (block, waypoint, posted, checked, fetch). It is not part of the object or an input to any leg, and a failed write leaves the hike unchanged.

  11. Conformance. Byte-equality target: kat-small.json. Also stage0-start.json, checked by Rust, Go and Java. A §13.2 producer replay equals object_hex (spec/conformance/v2.0/README.md). Produce does no signature check (SPEC §2). Signing happens at sign-in (Sign-in wire). Next: check what you made (Verifier and policy).

Checked against pcoc aaa8946. Raw markdown.