bari

Source: pcoc services/bari/README.md and OPERATING.md, with the waypoint rules from the specification, section 13.6 (Waypoint Publication), and plant-tag detail from that same document.

One binary, bari. Crate pcoc-bari, library pcoc_bari. Each release is tagged bari-v<version>.

It accepts 32-byte waypoints and later serves a Merkle path. It writes the index cache. It does not serve GET /index. The index HTTP reader is services/index.

Bari timestamps waypoints by building one tree per Bitcoin block from the waypoints it holds, and planting that tree's root in one Bitcoin transaction. The plant transaction only fixes a position in Bitcoin's record. Bitcoin's mining does not secure a PCOC, and it is not what the making costs. Section 13.6 of the specification is the whole rule set for a Bari's waypoint answers.

Routes

Surface Role
POST /waypoint Hand Bari a 32-byte waypoint, paid with a small Hashcash stamp (Rule BR1)
GET /path/{leaf} Serve the Merkle path for a waypoint whose plant is in a block (Rule BR4)
GET /ops Operator page

Hashcash

Required on POST /waypoint only. Two headers: X-Bari-Hashcash-Nonce: <u64 decimal> and X-Bari-Hashcash-Header: <160 hex digits>, the 80-byte fee header.

Item Value
Challenge SHA-256("bari-hc-v2" ‖ bari_origin ‖ header_hash), with bari_origin Bari's own public origin
Fee header Bari's current block, the block before it, or a valid block after it (±1 block, judged against Bari's own view of the best chain)
Digest Over the challenge, the 32 waypoint bytes and the nonce (SPEC §13.1)
Difficulty 21 leading zero bits (fixed; a constant of the specification)

The fee can only be solved on a three-block span of the chain, so stamps can't be stockpiled, and the origin binding stops one stamp being reused at a second Bari.

Answers

Bari's only answers to a waypoint post are 204 and 402. A paid post, valid under Rule BR1, is always accepted with 204, whatever the timing: the gap between Bari's tip and the maker's, the arrival time, and which of the three blocks the fee was solved on don't change the answer. Anything unpaid or invalid gets a plain 402 and nothing more. Dedupe applies to paid posts only: a paid post of a waypoint already in the current pool gets 204 and no second entry (Rule BR2). A 204 is not a promise that a path will be served.

Plant tag

Each plant is one Bitcoin transaction. The commitment is a 39-byte output script:

OP_RETURN ‖ push-37 ‖ BARI ‖ 0x02 ‖ the 32-byte Merkle root

That tag alone marks a plant for the initial release. Operator key attribution on funding inputs is a later, optional step (03-Waypoint_Publication_Process.md, proposed, not normative).

Cycle (short)

  1. Makers POST /waypoint; each accepted waypoint joins Bari's pool.
  2. When a beacon arrives, that is, a new block on Bari's best chain, Bari builds the tree from the pool, which clears the pool for the next stage (Rule BR3). Pool capacity, and what happens when a pool is full, are outside the specification.
  3. Once the plant is in a block, through the last offset of the anchor window (offsets 2, 3 and 4 after the stage's beacon, SPEC §13.1), GET /path/{leaf} returns the path. Otherwise it answers 404 with one of still in the pool, sealed but not in a block yet, not included, already archived after it was served or unknown. A path ask is never refused for timing (Rule BR4).
  4. The plant is never replaced to speed it up, and the same tree is never broadcast twice. Plant-fee settings are the operator's (deploy/env.example).

Tip modes

Mode What it is
Live BARI_TIP_SOURCE=bitcoin-gossip, plus a Bitcoin Core plant
Test BARI_TIP_SOURCE=synth, plus a simulated commit
Unset BARI_TIP_SOURCE remains the RPC poll and is not the live tip

Pins

hike and hike-net come from the Rust SDK in the same repository. The exact tag is in Cargo.toml.

More

From pcoc services/bari on main, with the waypoint rules of specification section 13.6. Raw markdown.