> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/pox-5/contract.md).

# Smart Contract Function Index

This page inventories every function in `stackslib/src/chainstate/stacks/boot/pox-5.clar`, the canonical [PoX-5](/pox-5/glossary.md#pox-pox-4-pox-5-pox-6) Clarity boot contract. Line ranges are inclusive and cover each function from its `define-*` form through its closing parenthesis.

Contract version: `abdffd5d6c707c2ae675ec8e717dbc592c03ea93`

### Summary

| Visibility       | Count |
| ---------------- | ----: |
| Public           |    18 |
| Read-only public |    70 |
| Private          |    31 |
| Total            |   119 |

### Public Functions

#### Public Function Summaries

**Staking**

* `stake` starts STX-only staking for the caller through a registered signer manager. It validates the signer manager callback, start burn height, lock period, and total STX balance (locked + unlocked, so a rollover's locked STX still counts). Rejects calls during the [prepare phase](/pox-5/glossary.md#prepare-phase-prepare-window) (`ERR_STAKE_IN_PREPARE_PHASE u47`). If the caller has an existing position, `stake` permits a **rollover** from a non-overlapping bond membership: `verify-bond-rollover-window` requires the existing bond to be inside its L1 unlock window (`ERR_ROLLOVER_TOO_EARLY u48`), `roll-sbtc` net-transfers any custodied sBTC, and the old `protocol-bond-memberships` entry is cleared before the new staker record is written. A rollover only **adds** the new position's shares — the prior bond's per-cycle shares and per-cycle signer delegation are left in place through the bond's remaining term, since rewards for those cycles are still owed to the old signer. Only the management pointer (`protocol-bond-memberships`) is cleared, which prevents `unstake-sbtc` / `update-bond-registration` from reaching the old bond. Overlapping bond memberships and existing STX-only stakes still revert (`ERR_ALREADY_STAKED u19`).
* `stake-update` changes an existing STX-only staker's signer, extends their lock, increases their locked amount, or combines those updates. It validates the new staking terms, removes the staker from remaining future cycles, re-adds them under the new signer and amount, settles the old and new signer's rewards plus the staker's per-signer rewards, and updates their stored staking info. Rejects calls during the prepare phase (`ERR_STAKE_IN_PREPARE_PHASE u47`).
* `unstake` shortens an active STX-only staker's remaining participation so their unlock cycle becomes the next reward cycle. It rejects calls during the prepare phase (`ERR_UNSTAKE_IN_PREPARE_PHASE u28`), settles staker-level rewards before mutating shares, removes the staker from future cycles, and updates their staking record to reflect the earlier unlock.

**Protocol Bonds**

* `register-for-bond` lets an allowlisted staker join a configured protocol bond by proving L1 BTC lockups (`ERR_DUPLICATE_LOCKUP_OUTPOINT u46` on a repeated outpoint in the proof list) or locking sBTC, supplying enough STX, and selecting an already registered signer manager. On the L1 path, each output tuple in the `btc-lockup` argument carries its own `unlock-burn-height: uint`. The staker may commit any height at or above the bond's minimum L1 unlock height (`get-bond-l1-unlock-height`) and below `BITCOIN_LOCKTIME_THRESHOLD` (`u500000000`), chosen independently per output; a height outside that range reverts with `ERR_INVALID_UNLOCK_HEIGHT u52`. The expected timelock witness script is reconstructed per output from that height via `construct-lockup-output-script` inside the `validate-l1-lockup` fold. The STX-balance check uses the staker's total balance (locked + unlocked) so a rollover whose STX is still locked by an ending bond is not falsely rejected. It enforces that the bond hasn't started yet (`ERR_BOND_ALREADY_STARTED u43`) and rejects calls during the prepare phase (`ERR_STAKE_IN_PREPARE_PHASE u47`). If the caller has an existing position, a **rollover** is allowed from a non-overlapping STX-only stake or from a bond inside its L1 unlock window — `bond-overlaps-new-position?` rejects overlap (`ERR_ALREADY_REGISTERED u9`), `verify-bond-rollover-window` rejects rollover before the prior bond's L1 unlock (`ERR_ROLLOVER_TOO_EARLY u48`), and `roll-sbtc` net-transfers any custodied sBTC. Settles both signer-level and per-staker rewards on the affected signer(s) before any share-map write. Returns `(ok { signer, staker, amount-ustx, sats-total, is-l1-lock, bond-index, first-reward-cycle, unlock-burn-height, unlock-cycle, btc-lockup })`, where `unlock-burn-height` is the start of the unlock cycle (`reward-cycle-to-burn-height`) and `btc-lockup` carries `{ type: "l1", txs: (some [{txid, output-index}...]) }` for L1 lockups and `{ type: "l2", txs: none }` for sBTC.
* `update-bond-registration` lets an existing bond participant rotate their signer-manager mid-bond. It rejects rotating to the same signer (`ERR_UPDATE_BOND_SAME_SIGNER u44`), rejects calls during the prepare phase (`ERR_STAKE_IN_PREPARE_PHASE u47`), validates the new manager via `validate-stake!`, settles both signer-level and per-staker rewards on the old and new signers, removes the staker from the remaining cycles under the old signer, and re-adds them under the new signer for the rest of the bond period. STX-only stakers cannot use this entrypoint — only callers with an active `protocol-bond-memberships` record qualify.
* `announce-l1-early-exit` marks an L1-locked bond participant as having exited early after their BTC timelock fires off-cycle. Only the staker themselves can call it, and only directly (not via another contract) — the contract asserts `contract-caller == tx-sender == staker` (`ERR_UNAUTHORIZED u1`). Rejects calls during the prepare phase (`ERR_STAKE_IN_PREPARE_PHASE u47`). Fails if the staker has already announced an early exit for this bond (`ERR_L1_EARLY_EXIT_ALREADY_ANNOUNCED u50`). For each affected cycle from `clamp(current-cycle, bond-start-cycle, bond-end-cycle)` through the bond's end, the staker's shares are zeroed via the shared `unstake-sats-from-bond-cycles` helper: the helper derives the signer for that cycle from `staker-signer-cycle-memberships`, settles signer-level and per-staker rewards for that cycle, then debits `total-shares-staked-for-cycle` / `signer-shares-staked-for-cycle` and zeroes `staker-shares-staked-for-cycle`. The function then zeroes `amount-sats` in the membership record, flips `protocol-bond-l1-early-exit-announced` for this `{ bond-index, staker }` to `true`, and decrements `protocol-bonds-total-staked`. The staker's locked STX remains locked through the bond's normal unlock cycle. sBTC-locked participants must use `unstake-sbtc` instead (`ERR_CANNOT_ANNOUNCE_L1_EARLY_UNLOCK u35`).
* `unstake-sbtc` lets an sBTC-locked bond participant withdraw some or all of their locked sBTC. Reverts on L1-locked memberships (`ERR_CANNOT_UNSTAKE_SBTC u38`) and during the prepare phase (`ERR_STAKE_IN_PREPARE_PHASE u47`). Iterates affected cycles via `unstake-sats-from-bond-cycles`, which — for each cycle — derives the signer from `staker-signer-cycle-memberships` (since `update-bond-registration` can leave a staker with different signers across the current cycle vs. future cycles), settles signer-level and per-staker rewards for that cycle, debits the share totals by the withdrawal amount, and writes the staker's new per-cycle share count. The function then decrements `total-sbtc-staked` and transfers the requested sBTC from the contract back to the staker. Because there is no cycle/bond-boundary check (outside the prepare-phase window), an sBTC bond participant can also unstake their sBTC after the bond is over to recover the locked amount.

**Rewards**

* `calculate-rewards` computes the latest reward distribution across active protocol bonds and STX-only staking. It prevents duplicate computation for the same distribution height, requires all active bonds to be included in `bond-periods` (in the canonical order — descending `stx-value-ratio`, then ascending `bond-index` as tiebreaker), allocates remaining rewards between the reserve and STX stakers, updates `rewards-per-token-for-cycle`, and records the calculation height. Per-bond target yield is `(totalSats × targetRate / 10_000) / 50` — i.e. `targetRate` (apy in bps) divided by 50 distributions per year. When a cycle has **no STX-only stakers**, the staker cut is folded into `reserve-balance` as `unallocated-staker-cut` rather than left in `rewards-per-token-for-cycle` (where it would otherwise produce phantom claimable rewards for below-threshold signers). Gated by `validate-no-reentrancy` (`ERR_REENTRANT_CALL u49`) so a signer-manager cannot trigger reward computation from inside `validate-stake!`.
* `claim-rewards` lets a signer claim accumulated sBTC rewards for a reward cycle and a supplied list of bond periods. It first asserts that reward claims are not paused (`ERR_REWARDS_PAUSED u53`); rewards keep accruing in the contract while paused, and the pause is one-way, so recovery requires a hard fork. It settles signer-level rewards across each leg, zeroes signer-level pending balances, transfers the total sBTC amount from the contract to the caller, reduces `last-accounted-rewards-only`, and returns `(ok { stx-rewards, bond-rewards, bond-totals, total-rewards })`. Each `stx-rewards` entry and each item within `bond-rewards` carries `{ earned, rewards-per-token }` (plus `bond-index` on the bond entries) — the snapshot of cumulative per-share rewards used to compute that leg's payout.
* `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 calls `settle-staker-rewards(contract-caller, reward-cycle, bond-index, staker)`, zeroes the matching `staker-unclaimed-rewards-for-cycle` entry, emits a `claim-staker-rewards-for-signer` print event with the `rewards-claimed` amount, and returns the settled `rewards-info`. **It does not transfer sBTC and does not modify `last-accounted-rewards-only`** — the signer-manager is responsible for paying the staker out of the sBTC it received from `claim-rewards`. The function is reentrancy-guarded (`ERR_REENTRANT_CALL u49`); the per-staker entries it touches are keyed by `contract-caller`, so the call is meaningful only for the signer-manager whose accounting this staker is recorded under.

**Signer Management**

* `register-signer` registers a signer manager contract and its signer key after verifying that the signer key grant exists. The `contract-caller` must equal the signer manager contract itself (no forwarding), then stores the signer key in the `signers` map.
* `grant-signer-key` records permission for a signer manager to use a signer key. The `contract-caller` must equal the signer manager itself. It verifies a one-time secp256k1 signature over the signer manager and auth id, marks that grant authorization as used, and stores the signer-key grant.
* `revoke-signer-grant` removes an existing signer-key grant for a signer manager. The `contract-caller` must be the Stacks principal derived from the signer key — the call cannot be forwarded through an intermediary contract — and the function returns whether the grant entry was deleted.

**Initialization And Admin**

* `set-burnchain-parameters` initializes the contract's burnchain timing parameters, including the first burn height, prepare-cycle length, reward-cycle length, and first PoX-5 reward cycle. It can only run once because it checks and then sets the `configured` flag before returning `ok true`.
* `setup-bond` **(admin)** lets the bond admin configure a protocol bond period. Parameters: `bond-index` (the identifier of the bond period), `target-rate` (APY in bps), `stx-value-ratio` (uSTX per 100 sats), `min-ustx-ratio` (minimum STX collateral ratio in bps), `early-unlock-bytes` (the early-exit subscript), and `allowlist` (per-staker max-sats entries). It enforces that setup happens in the allowed window before the bond starts, inserts the bond configuration via `map-insert` (a duplicate `bond-index` fails with `ERR_BOND_ALREADY_SETUP u4`), and folds over the allowlist to record each participant's maximum BTC allocation.
* `set-bond-admin` **(admin)** rotates the `bond-admin` data var to a new principal. Only the current `bond-admin` may call it (gated on `contract-caller`); all other callers get `ERR_UNAUTHORIZED`. On non-mainnet networks the node rewrites the initial admin literal at deploy time via the `pox_5_bond_admin` config, so testnets can bootstrap an operator without a separate transaction.
* `set-pause-admin` **(admin)** rotates the `pause-admin` data var to a new principal. Only the current `pause-admin` may call it (gated on `contract-caller`); all other callers get `ERR_UNAUTHORIZED`. It is reentrancy-guarded (`ERR_REENTRANT_CALL u49`) and prints a `set-pause-admin` event. `pause-admin` defaults to the burn address; on non-mainnet networks the node rewrites the initial literal at deploy time so testnets can bootstrap a pause operator.
* `pause-rewards` **(admin)** permanently halts signer reward claims: only the current `pause-admin` may call it, it is reentrancy-guarded (`ERR_REENTRANT_CALL u49`), and it sets the `rewards-paused` data var to `true` and prints a `pause-rewards` event. It is **one-way and irreversible** — there is no unpause entrypoint. After it runs, every `claim-rewards` call reverts with `ERR_REWARDS_PAUSED u53`; rewards continue to accrue in the contract, and releasing them requires a hard fork.

#### Public Function Locations

| Function                                               |                                                                                                                                                     Lines |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `stake`                                                |   [pox-5.clar:976:1086](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L976-L1086) |
| `stake-update`                                         | [pox-5.clar:1092:1173](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1092-L1173) |
| `unstake`                                              | [pox-5.clar:1424:1470](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1424-L1470) |
| `register-for-bond`                                    |     [pox-5.clar:642:842](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L642-L842) |
| `update-bond-registration`                             |     [pox-5.clar:850:943](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L850-L943) |
| `announce-l1-early-exit`                               | [pox-5.clar:1196:1257](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1196-L1257) |
| `unstake-sbtc`                                         | [pox-5.clar:1261:1342](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1261-L1342) |
| `calculate-rewards`                                    | [pox-5.clar:2158:2240](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2158-L2240) |
| `claim-rewards`                                        | [pox-5.clar:2387:2438](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2387-L2438) |
| `claim-staker-rewards-for-signer` **(signer-manager)** | [pox-5.clar:2444:2470](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2444-L2470) |
| `register-signer`                                      |     [pox-5.clar:946:973](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L946-L973) |
| `grant-signer-key`                                     | [pox-5.clar:2743:2811](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2743-L2811) |
| `revoke-signer-grant`                                  | [pox-5.clar:2824:2860](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2824-L2860) |
| `set-burnchain-parameters`                             |     [pox-5.clar:430:449](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L430-L449) |
| `setup-bond` **(admin)**                               |     [pox-5.clar:515:598](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L515-L598) |
| `set-bond-admin` **(admin)**                           |     [pox-5.clar:451:467](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L451-L467) |
| `set-pause-admin` **(admin)**                          |     [pox-5.clar:470:484](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L470-L484) |
| `pause-rewards` **(admin)**                            |     [pox-5.clar:489:497](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L489-L497) |

### Read-only Public Functions

#### Rewards

| Function                           |                                                                                                                                                     Lines |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `get-rewards`                      | [pox-5.clar:2135:2145](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2135-L2145) |
| `get-new-rewards`                  | [pox-5.clar:2149:2156](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2149-L2156) |
| `get-earned`                       | [pox-5.clar:2341:2354](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2341-L2354) |
| `get-earned-staker-rewards`        | [pox-5.clar:2358:2373](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2358-L2373) |
| `compute-earned-rewards`           | [pox-5.clar:2378:2385](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2378-L2385) |
| `assert-all-active-bonds-included` | [pox-5.clar:2616:2637](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2616-L2637) |

`get-earned-staker-rewards` is the per-staker counterpart of `get-earned`: it returns how much sBTC a single staker has accrued under a given signer for one cycle/bond leg. `compute-earned-rewards` is a pure-math helper that both `get-earned` and `get-earned-staker-rewards` delegate to (`((current-rpt - settled-rpt) * shares) / PRECISION + unclaimed`).

#### Signer Key Grants

| Function                        |                                                                                                                                                     Lines |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `get-signer-grant-message-hash` | [pox-5.clar:2865:2877](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2865-L2877) |
| `verify-signer-key-grant`       | [pox-5.clar:2879:2890](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2879-L2890) |

#### Bond / Cycle / Height Conversions

| Function                            |                                                                                                                                                     Lines |
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `bond-period-to-burn-height`        | [pox-5.clar:2895:2897](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2895-L2897) |
| `bond-period-to-reward-cycle`       | [pox-5.clar:2900:2902](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2900-L2902) |
| `burn-height-to-reward-cycle`       | [pox-5.clar:2906:2910](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2906-L2910) |
| `reward-cycle-to-burn-height`       | [pox-5.clar:2913:2917](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2913-L2917) |
| `current-pox-reward-cycle`          | [pox-5.clar:2920:2922](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2920-L2922) |
| `burn-height-to-distribution-index` | [pox-5.clar:2926:2930](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2926-L2930) |
| `current-distribution-cycle`        | [pox-5.clar:2933:2935](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2933-L2935) |
| `distribution-cycle-to-burn-height` | [pox-5.clar:2938:2942](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2938-L2942) |
| `is-in-prepare-phase`               | [pox-5.clar:2945:2950](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2945-L2950) |
| `is-bond-active-at-height`          | [pox-5.clar:3027:3041](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3027-L3041) |
| `get-bond-l1-unlock-height`         | [pox-5.clar:3342:3346](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3342-L3346) |

Public functions return `unlock-burn-height` as the start of the unlock cycle (`reward-cycle-to-burn-height`). `get-bond-l1-unlock-height` is the L1 CLTV re-lock window — half-cycle-before-cycle-end — and is the right read for L1 timelock construction.

#### Bond / Staker / Signer Reads

| Function                                         |                                                                                                                                                     Lines |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `get-pox-info`                                   | [pox-5.clar:3044:3053](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3044-L3053) |
| `get-bond-allowance`                             | [pox-5.clar:3055:3063](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3055-L3063) |
| `get-bond-membership`                            | [pox-5.clar:3066:3079](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3066-L3079) |
| `get-protocol-bond`                              | [pox-5.clar:3322:3324](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3322-L3324) |
| `min-ustx-for-sats-amount`                       | [pox-5.clar:3089:3095](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3089-L3095) |
| `get-staker-info`                                | [pox-5.clar:3099:3113](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3099-L3113) |
| `get-signer-info`                                | [pox-5.clar:3115:3117](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3115-L3117) |
| `get-amount-delegated-for-signer`                | [pox-5.clar:3121:3131](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3121-L3131) |
| `get-signer-cycle-membership`                    | [pox-5.clar:3134:3142](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3134-L3142) |
| `get-staker-custodied-sbtc`                      | [pox-5.clar:2967:2975](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2967-L2975) |
| `bond-overlaps-new-position?`                    | [pox-5.clar:2983:3002](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2983-L3002) |
| `get-total-sbtc-staked-for-bond`                 | [pox-5.clar:3144:3146](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3144-L3146) |
| `get-rewards-per-token-for-cycle`                | [pox-5.clar:3148:3158](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3148-L3158) |
| `get-total-shares-staked-for-cycle`              | [pox-5.clar:3160:3170](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3160-L3170) |
| `get-signer-shares-staked-for-cycle`             | [pox-5.clar:3172:3184](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3172-L3184) |
| `get-staker-shares-staked-for-cycle`             | [pox-5.clar:3187:3201](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3187-L3201) |
| `get-signer-rewards-per-token-settled-for-cycle` | [pox-5.clar:3203:3215](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3203-L3215) |
| `get-signer-unclaimed-rewards-for-cycle`         | [pox-5.clar:3217:3229](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3217-L3229) |
| `get-staker-rewards-per-token-settled-for-cycle` | [pox-5.clar:3231:3245](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3231-L3245) |
| `get-staker-unclaimed-rewards-for-cycle`         | [pox-5.clar:3247:3261](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3247-L3261) |
| `get-signer-rewards-per-token-for-cycle`         | [pox-5.clar:3263:3275](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3263-L3275) |
| `get-signer-pending-staked-ustx-per-cycle`       | [pox-5.clar:3277:3287](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3277-L3287) |
| `get-last-reward-compute-height`                 | [pox-5.clar:3289:3291](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3289-L3291) |
| `get-reserve-balance`                            | [pox-5.clar:3293:3295](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3293-L3295) |
| `get-total-sbtc-staked`                          | [pox-5.clar:3297:3299](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3297-L3299) |
| `get-last-accounted-rewards-only`                | [pox-5.clar:3301:3303](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3301-L3303) |
| `get-ustx-delegated-for-cycle`                   | [pox-5.clar:3305:3307](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3305-L3307) |
| `get-total-ustx-stacked`                         | [pox-5.clar:3311:3313](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3311-L3313) |
| `check-pox-lock-period`                          | [pox-5.clar:3315:3320](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3315-L3320) |
| `has-announced-l1-early-exit`                    | [pox-5.clar:3328:3338](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3328-L3338) |
| `get-first-pox-5-reward-cycle`                   | [pox-5.clar:3348:3350](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3348-L3350) |
| `clamp`                                          | [pox-5.clar:3353:3365](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3353-L3365) |

`get-staker-custodied-sbtc` returns the sBTC amount the contract currently custodies for a given staker (the source side of `roll-sbtc`). `bond-overlaps-new-position?` is the pure overlap predicate `stake` and `register-for-bond` use to decide whether an existing membership blocks a rollover; integrators can use it before broadcasting to pre-check rollover eligibility.

> `get-total-ustx-stacked` is a thin alias over `get-ustx-delegated-for-cycle`. The name is required so that `chainstate.get_total_ustx_stacked` in the node can read it for `/v2/pox` compatibility.

#### Per-cycle Signer Linked List

| Function                              |                                                                                                                                                     Lines |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `get-signer-set-last-item-for-cycle`  | [pox-5.clar:3392:3394](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3392-L3394) |
| `get-signer-set-first-item-for-cycle` | [pox-5.clar:3396:3398](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3396-L3398) |
| `get-signer-set-item-for-cycle`       | [pox-5.clar:3400:3408](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3400-L3408) |
| `get-signer-set-next-item-for-cycle`  | [pox-5.clar:3410:3421](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3410-L3421) |
| `get-signer-set-prev-item-for-cycle`  | [pox-5.clar:3423:3434](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3423-L3434) |
| `signer-set-contains-for-cycle`       | [pox-5.clar:3436:3444](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3436-L3444) |

#### Bitcoin SPV / Lockup Helpers

These read-onlys are exposed at the contract surface but are primarily used internally by `verify-l1-lockups` and `validate-l1-lockup`. They are listed for completeness rather than as a public API. `validate-l1-lockup` is the fold body over each lockup output; its accumulator carries the `staker`, the bond's `minimum-unlock-height`, the `staker-unlock-bytes`, and the `early-unlock-bytes`, and it reconstructs the expected p2wsh script for that output via `construct-lockup-output-script` from the output's own `unlock-burn-height`. For each output it asserts, in order: the committed `unlock-burn-height` is at or above the bond minimum (`ERR_INVALID_UNLOCK_HEIGHT u52`), that same height is below `BITCOIN_LOCKTIME_THRESHOLD` (`u500000000` — Bitcoin treats locktimes at or above that value as Unix timestamps rather than block heights) (`ERR_INVALID_UNLOCK_HEIGHT u52`), the decoded output script equals the reconstructed timelock script (`ERR_INVALID_LOCKUP_SCRIPT u42`), the decoded output amount equals the caller-supplied `amount` (`ERR_INVALID_LOCKUP_AMOUNT u45`), the outpoint does not repeat across the registration's lockup list (`ERR_DUPLICATE_LOCKUP_OUTPOINT u46`, max 10 outpoints), the block header is valid (`ERR_INVALID_BTC_HEADER u40`), and the merkle proof holds (`ERR_INVALID_MERKLE_PROOF u41`).

`construct-lockup-script` builds the L1 lockup witness script from the caller-supplied `staker-unlock-bytes` (runs unconditionally after `OP_ENDIF`) and `early-unlock-bytes` (runs in the `OP_ELSE` branch, result consumed by the shared `OP_VERIFY`); 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](/pox-5/development/paired-btc.md) for the full template. `uint-to-buff-le` produces a little-endian encoding for values up to 65535 and panics above that. `serialize-c-script-num` / `push-c-script-num` encode an output's `unlock-burn-height` as a minimally-encoded Bitcoin script number for the CLTV branch; they are fallible and reject a height at or above 2³⁹ (`u549755813888`) with `ERR_INVALID_UNLOCK_HEIGHT u52`, so `construct-lockup-script` and `construct-lockup-output-script` propagate that error rather than truncating an out-of-range height. `validate-l1-lockup` enforces a second, much stricter gate on the same field: a committed `unlock-burn-height` must be below `BITCOIN_LOCKTIME_THRESHOLD` (`u500000000`), since Bitcoin treats locktimes at or above that value as Unix timestamps rather than block heights; a height at or above the threshold also reverts with `ERR_INVALID_UNLOCK_HEIGHT u52`, well before it could approach the 2³⁹ script-number cap.

| Function                         |                                                                                                                                                     Lines |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `parse-block-header`             | [pox-5.clar:3569:3591](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3569-L3591) |
| `read-uint32`                    | [pox-5.clar:3596:3615](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3596-L3615) |
| `read-hashslice`                 | [pox-5.clar:3620:3643](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3620-L3643) |
| `reverse-buff32`                 | [pox-5.clar:3645:3653](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3645-L3653) |
| `get-bc-h-hash`                  | [pox-5.clar:3658:3660](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3658-L3660) |
| `verify-block-header`            | [pox-5.clar:3664:3672](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3664-L3672) |
| `get-reversed-txid`              | [pox-5.clar:3676:3678](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3676-L3678) |
| `construct-lockup-script`        | [pox-5.clar:3711:3731](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3711-L3731) |
| `construct-lockup-output-script` | [pox-5.clar:3734:3745](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3734-L3745) |
| `uint-to-buff-le`                | [pox-5.clar:3749:3766](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3749-L3766) |
| `push-script-bytes`              | [pox-5.clar:3773:3786](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3773-L3786) |
| `serialize-c-script-num`         | [pox-5.clar:3788:3832](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3788-L3832) |
| `push-c-script-num`              | [pox-5.clar:3834:3845](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3834-L3845) |

### Private Functions

| Function                              |                                                                                                                                                     Lines |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------: |
| `validate-no-reentrancy`              |     [pox-5.clar:400:402](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L400-L402) |
| `signer-manager-validate-stake`       |     [pox-5.clar:408:427](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L408-L427) |
| `add-staker-to-bond`                  |     [pox-5.clar:600:634](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L600-L634) |
| `unstake-sats-from-bond-cycles`       | [pox-5.clar:1344:1362](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1344-L1362) |
| `unstake-sats-from-bond-cycle`        | [pox-5.clar:1368:1421](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1368-L1421) |
| `remove-staker-from-cycles`           | [pox-5.clar:1473:1499](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1473-L1499) |
| `remove-staker-from-signer-for-cycle` | [pox-5.clar:1504:1618](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1504-L1618) |
| `add-staker-to-signer-cycles`         | [pox-5.clar:1620:1650](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1620-L1650) |
| `add-staker-to-signer-for-cycle`      | [pox-5.clar:1663:1784](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1663-L1784) |
| `add-staker-to-bond-cycles`           | [pox-5.clar:1786:1804](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1786-L1804) |
| `add-staker-to-bond-for-cycle`        | [pox-5.clar:1806:1865](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1806-L1865) |
| `remove-staker-from-bond-cycles`      | [pox-5.clar:1867:1885](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1867-L1885) |
| `remove-staker-from-bond-for-cycle`   | [pox-5.clar:1887:1936](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1887-L1936) |
| `roll-sbtc`                           | [pox-5.clar:1943:1979](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1943-L1979) |
| `verify-l1-lockups`                   | [pox-5.clar:1984:2019](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L1984-L2019) |
| `validate-l1-lockup`                  | [pox-5.clar:2031:2113](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2031-L2113) |
| `get-l1-lockup-summary`               | [pox-5.clar:2115:2130](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2115-L2130) |
| `calculate-bond-rewards`              | [pox-5.clar:2242:2337](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2242-L2337) |
| `update-claimable-rewards`            | [pox-5.clar:2476:2493](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2476-L2493) |
| `update-claimable-bond-rewards`       | [pox-5.clar:2495:2523](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2495-L2523) |
| `settle-rewards`                      | [pox-5.clar:2530:2574](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2530-L2574) |
| `settle-staker-rewards`               | [pox-5.clar:2581:2614](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2581-L2614) |
| `assert-active-bond-included`         | [pox-5.clar:2639:2676](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2639-L2676) |
| `match-uint-in-list`                  | [pox-5.clar:2679:2690](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2679-L2690) |
| `transfer-from-reserve`               | [pox-5.clar:2696:2713](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2696-L2713) |
| `transfer-stranded-rewards`           | [pox-5.clar:2724:2739](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2724-L2739) |
| `verify-not-prepare-phase`            | [pox-5.clar:2956:2960](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L2956-L2960) |
| `verify-bond-rollover-window`         | [pox-5.clar:3009:3025](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3009-L3025) |
| `add-signer-to-set-for-cycle`         | [pox-5.clar:3446:3486](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3446-L3486) |
| `remove-staker-from-set-for-cycle`    | [pox-5.clar:3488:3555](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3488-L3555) |
| `reverse-buff16`                      | [pox-5.clar:3655:3657](https://github.com/stacks-network/stacks-core/blob/pox-wf-integration/stackslib/src/chainstate/stacks/boot/pox-5.clar#L3655-L3657) |

> `signer-manager-validate-stake` is the only call-path into the trait's `validate-stake!` callback; it raises the `signer-manager-call-active` guard for the duration of the call so any reentrant entry from inside the callback fails with `ERR_REENTRANT_CALL u49`. `roll-sbtc` net-transfers custodied sBTC and so handles both initial registrations and rollovers between bonds (or between bond and STX-only positions). `settle-staker-rewards` is the per-staker counterpart of `settle-rewards`. Both run at the top level of `register-for-bond` and `update-bond-registration` (where the affected signer is unambiguous for the call). In `announce-l1-early-exit` and `unstake-sbtc` they run **per affected cycle** inside `unstake-sats-from-bond-cycle`, which derives that cycle's signer from `staker-signer-cycle-memberships` first — this is required because `update-bond-registration` can leave a staker with a different signer in the current cycle than in future cycles. For STX-only flows (`stake`, `stake-update`, `unstake`) they run inside the per-cycle helpers `add-staker-to-signer-for-cycle` / `remove-staker-from-signer-for-cycle`. `unstake-sats-from-bond-cycles` is the cycle-folding entry point that drives `unstake-sats-from-bond-cycle`; it is used in place of `remove-staker-from-bond-cycles` for the bond-side withdrawal flows because it derives the signer per cycle rather than taking a single signer for the full range. The call order is signer-then-staker so the staker's RPT snapshot is taken against the freshly-settled signer-level RPT. `verify-not-prepare-phase` is the prepare-phase guard called by every entrypoint that mutates next-cycle share data: `register-for-bond`, `update-bond-registration`, `stake`, `stake-update`, `announce-l1-early-exit`, and `unstake-sbtc` (all raise `ERR_STAKE_IN_PREPARE_PHASE u47`). `unstake` enforces the same window through its own separate check (`ERR_UNSTAKE_IN_PREPARE_PHASE u28`). `verify-bond-rollover-window` asserts a prior bond is inside its L1 unlock window before allowing a rollover (`ERR_ROLLOVER_TOO_EARLY u48`). `transfer-from-reserve` is invoked only by node-level consensus (annotated `#[allow(unused_private_fn)]`); no in-contract call-path reaches it. `transfer-stranded-rewards` is its sibling: also private, also reachable only by node-level consensus through a hard fork (`#[allow(unused_private_fn)]`, no in-contract caller). Unlike `transfer-from-reserve`, it does not update internal accounting or bound the amount against the reserve — it is an unbounded catch-all for moving sBTC out of the contract (for example, to recover rewards stranded by a `pause-rewards` call). It is not an integrator API.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stacks.co/pox-5/contract.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.