Operating on-chain staking

Everything that moves coins runs on the scheduled tasks. What a person holds is a small set of doors, each of which refuses by name what it cannot do safely. This page is the runbook for those doors, and the drills to run on a test network before the first customer stakes.

The consoles

Six consoles sit under Staking → On-chain, grouped behind one nav parent. Overview, Pools, Positions, Earnings and Settings sit at the top level beside it. All eleven are reachable in either mode — the engines are gated on rows, not on stakingMode, so a fixed-rate install that once started an activation can still hold a stuck batch and an open incident.

The permission below is the one that opens the screen. The write doors inside ask for their own, and those are named where they appear on this page.

Activating a chain, screening validators, reading a batch's approved intent and the six incident kinds the reconciler opens are all on Chains, wallets and validators. The settings themselves are on Staking settings. What follows is what you do after those are already true.

Overview — per wallet: the native balance the reconciler last read, the gas reserve floor, and the book value the pools on that key say is delegated. Per pool: on-chain value, share price, unallocated value, holders by state, the observer's last read and whether it lags, the validator set's policy verdict, the commission held as treasury shares and what of it has been realised, and the unbonding ladder — what is due back, by day, with anything past the promised bound marked. Open incidents and in-flight batches sit at the bottom. Refreshes every minute while the tab is visible; reads only.

Pools — the form has no rate, lock, capacity, early fee, cadence or tiers for an on-chain pool. You choose an activated chain; the venue, the wallet, the validator set, the slashing policy and the commission notice come from the activation and are shown read-only. A pool's detail page gains an On-chain tab: the same commission ledger the Earnings page renders, the tranches (stake accounts or Lido shares) with their validator and observed value, and the observations that moved the share price.

Compliance — the activation record each chain was opened under and the rules it derived, every consent recorded at the stake door, every monthly statement written, and CSV exports of consents, activations and observations. One write: Write missing statements for a period ahead of the nightly run.

The scheduled tasks

Nothing on the consoles moves coins. Six registered jobs do. Admin → System → Cron lists them by their on-screen title; the logs, the refusal state and the API use the registered name.

A seventh staking job, processStakingPositions ("Process Staking Logs", hourly), settles the fixed-rate product and touches no on-chain position.

Three things about these rows that will otherwise mislead you.

The batch runner survives the addon being switched off. processRealStakingBatches is flagged returnsCustomerMoney, and a job with that flag is scheduled on the disabled branch as well as the enabled one — disabling the extension closes its routes so nothing new can start, and leaves the runner claiming unbonded stake and sending it back. The only thing that does bring it down is a hard stop (stopEverything on the addon toggle), which records the addon in the hard-stop list. Nothing else in the product returns a holder's coins, so a hard stop with positions in UNBONDING strands them until you lift it.

REFUSED is a failure state, and it is per job. When @b/api/(ext)/staking/utils/real/cron fails to load, one alert goes out per broken module — not per job — but the refusal state is set on each of the six, and the cron page shows all six rows refused. Read the loader's own message in the refusal: a missing dependency usually means the addon was built against a newer core than the one installed.

A module that is simply absent is silent. addonCronModule distinguishes "failed to load" from "not installed"; the second returns null without an alert, the wrapper returns undefined, and the job is recorded as having completed. Six green rows on an install without the addon mean nothing ran.

The two doors on a position

Positions is the only console with a write door onto an on-chain position, and it holds two. Both take a reason rather than a yes or no, because both are things you do to a holder's position without being asked; both refuse an empty one with 400 and show the reason to the holder. There is no approve, decline, complete or cancel on an on-chain row: a protocol exit needs no human, and the fixed-rate withdrawal pair can never appear for one. The states these doors move a position between are laid out in How a stake moves.

Force unstake… appears on a position in ACTIVE and nowhere else — once the row is UNSTAKE_REQUESTED the protocol has the request and nothing can be started again. It starts the ordinary exit: the share price freezes, rewards stop at the request, the row walks UNSTAKE_REQUESTED → UNBONDING → WITHDRAWABLE → COMPLETED, and the coins go to the holder's own deposit address when the network releases them. It cannot be cancelled once queued.

