For contributors¶
If you closed issues that were counted in a cycle, your allocation is already on-chain before you do anything: splitstream-actions wrote the manifest and relayed the cycle's Merkle root to the vault. This repo is how you check what you are owed and pull it out.
Check your position¶
With --contributor, status reads the vault and reports:
- claimable in vault — your credit balance, from
get_balance. - vesting — the schedule from
get_vesting, ornone. - pending claimable cycles — cycles whose root is posted and which you have not claimed yet.
- already claimed cycles — cycles where
has_claimedis already true.
Add --json for machine-readable output, or --cycles <n> to widen the range.
There is no contributor list on-chain — the contract does not expose one, and
this tooling does not pretend otherwise. Per-contributor amounts come from the
manifest, so a local manifests/ directory makes the output richer.
Claim a cycle¶
--cycle is required: there is no way to guess which cycle you mean. The
manifest for that cycle is read from --manifest <path>, a local checkout
passed with --repo <dir>, --repo owner/name at --ref on GitHub, or
manifests/cycle-<id>.json in your working directory.
Claiming is two separately signed transactions, always:
credit_claimproves your allocation against the cycle's Merkle root and credits your balance inside the vault.withdrawmoves that credited balance out to your account.
The command submits the first, then offers the second explicitly. They are never
merged into one transaction. Pass --no-withdraw to stop after credit_claim.
What the command checks before it signs¶
- It builds your proof from the manifest row for your address, or for your
GitHub handle if you pass one as
--contributor. - It recomputes the Merkle root from the manifest's own rows and compares it
to the published
merkleRoot. If they disagree it refuses to submit, because the proof would burn a fee and fail on-chain.--forceoverrides that, prints a warning, and should only be used when you are certain. - It checks
has_claimedfor your cycle and address, and stops before signing if you have already claimed. - It asks you to confirm, unless you pass
-y, --yes.
Signing¶
There are two ways to sign, and neither is "paste a secret key into the terminal".
Local testnet keypair¶
Set SPLITSTREAM_DEV_SECRET_KEY in .env. This is a testnet-only path: it is
labelled INSECURE, testnet-only wherever it is printed, and it is
hard-blocked on mainnet. The key is read only from that environment
variable — never from a flag and never from a config file. If the key does not
control your claimant address, the command fails before signing.
Hardware wallet¶
Signing is delegated to a Ledger device through the optional
@ledgerhq/hw-app-str and @ledgerhq/hw-transport-node-hid packages, which
keep the key off the machine. They are not installed by default; the CLI tells
you the npm install --save-optional line if they are missing. The default
derivation path is 44'/148'/0'.
The device's address is read first and matched against the address the claim is sourced from, so a wrong device fails before you approve anything.
A mainnet claim therefore requires a hardware wallet, by construction.
Where your amount comes from¶
Your row in the manifest has stellar (your G... account), issuesClosed
(the count that produced the payout) and amount (base units, as a decimal
string). Amounts are computed as:
The remainder that does not divide evenly is dustRemainder and stays in the
vault. An issue counts when it was closed by a merged pull request containing a
recognized closing keyword — Closes #N, Fixes #N or Resolves #N. No label
is read, and every qualifying issue counts equally. Credit goes to the PR
author.
If you are not in the manifest, you are not paid by this cycle. Who is
eligible is decided by the contributor registry, which is owned by
splitstream-actions — see its
maintainer page on .github/splitstream.yml. Missing or
wrong addresses in that registry are the usual reason a contributor is absent or
unmapped, so check there before opening an issue here.
Vesting¶
If a cycle granted you a vesting schedule, part of your allocation unlocks over
time rather than all at once. splitstream status --contributor <address>
reports the unvested remainder, the start ledger and the duration. The vault's
claim_vested entrypoint and the SDK's buildClaimVestedTx handle it, but there
is no CLI command for it yet — the SDK path is in the
SDK reference.
When something refuses to run¶
- "has already claimed cycle N" — you already credited this cycle. Run
splitstream status --contributor <address>to see the balance instead. - "the manifest root does not match the tree recomputed from its own rows" —
the manifest and this repo's proof code disagree. Re-generate the manifest, or
report it. Do not reach for
--forcefirst. - "is not present in the cycle N manifest" — your address or handle is not in the eligible set. See the registry note above.
Every message is a single line by default; -v, --verbose adds stack traces and
raw RPC detail.