> For the complete documentation index, see [llms.txt](https://docs.kpk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpk.io/funds/infrastructure/architecture/onchain-accounting/assisted-balance-adapters/nexus-mutual-staking.md).

# Nexus Mutual Staking

An assisted adapter that reports an account's staked NXM across Nexus Mutual V2 staking pools, per StakingNFT position the owner has submitted.

An **assisted** adapter that reports an account's **staked NXM across Nexus Mutual V2 staking pools**, per `StakingNFT` position, as NXM-denominated `Staking` and `Rewards` legs. The `StakingNFT` is not owner-enumerable and the StakingViewer has no owner→tokenIds view, so the owner submits the `tokenId` itself (`submit(uint256)`, keyed on `msg.sender`); the adapter values it from live onchain reads, re-verifying ownership on every read.

* **Type:** Assisted adapter, permissionless, `msg.sender`-keyed (`AssistedCoordCache`)
* **protocolSubId:** `keccak256("nexus-mutual-staking-pools")`
* **Source:** `NexusMutualStakingPoolsAssistedBalanceAdapter.sol`
* **Assistant:** `NexusMutualStakingPoolsAssistant.sol`

{% hint style="info" %}
The cache stores only tokenIds, never amounts, so the feeder can at worst omit an id (NAV under-counts). See [Assisted balance adapters](https://docs.kpk.io/funds/infrastructure/architecture/onchain-accounting/assisted-balance-adapters.md) for the family trust model.
{% endhint %}

## Positions returned

Up to two legs **per `StakingNFT`** the account holds (a holder can have several, across several pools):

| Leg     | PositionKind | isDebt  | isLocked | Description                                                                                                  |
| ------- | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| Stake   | `Staking`    | `false` | `false`  | `activeStake + expiredStake`, staked NXM principal (expired tranches no longer earn but remain withdrawable) |
| Rewards | `Rewards`    | `false` | `false`  | Accrued, unclaimed NXM rewards for that position                                                             |

A zero-amount leg is skipped. Legs are denominated in **NXM** and dropped if NXM is not registered in NAVCalculator.

## Feed surface & assistant

A permissionless, `msg.sender`-keyed surface, with no roles and no `account` argument:

| Function                      | Purpose                                                                                                                                                  |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `submit(uint256 tokenId)`     | Track `tokenId` for the caller (idempotent). Reverts `CoordinateNotOwned` if the caller doesn't own it, `CoordinateCacheFull` past `MAX_TOKEN_IDS` (256) |
| `remove(uint256 tokenId)`     | Stop tracking `tokenId`. Reverts `CoordinateNotCached` if untracked, `CoordinateStillLive` if the position is still live                                 |
| `tokenIdsOf(address account)` | View the candidate tokenIds cached for `account` (display/debug; not ownership-filtered)                                                                 |
| `clearAccount()`              | Drop **all** of the caller's cached ids (unconditional)                                                                                                  |

{% hint style="warning" %}
**`_removable` is value-based.** Nexus does not burn the `StakingNFT` on withdraw, so "no longer owned" is not a reliable liveness proxy. An id is removable only once it is no longer owned by the account **or** fully emptied (no active/expired stake and no rewards). A partial or rewards-only withdraw leaves the id tracked, and on an unresolvable `getTokens` read the adapter keeps the id.
{% endhint %}

### The assistant (`NexusMutualStakingPoolsAssistant`)

Delegatecall the assistant instead of calling the pool directly, so the `StakingNFT` is tracked in the same transaction.

| Entrypoint                                                                     | Does                                                                                                                                                      | Adapter call                 |
| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `depositTo(poolAddress, amount, trancheId, requestTokenId)`                    | Approves the Nexus `TokenController` for the Safe's own NXM and stakes it (`destination = the Safe`), minting/topping-up a `StakingNFT` owned by the Safe | `submit(tokenId)`            |
| `withdraw(poolAddress, tokenId, withdrawStake, withdrawRewards, trancheIds[])` | Withdraws stake and/or rewards to the Safe, then tries to `remove(tokenId)`                                                                               | `remove(tokenId)`; see below |

Both are `onlyDelegateCall`. The Safe holds the NXM, is the Nexus member, and owns the minted NFT. On `withdraw`, removal is best-effort and never blocks the withdraw: the assistant swallows `CoordinateStillLive` (partial or rewards-only withdraw, so the id stays tracked) and `CoordinateNotCached`, and re-throws anything else. The id is dropped only once the position is fully emptied.

<figure><picture><source srcset="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FVTWTvsQexRPFBM5bhDoV%2Fdeposit-to-flow_D.png?alt=media&amp;token=18fb765a-838b-40c7-9b6f-3b6c27e2cb9b" media="(prefers-color-scheme: dark)"><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FTCBRwjic5Goan3kq2KVW%2Fdeposit-to-flow.png?alt=media&amp;token=49f6c805-b34a-4e55-b871-d1986b3cbdf9" alt="Flow to stake into Nexus: the Manager Safe drives the Portfolio Safe to delegatecall the assistant, which stakes NXM into the pool and submits the resulting StakingNFT tokenId to the adapter."></picture><figcaption><p><strong>Staking.</strong> The Safe delegatecalls the assistant, which stakes its own NXM into the pool (minting/topping-up a <code>StakingNFT</code>) and <code>submit</code>s the returned tokenId to the adapter: in one transaction.</p></figcaption></figure>

<figure><picture><source srcset="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FM0yd6ed4DJZaGHPd7OQd%2Fwithdraw-staking-flow_D.png?alt=media&amp;token=82b99940-e40b-4d6f-bc3a-8d9542a68605" media="(prefers-color-scheme: dark)"><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FhsyIuQo675ZEbEDn1a9n%2Fwithdraw-staking-flow.png?alt=media&amp;token=96f52f07-3bd4-436a-9d71-6e908996e19f" alt="Flow to withdraw from Nexus: the assistant withdraws stake/rewards to the Safe then best-effort removes the tokenId: kept if still staked (CoordinateStillLive), dropped once fully emptied."></picture><figcaption><p><strong>Withdrawing.</strong> The assistant withdraws stake and/or rewards to the Safe, then best-effort <code>remove</code>s the tokenId: a partial withdraw keeps it tracked (<code>CoordinateStillLive</code>); it is dropped only once the position is fully emptied.</p></figcaption></figure>

## Balance calculation

<figure><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2Fgit-blob-64dce3fec7253c283f2744660af6a23493412218%2Fadapter-nexus-mutual-staking.svg?alt=media" alt="Flowchart of the Nexus Mutual Staking balance adapter: an assistant-submitted StakingNFT tokenId is ownership-verified, then valued via the StakingViewer into Staking and Rewards PositionBalance entries."><figcaption><p>Nexus Mutual Staking adapter: how the underlying balances reported to the NAV Calculator are derived.</p></figcaption></figure>

For each cached `tokenId`, the adapter re-verifies ownership against the StakingNFT and values the position via the StakingViewer:

```
for each cached tokenId:
    if StakingNFT.tokenInfo(tokenId).owner != account: skip      // live ownership re-check
    token = StakingViewer.getTokens([tokenId])
    staking = token.activeStake + token.expiredStake;  rewards = token.rewards
    if staking == 0 and rewards == 0: skip
    pool = StakingViewer.stakingPool(token.poolId)               // positionId
    emit Staking leg (if staking > 0) and Rewards leg (if rewards > 0)
```

A stale or transferred id contributes nothing. Each id is valued behind the base's per-coordinate self-`staticcall` (fail-open), so a revert in one position's reads (`getTokens` is revert-prone) discards only that id.

## Identity

* **positionId:** `abi.encode(address stakingPool)`, where `stakingPool = StakingViewer.stakingPool(poolId)`. Both legs of a position share it; the `tokenId` is not part of it.
* **positionKind:** `Staking` · `Rewards`
* **positionInstanceId:** `bytes32(tokenId)` (ephemeral; both legs of a position carry the same id)
* **Labels:** `positionLabels(positionId)` returns `["Staking Pools", "Pool #<poolId>"]`, with the pool id read live via `INexusMutualStakingPool.getPoolId()` (falling back to the pool's `"0x…"` address if that read reverts). Verbose read path only; full breadcrumb `["Nexus Mutual", "Staking Pools", "Pool #<poolId>"]`.

The reconciliation key is `keccak256(abi.encode(chainId, protocolSubId, positionId, balanceAsset.asset, positionKind))`. An account's NFTs in the same pool share a positionId, and `positionInstanceId` is excluded, so they reconcile into one coordinate per kind; `Staking` and `Rewards` reconcile independently.

## Constructor

```solidity
constructor(
    address stakingNft_,
    address stakingViewer_,
    address underlyingToken_,
    address navCalculator_
)
```

| Parameter          | Description                                                                                                                              |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `stakingNft_`      | Nexus Mutual `StakingNFT` (ERC-721), source of ownership re-verification via `tokenInfo`. Must be a contract                             |
| `stakingViewer_`   | Nexus Mutual `StakingViewer`, per-token active/expired stake + rewards, and `stakingPool(poolId)` for the positionId. Must be a contract |
| `underlyingToken_` | Asset positions are denominated in: NXM. Must be non-zero                                                                                |
| `navCalculator_`   | NAVCalculator address, used for asset-registry metadata. Must be a contract                                                              |

There is no `admin_` / `assistant_` argument. The `NexusMutualStakingPoolsAssistant` is deployed separately and pinned to this adapter (plus the NXM token and Nexus `TokenController`).

## Registration

Register with `addBalanceAdapters([adapter])` and remove with `removeBalanceAdapters([adapter])`. The owner's own transactions then keep the cache current, typically through the assistant.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kpk.io/funds/infrastructure/architecture/onchain-accounting/assisted-balance-adapters/nexus-mutual-staking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
