Developer guide¶
Local setup¶
Node 24. .nvmrc pins 24 and package.json sets engines.node to
>=24.0.0; CI (.github/workflows/ci.yml) uses node-version: 24.
git clone https://github.com/SplitStream-Labs/splitstream-actions
cd splitstream-actions
npm install
| Command | Does |
|---|---|
npm run typecheck |
tsc --noEmit. |
npm test |
vitest run — all unit tests. |
npm run test:watch |
vitest in watch mode. |
npm run test:integration |
vitest run test/relay.integration.test.ts — gated, see below. |
npm run build |
ncc build src/index.ts -o dist — the action bundle. |
npm run check |
typecheck + test + build. This is exactly what CI runs on every push and PR to main. |
dist/ is deliberately not gitignored, because action.yml runs dist/index.js
(using: node24, main: dist/index.js) and uses: ./ resolves there. Any
change under src/ needs a rebuilt bundle committed with it — run
npm run build (or npm run check) and commit dist/ in the same commit.
Layout:
src/index.ts orchestrator (inputs -> pipeline -> relay)
src/registry.ts loads + validates splitstream.yml
src/ingest.ts Octokit: merged PRs + closing refs (no label reading)
src/counts.ts distinct closed issues per contributor
src/manifest.ts floor payout formula + dust remainder + manifest format
src/merkle.ts leaf XDR hashing + sorted-pair tree
src/relay.ts Soroban RPC: cycle query, build/sign/submit/confirm
schemas/splitstream.schema.ts the zod registry schema
Unit suites cover registry, counts, manifest, merkle (golden), and
ingest. test/relay.integration.test.ts also holds two always-on unit blocks —
the oracle self-verification check and parseCycleInfo — which run under plain
npm test against stubbed RPC servers; only the testnet blocks in that file are
gated.
Verifying the Merkle implementation¶
This is the check that matters most: src/merkle.ts must produce the same bytes
as splitstream-core's Rust merkle::leaf_hash and hash_pair. If it drifts,
every root this repo relays is unclaimable.
test/fixtures/merkle.golden.json pins:
- the 64-byte leaf pre-image (
leaf.leafPayloadHex) and the leaf hash (leaf.leafHex) for one(address, amount)pair; - a 3-leaf root (
tree3.rootHex, exercises odd-node promotion) and a 4-leaf root (tree4.rootHex).
test/merkle.test.ts asserts all of these, plus that the i128 encoding matches
the Rust SDK's nativeToScVal for amounts up to 2^127 - 1 and down to
-2^127.
Procedure after any change to src/merkle.ts, or to splitstream-core's
merkle.rs:
- In a checkout of
splitstream-core, regenerate the same three values from Rust (Address::to_xdr+i128::to_xdrconcatenated, thensha256, and the same pair/tree construction). CONTRIBUTING.md carries a runnablecargo testsnippet and the expected hex. - Compare against the fixture. The last recorded cross-check, on 2026-09-10
against
Oyinkans0la12/splitstream-core@main(soroban-sdk 27.0.6), matched all three: leafe89c8b63…33c206,tree342cb7efa…0663f94f,tree4b9f5a8ae…36197b24. - If the Rust value differs, fix
src/merkle.tsfirst. Update the fixture only once both implementations agree, in the same commit, and record the new values there too. Never re-pin the fixture to make a failing test pass — the fixture is pinned to the contract's implementation, not this repo's.
splitstream-core's merkle.rs is frozen; treat any change to it as a breaking
protocol change and re-run this cross-check before trusting a relayed root.
Gated integration tests (testnet)¶
test/relay.integration.test.ts runs its testnet blocks only when every gate is
set:
| Env var | Value |
|---|---|
RUN_RELAY_INTEGRATION |
1 — required for the read-only suite |
SOROBAN_RPC_URL |
e.g. https://soroban-testnet.stellar.org |
SPLITSTREAM_VAULT_CONTRACT |
a deployed C... vault contract |
ORACLE_SECRET_KEY |
a funded S... relay keypair |
RUN_RELAY_SUBMIT |
1 — additionally required for the state-changing submit test |
RUN_RELAY_INTEGRATION=1 \
SOROBAN_RPC_URL=https://soroban-testnet.stellar.org \
SPLITSTREAM_VAULT_CONTRACT=C... \
ORACLE_SECRET_KEY=S... \
npm run test:integration
- Read-only (
RUN_RELAY_INTEGRATION=1):queryCycleInfoagainst cycle 0 (aNonereply for a never-posted cycle is a valid result and passes) andledgerCloseTimeagainst the latest ledger. - Submit (
RUN_RELAY_SUBMIT=1): posts a realpost_cycle_rootwith cycle id999999, a 32-byte root of0xab, andtotalAmount = 1. The absurd cycle id keeps it from colliding with a real cycle, but it is still a real state change — run it only against a throwaway vault and a throwaway keypair, never the treasury vault or the production oracle secret.
The manual integration-check.yml workflow¶
.github/workflows/integration-check.yml runs the gated suite on demand:
workflow_dispatch only, never on a schedule and never on push. It takes
one input, run_submit (boolean, default false), sets
RUN_RELAY_INTEGRATION=1, passes run_submit through as RUN_RELAY_SUBMIT,
supplies SOROBAN_RPC_URL and SPLITSTREAM_VAULT_CONTRACT from repository
variables and ORACLE_SECRET_KEY from a repository secret, and runs
npm run test:integration.
It starts with a gate check that fails the run when any of those three is unset. Without it, unmet gates mean every test skips and the job reports green having verified nothing.
It is separate from cycle-close.yml on purpose. That workflow is the real
cycle close: it runs on the sprint boundary, relays to the production vault, and
cannot be made conditional on a flag, because closing the cycle is the whole
point of the schedule. The integration check is never scheduled, is read-only
unless run_submit is set, and is pointed at a throwaway vault — so running it
costs nothing and cannot move treasury funds.