Credits¶
An internal ledger of who used what and whose machines earned it, in euros, inside one deployment. Closed loop unless payouts are on, and they run on a test network only: no money comes in and none goes out. Credits are only spent on this deployment's compute.
Turning it on¶
SWARM_LEDGER is off by default.
| Value | Means |
|---|---|
off |
Nothing settles, and nobody is refused |
record |
Usage settles and nobody is refused, so balances can go negative. Use this for a beta |
enforce |
Also refuses a request the balance cannot cover: a 402 with the numbers |
Only usage from the moment it is turned on settles. Usage while it was off stays free.
There is no default price. Without SWARM_LEDGER_RATES, every event settles as
unpriced and nothing moves:
SWARM_LEDGER=record
# Micro-EUR per million tokens. "train" is per sample and billion parameters.
SWARM_LEDGER_RATES='{"default": {"prompt": 100000, "completion": 300000, "train": 0},
"models": {"org/big-model": {"prompt": 200000, "completion": 600000}}}'
An event is decided once, so adding a rate later does not bill what went before.
| Setting | Default | Means |
|---|---|---|
SWARM_LEDGER_DEMAND_FEE_BPS |
0 | Added to what a customer pays, in basis points |
SWARM_LEDGER_SUPPLY_FEE_BPS |
0 | Taken from what a host earns |
SWARM_LEDGER_AUDIT_RESERVE_BPS |
0 | Added to what a customer pays, held for audits |
SWARM_LEDGER_STARTER_GRANT_MICRO_EUR |
0 | Given once to each user |
SWARM_EARNINGS_MATURITY_DAYS |
14 | How long an earning is held |
SWARM_PAYOUT_MINIMUM_MICRO_EUR |
20 EUR | When matured earnings become payable |
SWARM_PROBATION_DAILY_TOKENS |
200,000 | Past this in a day, a new node's earnings wait until it is established |
What a request moves¶
What is priced is what work metering counted: tokens the leader delivered and training steps committed. Each stage's share is its parameters over the placement's. For every settled event, to the micro-EUR:
customer debit = sum of stage shares + demand fee + audit reserve
stage share = net to its host + supply fee
| Case | What happens |
|---|---|
| Nothing was delivered | No charge (nothing_delivered) |
| A private pool | Free (private_pool) |
| The consumer's own machine, or their organization's | That stage is neither charged nor earned |
| A stage sent no receipts | The customer pays, its host gets nothing (system:withheld) |
| A node nobody owns | The customer pays, nobody earns it (system:unattributed) |
| No user behind the request | No charge (no_consumer) |
| Training without parameter counts | Not priced (unpriced) |
An earning's life¶
accrued -> matured -> payable -> pending -> paid
accrued: earned, and on hold for the maturity period.matured: the hold is over, and no audit is open or unresolved on that node. It can be spent, after the owner's wallet.payable: at least the minimum, with the books clean. What was spent is not there to pay out.pending: in an order the payout service holds. It may be on the chain already, so it can no longer be spent or reversed.paid: finalized on the chain.
Any state before pending can be reversed, and the customer gets back everything they paid
for that share. Under SWARM_AUDITS=enforce, a confirmed failure
reverses all of the node's accrued earnings. If that failure is overturned on appeal, the
host's earning returns and the customer keeps the refund. The audit reserve carries that,
and can go negative.
Grants land in a wallet, which can be spent and never becomes payable.
How the books stay honest¶
- Whole numbers. Amounts are integer micro-EUR. APIs show exact decimal strings.
- Double entry. A transaction that does not sum to zero is refused, and a balance is always added up from entries.
- Append-only and chained. Triggers refuse changes, and each entry's hash covers the previous one, so an edit shows.
- A file of its own,
SWARM_LEDGER_DB. Nothing in it is ever deleted, so plan to keep it as long as tax rules ask. Back it up.
Reconciliation runs daily (and on swarm admin ledger reconcile). It checks that all
entries sum to zero, that every transaction balances, that the chain is intact, and redoes
every settlement's arithmetic from its stored inputs.
Any failure stops earnings becoming payable. A later clean run does not lift that. An admin has to look and resume, from the browser.
This does not stop someone who holds the file and rewrites all of it, chain included, unless anchors are running: they publish the chain's head.
Refusals¶
Under enforce, a chat needs its balance to cover the prompt (estimated at four bytes per
token, as the leader has no tokenizer) and max_tokens at the rate. There is no overdraft
on purpose, but requests running at the same time settle after they deliver, so a wallet
can end slightly negative. The next request is then refused. A training job needs a
positive balance, since its cost is not known ahead.
If the ledger itself fails during that check, the request goes through: a bookkeeping fault should not stop serving.
Seeing it¶
| Who | How |
|---|---|
| A user | The profile page, swarm me credits, GET /api/v1/me/credits |
| A user's statement: base, fee, net per line | swarm me credits-statement [--csv], GET /api/v1/me/credits/statement[.csv] |
| A pool's members: what it earned | swarm pools credits, GET /api/v1/pools/{id}/credits |
| An admin | swarm admin ledger, GET /api/v1/admin/ledger |
API tokens can read. Creating credits takes an admin's browser session
(POST /api/v1/admin/ledger/grant), and so does resuming after a failed reconciliation, so
a leaked token cannot mint money.
What this does not settle¶
Whether credits a host earned count as e-money, how VAT applies, and how long records must be kept are questions for a lawyer and a tax advisor. Get those answered before real money stands behind a credit.