Manifest reference¶
The distribution manifest is the artifact of a cycle: who gets paid, how much,
and the Merkle root those amounts hash to. This repo is the authoritative
source for this format — it is produced by buildManifest() in
src/manifest.ts and consumed by splitstream-sdk-cli.
The manifest is written to manifests/cycle-<id>.json and committed to git
before the relay runs. Treat the committed file, not the chain, as the record of
what was distributed.
Fields¶
| Field | Type | Meaning |
|---|---|---|
cycleId |
integer (JSON number) | Cycle id, taken from the committed audit trail (last cycle + 1) or the cycle_id input. Must equal the <id> in the filename. |
generatedAt |
string, ISO 8601 | new Date().toISOString() at build time. This is the next cycle's window start. |
poolAmount |
decimal string | The cycle_pool_amount input in stroops, echoed unchanged. |
totalIssuesClosed |
integer (JSON number) | Sum of entries[].issuesClosed — the payout denominator. |
entries |
array | One entry per contributor with at least one qualifying issue. Contributors with none are absent. |
entries[].github |
string | GitHub handle, in the registry's casing. |
entries[].stellar |
string | The contributor's G... public key. |
entries[].issuesClosed |
integer (JSON number) | Distinct issues this contributor closed this cycle. |
entries[].amount |
decimal string | Payout in stroops, from the floor formula. |
dustRemainder |
decimal string | poolAmount - sum(entries[].amount). Always present, including "0". |
merkleRoot |
string | 64 hex characters — the 32-byte root over the payout leaves. |
Monetary values are decimal strings, never JSON numbers: a pool or a payout
large enough to exceed Number.MAX_SAFE_INTEGER must survive a round trip
through a consumer that parses JSON with floats.
entries is sorted by issuesClosed descending, then by handle. That is review
order only — it does not affect the root, because the tree pins leaf order
itself.
{
"cycleId": 4,
"generatedAt": "2026-09-10T00:00:00.000Z",
"poolAmount": "5000000000",
"totalIssuesClosed": 7,
"entries": [
{ "github": "alice", "stellar": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF", "issuesClosed": 3, "amount": "2142857142" },
{ "github": "bob", "stellar": "GC3BLRQMHJGDIBAVHA2WQOY6Q7CBLAZUNZPIR5NYAX6XTQZUSTVRHHPK", "issuesClosed": 2, "amount": "1428571428" },
{ "github": "carol", "stellar": "GCWSW5ZMOHGEBLUFKL7PZGPZKW3OMMDCAT4OMBFKWHXNIUGWGG43HQ7C", "issuesClosed": 2, "amount": "1428571428" }
],
"dustRemainder": "2",
"merkleRoot": "8b3adf9e99322e6ba79ec199a035e5dbee758160402c4e15ee357b0f445685f2"
}
That root is the real root of the three entries above, computed with
buildMerkleRoot() — not a placeholder.
Merkle leaf format¶
The leaf is the one thing the contract and every consumer must agree on byte-for-byte. A leaf hashes exactly two values — the contributor's Stellar address and their payout amount:
leaf = sha256( xdr_encode(ScVal(Address(stellar_pubkey))) || xdr_encode(ScVal(i128(amount))) )
Address XDR (44 bytes): u32(SCV_ADDRESS=18) | u32(SC_ADDRESS_TYPE_ACCOUNT=0) | u32(publickey ED25519=0) | ed25519(32)
i128 XDR (20 bytes): u32(SCV_I128=10) | int64 hi | uint64 lo
Both halves are the full ScVal-form XDR that soroban-sdk's ToXdr trait
produces — including the ScVal union discriminant, not a bare 32-byte key or a
bare integer. scvI128() and addressScVal() in src/merkle.ts build them;
test/merkle.test.ts additionally asserts the i128 encoding against the Rust
SDK's nativeToScVal for amounts including i128::MAX, i128::MIN and
negative values.
The leaf deliberately does not use any Merkle library's default leaf
hashing. It also hashes only (address, amount) pairs, which is why the
count-based payout rule needed no contract change: the formula never enters the
leaf.
Tree construction¶
A sorted-pair Merkle tree:
- Leaves are ordered by ascending stellar public key bytes — deterministic
and independent of handle casing, so the root is reproducible from the
manifest alone, regardless of
entriesorder. - At each level, children are paired left-to-right and concatenated in ascending
byte order before hashing, so a pair
(a, b)hashes the same as(b, a). - An odd node is promoted to the next level unchanged.
- A single-leaf tree's root is that leaf.
splitstream-core's verifier must use the same leaf order and the same pair
sorting; a tree that concats children in insertion order produces a different
root and rejects every claim.
The golden fixture test/fixtures/merkle.golden.json pins the leaf pre-image
bytes, the leaf hash, and a 3-leaf root (odd-node promotion) plus a 4-leaf root.
See the developer guide
for how to re-verify it against splitstream-core's Rust implementation.
Where manifests live, and why the newest one is the source of truth¶
Committed manifests are manifests/cycle-<id>.json. The workflow's
cycle-close.yml commits the generated file as the audit trail.
readLastManifestWindow() (src/manifest.ts) scans that directory for files
matching ^cycle-(\d+)\.json$, takes the highest id, and returns its
cycleId and generatedAt. The next cycle starts at that timestamp. This is
the only way to answer "what was the last cycle?" — the deployed contract cannot
enumerate its cycles, it only answers get_cycle_info(cycle_id) for an id you
already know.
Two consequences:
- Dry-run artifacts never count. Dry runs write
cycle-<id>.dry-run.json, which the regex above does not match, so a dry run can never advance the window. - A corrupt audit trail fails the run rather than guessing. The scan throws
on an unreadable directory, malformed JSON, a missing or unparseable
generatedAt, or a filename whose<id>disagrees with the file'scycleId. A missing directory (ENOENT) is not an error — it means cycle 0.
Deleting or rewriting a committed manifest silently rewinds or jumps the next cycle's window. Don't.