Abandon and return coins… appears on a position in PENDING_DELEGATION that has a non-zero on-chain principal, and nowhere else. It is the door for coins that reached the staking wallet and could not be delegated — the batch runner already retries on its own, and this is the other half of that rule. It is the only way a holder whose coins sat in the staking wallet gets them back.

It does not refund from the platform. The position becomes WITHDRAWABLE for the amount that actually reached the staking wallet, the ordinary return pass sends that amount on-chain to the holder's own deposit address, and it is credited only once the transfer has landed — the same rule every other exit follows. The position then finishes FAILED, carrying the reason.

It refuses, by name, three positions that look abandonable and are not:

So FAILED has two roads into it, and both start at PENDING_DELEGATION: a gather that never landed, which refunds exactly; and this door, which routes through WITHDRAWABLE first. The model's comment says FAILED is reachable only from PENDING_DELEGATION — it is describing the first road.

Earnings, in REAL mode

/admin/staking/earning renders a different page in each mode. In SYNTHETIC it is the fixed-rate earnings table — what the platform typed, funded and distributed. In REAL the switch renders the commission ledger instead: what the network paid, the share the disclosure said the platform keeps, and what of that has reached the platform's own address. Nothing on it is typed or distributed.

Each pool card carries four figures — what the treasury holds now (shares × today's price), the commission minted at observations for all time, the amount realised to the platform's address for all time, and the exit in progress if there is one. Accrued and realised will not agree and are not meant to: the first is the accrual ledger the observer writes, the second is what has been paid.

Beneath them, once a pool has queued at least one, is the exit history in seven columns. The QUEUED → UNBONDING → SETTLED → PAID walk below is only legible against them:

Requested value and Settled differ whenever the price moved. Settlement burns at the lower of the request price and the current price, the same rule a customer's exit settles under, so a fall between the request and the return is taken by the treasury and a rise is not kept by it.

The commission exit

Commission is minted as treasury shares on the pool at every observation with a positive gross reward, so it rises and falls with every holder's shares and is slashed with them. Nothing is booked as revenue until the coins reach the platform's own address:

1. Unstake commission queues N treasury shares (default: all). At most one open request per pool; refused while the staking wallet is frozen, and refused when the chain has no ecosystem master wallet to pay to.
2. The engine's next exit batch covers the queued value together with the users' exits, users first in FIFO order.
3. When the coins are back, settlement burns the shares from the treasury at the lower of the request price and the current price — after every user exit ahead of it has been paid. If the users ahead of it starve the unallocated value, the commission waits for the next claim.
4. The engine transfers the settled amount from the staking wallet to the chain's ecosystem master wallet. The firewall allows that one destination and nothing else; a frozen wallet does not sign it and the row waits.

The row walks QUEUED → UNBONDING → SETTLED → PAID and is the realised ledger; the accrual rows the observer writes are the accrued ledger. The two are shown side by side.

The slashing reimbursement

A validator penalty reduces the pool's value for every holder. What an operator may promise on top is declared at activation: PASS_THROUGH, or REIMBURSE_CAPPED with a cap per incident. Reimburse… on a SLASHING incident pays that promise and nothing beyond it:

• at most the cap per incident, cumulatively across calls, never more than the recorded loss; in parts if you prefer, each part keyed on what was already paid so a retried request cannot pay twice;
• pro rata to the holders by their shares (a queued exit's shares still took the loss, so they count);
• from the Super Admin's ECO wallet for the pool's currency, which must hold the amount — a reimbursement the treasury cannot fund is refused with the shortfall named, never booked as a credit the platform does not have;
• the incident records the amount and resolves itself when the cap is reached.

Nothing on-chain moves. Each holder is notified with the amount and the incident, under the title Validator penalty reimbursed.

Alerts

reconcileRealStaking raises hourly what can be checked against the chain: gas reserve, share-ledger and value drift, observer lag, stuck batches, validator policy. alertRealStaking raises every ten minutes what is a matter of time on the platform's own rows:

Every alert dedupes on its key while open, clears itself when the condition ends, and never blocks an exit. New incidents notify every admin who can see them.

What the holder is told

Every on-chain engine writes an in-app notification against the position, with a link to it, at each point where the holder's money changes hands. These are the titles, so you can match a support ticket to a step without guessing:

The unstake messages carry the unbonding estimate and bound the pool published, not a fixed figure; the reimbursement message names the incident.

Statements

Once a day the statements job writes the previous month's statement for every user who held an on-chain position in it: staked in the period, exited in the period, rewards net of commission, the commission attributed to them (each earning row's net × the observation's commission ÷ net, which is exact under the pro-rata rule the observer applies), and the value of their shares at the time of writing, labelled as such. One CSV per user and month, hashed, never regenerated. Users download theirs from Staking → Statements; the compliance console lists them all and can write a period early.

The liquid exit, and why it is off

An Ethereum pool can be set to sell its stETH on Curve's stETH/ETH pool rather than joining Lido's withdrawal queue, which releases an exit in minutes instead of days. It is off on every pool and you turn it on per pool, with a slippage cap in basis points.

What the cap does: the engine asks the venue what it would pay before it commits. If that price is worse than your cap against the protocol price, it does not sell — the exit joins the withdrawal queue as usual. The difference between the market price and the protocol price is borne by the holder who is leaving, never by the holders who stay, and the pool's disclosure states the cap as a number so they know it before they stake.

What protects it: the platform builds the swap itself against one named contract, and the firewall decodes every argument back out before the key signs — the pool address, the direction, the exact amount, and a minimum-out floor computed from your cap before any price is read. No aggregator is involved. A payload the firewall cannot read in full is refused rather than signed.

Before you enable it on a pool holding customer money: there is no test network for this path. Hoodi, where the rest of the Ethereum engine is rehearsed, has no Curve deployment. Turn it on for a pool with a small position first, watch one exit through end to end, and only then leave it on at scale.

Drills

Run these on a test network (Solana devnet or a local validator; Lido on Hoodi) with a funded staking wallet, before the first customer stakes, and again after any change to the engine.

1. Kill switch — pause the chain under Chains. Confirm the stake door refuses with the pause named, and that a queued exit still deactivates, claims and returns on schedule. Resume.
2. Freeze — freeze the staking wallet with a reason. Confirm a stake is refused, a delegation batch waits, and an exit, claim, return and refund still sign. Confirm a commission payout waits. Unfreeze; confirm the waiting batches land.
3. Force-unstake — force-unstake a test position in ACTIVE with a reason. Confirm the notification reads Unstake started by the platform and carries the reason, the row walks UNSTAKE_REQUESTED → UNBONDING → WITHDRAWABLE → COMPLETED, and the credit carries the return transaction hash. Confirm an empty reason is refused.
4. Abandon — pause the batch runner (or use a position whose delegation is failing) so a test stake sits in PENDING_DELEGATION with its coins in the staking wallet, then abandon it with a reason. Confirm the notification reads Stake abandoned, the position goes WITHDRAWABLE for the amount that reached the wallet rather than the amount requested, the return is an on-chain transfer to the holder's own deposit address, the credit lands only after the transfer does, and the position finishes FAILED with the reason on it. Confirm the door refuses a position in any other state, a position with nothing on-chain, and an empty reason.
5. Commission — with treasury shares accrued, queue a commission exit. Confirm it settles after the test positions' exits, that the share invariant reconciles, and that the payout lands in the master wallet with the row PAID.
6. Slashing — on a REIMBURSE_CAPPED activation, open a SLASHING incident by hand (or wait for a negative observation on the test network), fund the Super Admin's ECO wallet, and reimburse. Confirm the pro-rata credits, the cap, the refusal above the cap, and the refusal with an underfunded treasury.
7. Observer lag — stop observeRealStaking for longer than two of a pool's observation windows. Confirm OBSERVER_LAG opens, that exits still run, and that it clears when the job resumes.
8. Overdue exit — set a test position's unbondingBoundAt in the past. Confirm UNBONDING_OVERDUE opens and clears when the position settles.
9. Statements — write a period from the compliance console. Confirm one row per test user, the CSV's hash matches its content, and a second run writes nothing.
10. Restore — with the database restored from the last backup and the staking wallet's key material intact, confirm the reconciler reports the on-chain state against the book with no drift incident, and that in-flight batches settle from their recorded signatures without a rebuild.

Record the date and the outcome of each drill in the activation's validatorDueDiligence notes or your own change log.