Staking
What the Staking addon actually does — operator-funded reward pools, locked positions, APR accrual and platform fees — what it requires, and where to start.
Staking gives your users a place to lock funds from their platform wallet and earn a published APR. They pick a pool, commit an amount for a fixed number of days, and rewards accrue on a schedule you set. At maturity the principal is returned to the same wallet automatically.
It is an addon on top of Bicrypto core. There is no separate database and no ScyllaDB.
Two products, one switch
The addon carries a mode, stakingMode, edited at Staking → Settings.
SYNTHETIC is the fixed-rate product every page in this section describes:
a rate you set, paid from your own funds.
REAL is custodial on-chain staking, and it is built and shipping. Coins
are gathered from the user's own deposit address into a staking wallet the
platform holds, delegated on the network — Solana natively, Ethereum through
Lido — and the rewards are whatever the protocol paid, observed on-chain and
shared by holders in proportion to their stake. You set no rate, you guarantee
nothing, and your income is a commission on rewards that actually arrived.
Turning it on requires the Ecosystem extension and the Web3 Trading addon — sold as Web3 Wallet & On-Chain Trading — both installed, enabled and licensed, a chain activated with its staking wallet and a policy-screened validator set, and the ecosystem key vault unlocked. The settings console names whichever of those is missing rather than saying "not available".
Every pool and every position records the product it was opened under, so a later switch never touches anything already open: both engines keep running for the rows they own, and only NEW stakes follow the switch.
See Settings, Chains and Operations.
The one thing to understand before you enable the fixed-rate product
This is not delegated staking. No validator is involved, nothing is bonded, and no external yield reaches the platform. When a user stakes, the amount is debited from their wallet and held as a database row. When a reward accrues, the platform writes an earning row the user can claim into their wallet, and the backend simultaneously books the gross amount as a platform loss against the Super Admin treasury.
Every percentage point of APR you publish is a percentage point you pay out of
your own float. Your real yield source — an exchange account, an external
staking provider, a lending desk, or nothing at all — lives entirely outside
this product. The pool's profitSource and fundAllocation fields are prose
you show users; the software never reads them.
That single fact drives everything else on these pages: capacity limits are how you cap your liability, the admin fee is how you keep a slice of the yield you are paying, and the admin overview is a solvency console, not a marketing dashboard.
What it requires
| Requirement | Why |
|---|---|
| Bicrypto core | Wallets, users, KYC, roles, settings, the cron process and the fee collector all come from core. Staking adds no infrastructure of its own. |
| The cron process running | Rewards accrue and matured principal is returned by an hourly scheduled task. With the cron down, users' money stays locked past the term they agreed to. |
| A Super Admin user with wallets | Platform fees are credited to the oldest Super Admin's wallet. With no Super Admin configured, every staking fee is silently dropped and logged as [CRITICAL]. |
Ecosystem addon — only for ECO pools |
A pool set to the ECO wallet type needs the currency to exist as an active ecosystem token so the user's ECO wallet and its chain addresses can be created. Pools on SPOT or FIAT need nothing extra. |
Nothing else. Staking does not depend on Ecosystem, Futures, P2P or any other
addon unless you deliberately build ECO pools.
What ships
Fifteen tables, created automatically on boot. Six for the fixed-rate
product, soft-deleted: staking_pools, staking_positions,
staking_earning_records, staking_admin_earnings,
staking_external_pool_performances and staking_admin_activities. Nine for
the on-chain product, never soft-deleted: staking_chain_wallets,
staking_chain_activations, staking_validator_sets, staking_validators,
staking_tranches, staking_batches, staking_observations,
staking_consents, staking_statements and staking_incidents.
Eleven admin screens under /admin/staking — Overview, Pools, Positions,
Earnings, Settings for the fixed-rate product; Chains, Wallets, Validators,
Batches, Incidents, Compliance for the on-chain one (see
Chains).
Six user screens under /staking — Dashboard, Staking Pools, My Positions,
Statements, Staking Guide, and the public landing page. The landing page renders
without a login; everything else requires one.
Seven scheduled tasks. processStakingPositions, hourly, accrues due
fixed-rate rewards and settles matured positions — the only automatic money
mover in the fixed-rate product. For the on-chain product:
processRealStakingBatches (every two minutes) signs and broadcasts due
batches and polls the ones in flight; observeRealStaking (every fifteen
minutes) reads what the network paid; reconcileRealStaking (hourly) compares
the chain with the book and opens incidents; refreshStakingValidatorSets
(every six hours) re-screens every set against the policy; alertRealStaking
(every ten minutes) raises overdue unbonding, stale delegation and commission
alerts; generateRealStakingStatements writes each month's statements. Each of
the six is a no-op until a chain is activated.
Thirty-seven permission keys under *.staking.*, three KYC feature
gates (view_staking, invest_staking, withdraw_staking) and eight
platform settings prefixed staking*.
How the money moves
Follow one 1,000 USDT stake in a pool paying 12% APR with a 20% admin fee, a 30-day lock and daily earnings:
-
The user stakes. 1,000 USDT leaves their SPOT wallet as a
STAKINGdebit. The pool's remaining capacity drops by 1,000. A position row is created withstartDate,endDate30 days out, and a snapshot of the pool's APR, admin fee and early-withdrawal fee — so editing the pool later cannot reprice a lock that has already been agreed. -
Rewards accrue. Once a day the cron computes the reward owed since the position started, subtracts what has already been credited, and writes the difference as an unclaimed earning row. The 20% admin fee is taken off the top: the user's rows add up to 9.6% APR, and the fee leg is credited to the Super Admin wallet.
-
The user claims. Claiming credits every unclaimed row for that position into their wallet as a
STAKING_REWARDtransaction and marks the rows claimed. Rewards do not appear in the wallet until they are claimed. -
The position matures. On the first hourly run after
endDate, the final outstanding reward is accrued, the 1,000 USDT principal is returned to the wallet, the pool's capacity is restored by the original 1,000, and the position is markedCOMPLETED. Unclaimed rewards survive completion and stay claimable.
An early exit changes step 4: the user requests a withdrawal, and depending on your approval policy the position either settles immediately or waits in a queue for you. Either way the pool's early-withdrawal fee is taken out of the principal, priced from the moment the user asked to leave.
The on-chain product
Two venues ship: Solana native delegation and Ethereum through Lido stETH.
When the mode is REAL the flow is different in kind: a stake is a quote, a consent, a ledger debit and a gather signed with the customer's own key; the coins are delegated from platform-owned stake accounts; the reward is what the network paid, observed per epoch; an exit waits the protocol's unbonding and the ledger is credited only when the coins have landed back in the customer's own address. How an on-chain stake moves follows one stake end to end; Chains is where a chain is switched on.
Where to start
Enable the extension row, confirm the cron is scheduled, grant the permissions and set the KYC gates. Nothing works until the extension flag is on.
Every field on the pool form, what "locked" and "flexible" actually mean here, and the capacity field that the edit form cannot change.
The exact formula, what earningFrequency and autoCompound change, why the
cron can never double-pay, and how to distribute by hand.
The four position states, what a withdrawal request does, and the difference between completing and cancelling a position.
One Solana stake, from quote to return, and which task drives each step.
The consoles in on-chain mode, the commission exit, the slashing reimbursement, the alerts, the monthly statements, and the drills to run before the first customer stakes.
The solvency overview, the pool and position tables, and the earnings desk — including which numbers are totals and which are capped lists.
Eight keys. Three of them behave differently when they have never been saved, and one of those disagrees with what the switch on screen shows you.
Reference material sits behind all of them: API and data model lists every endpoint with its permission key and every table with its columns. Troubleshooting covers the failures that look like nothing is wrong.