Source: [pcoc `services/bari/README.md`](https://github.com/groundinglab/pcoc/blob/main/services/bari/README.md) and [OPERATING.md](https://github.com/groundinglab/pcoc/blob/main/services/bari/OPERATING.md), with the waypoint rules from the specification, section 13.6 ([Waypoint Publication](spec-waypoint.md)), and plant-tag detail from that same document.

# bari

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](https://github.com/groundinglab/pcoc/tree/main/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](https://github.com/groundinglab/pcoc/blob/main/spec/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](https://github.com/groundinglab/pcoc/blob/main/services/bari/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](https://github.com/groundinglab/pcoc/blob/main/services/bari/Cargo.toml).

## More

- [OPERATING.md](https://github.com/groundinglab/pcoc/blob/main/services/bari/OPERATING.md) — full HTTP table, operator page, fixture command
- [deploy/bari.service](https://github.com/groundinglab/pcoc/blob/main/services/bari/deploy/bari.service)
- [deploy/env.example](https://github.com/groundinglab/pcoc/blob/main/services/bari/deploy/env.example)