Architecture¶
SplitStream is deliberately split into three repositories so that the thing that decides who is owed what is separate from the thing that holds the money, which is separate again from the thing that lets each person collect. None of them trusts the others with more than it must.
flowchart TB
subgraph GH["GitHub (untrusted input)"]
PRS["Merged PRs / closed issues"]
end
subgraph ACTIONS["splitstream-actions · TypeScript, runs in CI"]
COUNT["count contributions"] --> MANIFEST["build payout manifest"]
MANIFEST --> MERKLE["compute Merkle root + proofs"]
MERKLE --> RELAY["relay root on-chain"]
end
subgraph CORE["splitstream-core · Rust/Soroban, on Stellar"]
ROOT["post_cycle_root (oracle)"]
WINDOW["24h challenge window"]
CLAIM["credit_claim (Merkle proof)"]
WITHDRAW["withdraw (pull payment)"]
SPLIT["fixed basis-point splits"]
VEST["linear vesting"]
SWEEP["sweep (72h timelock)"]
ROOT --> WINDOW --> CLAIM --> WITHDRAW
end
subgraph SDKCLI["splitstream-sdk-cli · TypeScript"]
SIM["simulate — dry-run a cycle"]
STATUS["status — read balances"]
CLAIMCLI["claim — build proof + submit"]
end
PRS --> COUNT
RELAY -->|"oracle auth"| ROOT
MANIFEST -.->|"published artifact"| SIM
MERKLE -.->|"proofs"| CLAIMCLI
CLAIMCLI --> CLAIM
STATUS --> CORE
WITHDRAW --> WALLET["Contributor wallet"]
Component responsibilities¶
| Repository | Owns | Trust boundary |
|---|---|---|
splitstream-core |
Custody of the pooled SEP-41 token, the Merkle root of record, the dispute window, fixed-share splits, vesting schedules, and sweeps. | Trusts only that the admin and oracle behave; funds can never leave except through a valid proof or an admin-gated, timelocked sweep. |
splitstream-actions |
Reading GitHub events, weighting contributions, producing the payout manifest, and relaying its root on-chain. | Runs with the oracle key. It can post a wrong root, but that root is challengeable for 24 hours before any money moves. |
splitstream-sdk-cli |
A typed client over the vault: building Merkle proofs, submitting claims, reading balances, and simulating cycles before they are posted. | Holds only the contributor's own key. It can do nothing a contributor could not do by calling the contract directly. |
The frozen cross-repo contracts¶
Three interfaces cross repository boundaries. They are protocol, not implementation details, and changing any of them is a breaking change that must land in all three repos together.
- The Merkle leaf format.
splitstream-actionsandsplitstream-coremust hash a leaf identically, or proofs will never verify:
Proofs use the sorted-pair convention (each pair hashed in ascending byte
order), so left/right ordering never matters. The format is frozen in
splitstream-core's CONTRIBUTING.md,
and covered by golden fixtures in both repositories.
-
The payout manifest schema. The JSON artifact that
splitstream-actionspublishes andsplitstream-sdk-cliconsumes and verifies. Described once, in Manifest reference. -
The contract ABI. The 19 public functions and the 17 error discriminants of
splitstream-coreare addressed by name and number from both the SDK and the relay. Error numbers must never be renumbered — see Contract reference.
Lifecycle of a cycle¶
- The action runs on a schedule (or on demand). It counts contributions from merged PRs and closed issues since the last cycle.
- It computes each contributor's share, builds the manifest, and derives the Merkle root.
- It relays the root to
splitstream-coreviapost_cycle_root, signed with the oracle key. The 24-hour challenge window starts now. - Maintainers can inspect the manifest and, if it is wrong,
challenge_and_replace_rootonce inside the window. The window never restarts. - After the window closes, claims open. A contributor (or their CI) obtains
their proof from the manifest and calls
credit_claim, which credits a pull-payment balance, thenwithdrawto receive the tokens. - Separately, the admin configures fixed basis-point splits and vesting schedules for recurring team payouts; those are not gated by the challenge window. Treasury sweeps are gated by a 72-hour timelock instead.
Why three repositories¶
- Custody is separated from computation. The contract that holds the money contains no GitHub-specific logic, so the surface that must be audited is small and stable.
- The oracle is not the admin.
splitstream-actionsholds the oracle key and can post roots; it cannot replace them, configure splits, or sweep. The admin can replace a root, but only inside a bounded window. - Contributors can verify everything themselves. With the manifest and the SDK, a contributor can reproduce their proof and confirm the on-chain root without trusting any server.