Smart Contract Function Index

Line-by-line function inventory for the PoX-5 Clarity contract.

This page inventories the integrator-relevant functions in stackslib/src/chainstate/stacks/boot/pox-5.clar, the canonical PoX-5 Clarity boot contract. Line ranges are inclusive and cover each function from its define-* form through its closing parenthesis.

Contract version: 4.0.1

Public Functions

Public Function Summaries

Staking

• stake starts STX-only staking for the caller through a registered signer manager. It validates the signer manager, the start height, the lock period, and the caller's STX balance. Calls during the prepare phase are rejected. A caller with an ending bond or a non-overlapping position can roll over directly into a new stake — the old bond keeps earning for its remaining cycles under its old signer, and the caller cannot manage it any more. A caller with an overlapping bond or an existing STX-only stake cannot stake again.
• stake-update changes an existing STX-only staker's signer, extends their lock, increases their locked amount, or combines those updates. Calls during the prepare phase are rejected.
• unstake shortens an active STX-only staker's remaining participation so their unlock cycle becomes the next reward cycle. Calls during the prepare phase are rejected.

Protocol Bonds

• register-for-bond lets an allowlisted staker join a configured protocol bond. The staker proves L1 BTC lockups or locks sBTC, supplies enough STX, and selects a registered signer manager. Registration must land before the bond starts and outside the prepare phase. A caller with an ending bond or a non-overlapping STX-only stake can roll over directly into the new bond; an overlapping position is rejected. Returns the registered position, including the unlock heights.
• update-bond-registration lets an existing bond participant rotate their signer-manager mid-bond. Rotating to the same signer is rejected, as are calls during the prepare phase. Only bond participants can use this entrypoint — STX-only stakers cannot.
• announce-l1-early-exit marks an L1-locked bond participant as exited early after their BTC timelock is spent off-cycle. Only the staker themselves can call it, and only directly (not via another contract). The old-signer-manager argument must be the staker's currently-recorded signer. The call removes the position's remaining reward shares; the staker's locked STX remains locked through the bond's normal unlock cycle. sBTC-locked participants use unstake-sbtc instead.
• unstake-sbtc lets an sBTC-locked bond participant withdraw some or all of their locked sBTC, at any time outside the prepare phase — including after the bond is over. L1-locked memberships cannot use it.

Rewards

• calculate-rewards computes the latest reward distribution across active protocol bonds and STX-only staking. Anyone can call it; it runs at most once per distribution height and requires all active bonds to be listed in the call.
• claim-rewards lets a signer claim accumulated sBTC rewards for a reward cycle and a supplied list of bond periods. The contract transfers the total sBTC to the caller and returns a breakdown per leg.
• claim-staker-rewards-for-signer (signer-manager only) settles a single staker's accumulated sBTC under one cycle/bond leg for the calling signer-manager's accounting. It does not transfer sBTC — the signer-manager pays the staker out of what it received from claim-rewards.

Signer Management

• register-signer registers a signer manager contract and its signer key. The signer manager contract must call it directly.
• grant-signer-key records permission for a signer manager to use a signer key, verified by a one-time signature.
• revoke-signer-grant removes an existing signer-key grant. Only the principal derived from the signer key can call it.

The Endowment configures each bond period with setup-bond and operates the remaining admin entrypoints. Integrators do not call these; see Onboarding for what to submit to the Endowment instead.

Relevant Public Function Locations

Function	Lines
stake	pox-5.clar:976:1086
stake-update	pox-5.clar:1092:1173
unstake	pox-5.clar:1424:1470
register-for-bond	pox-5.clar:642:842
update-bond-registration	pox-5.clar:850:943
announce-l1-early-exit	pox-5.clar:1196:1257
unstake-sbtc	pox-5.clar:1261:1342
calculate-rewards	pox-5.clar:2158:2240
claim-rewards	pox-5.clar:2387:2438
claim-staker-rewards-for-signer (signer-manager)	pox-5.clar:2444:2470
register-signer	pox-5.clar:946:973
grant-signer-key	pox-5.clar:2743:2811
revoke-signer-grant	pox-5.clar:2824:2860

Read-only Public Functions

Rewards

Function	Lines
get-rewards	pox-5.clar:2135:2145
get-new-rewards	pox-5.clar:2149:2156
get-earned	pox-5.clar:2341:2354
get-earned-staker-rewards	pox-5.clar:2358:2373
compute-earned-rewards	pox-5.clar:2378:2385
assert-all-active-bonds-included	pox-5.clar:2616:2637

get-earned returns a signer's accrued sBTC; get-earned-staker-rewards is its per-staker counterpart. See Rewards.

Signer Key Grants

Function	Lines
get-signer-grant-message-hash	pox-5.clar:2865:2877
verify-signer-key-grant	pox-5.clar:2879:2890

Bitcoin SPV / Lockup Helpers

These read-onlys are exposed at the contract surface but are primarily used internally during L1 lockup verification. They are listed for completeness rather than as a public API. At registration, the contract validates each lockup output: it reconstructs the expected P2WSH script for the output's committed unlock height, and checks the script, the amount, the block header, and the merkle proof. A registration with an invalid output is rejected.

construct-lockup-script builds the L1 lockup witness script from the caller-supplied staker-unlock-bytes and early-unlock-bytes. Both must be pre-pushed, self-contained script fragments that leave a boolean result on the stack. See the lockup-script section of paired-btc for the full template and the height limits that apply to the CLTV branch.