> 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/etherfi-withdrawal-queue.md).

# ether.fi Withdrawal Queue

An assisted adapter that reports the in-flight ETH owed to an account in ether.fi's withdrawal queue, fed onchain by the owner Safe.

An **assisted** adapter that reports the **in-flight ETH owed to an account in ether.fi's withdrawal queue**. Requesting a withdrawal burns eETH/weETH and mints a `WithdrawRequestNFT`, which is not `ERC721Enumerable` and has no owner→tokenIds view, so the queued ETH is invisible to NAV. The owner submits the request `tokenId` (`submit(uint256)`, keyed on `msg.sender`); the adapter values it from live onchain reads, re-verifying ownership on every read.

* **Type:** [Assisted adapter](https://docs.kpk.io/funds/infrastructure/architecture/onchain-accounting/assisted-balance-adapters.md), permissionless, `msg.sender`-keyed (`AssistedCoordCache`)
* **protocolSubId:** `keccak256("etherfi-withdrawal")`
* **Source:** `EtherFiWithdrawalQueueAssistedBalanceAdapter.sol`
* **Assistant:** `EtherFiWithdrawalQueueAssistant.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

One `Supplied` leg per owned cached request, all sharing one static positionId:

| Leg                   | PositionKind | isDebt  | isLocked | Description                                           |
| --------------------- | ------------ | ------- | -------- | ----------------------------------------------------- |
| Per finalised request | `Supplied`   | `false` | `false`  | Native ETH from a finalised tokenId, withdrawable now |
| Per pending request   | `Supplied`   | `false` | `true`   | Native ETH from a pending tokenId, still finalising   |

Legs are denominated in native ETH (`balanceAsset`), with `isLocked = !finalized` and the tokenId in `positionInstanceId`. A zero-amount leg is omitted; the position is dropped if native ETH is not registered in NAVCalculator, if there are no owned open requests, or if `assetFilter` excludes it. `getAdapterBalances` still reports the summed total.

## 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 still owned (not yet claimed)                              |
| `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)                                                                                                  |

`_removable` is "no longer owned by the caller": `claimWithdraw` **burns** the NFT, so a claimed id reads as unowned and becomes removable. See the [family write semantics](https://docs.kpk.io/funds/infrastructure/architecture/onchain-accounting/assisted-balance-adapters.md#write-semantics-fail-loud).

### The assistant (`EtherFiWithdrawalQueueAssistant`)

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

| Entrypoint                        | Does                                                                                                                                  | Adapter call        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `requestWithdraw(uint256 amount)` | Approves the LiquidityPool for the Safe's eETH and calls it with `recipient = the Safe`, minting the `WithdrawRequestNFT` to the Safe | `submit(requestId)` |
| `claimWithdraw(uint256 tokenId)`  | **Claims first** (burns the NFT, ETH to the Safe), **then** untracks best-effort                                                      | `remove(tokenId)`   |

Both are `onlyDelegateCall` (a direct call reverts `NotDelegateCall`). Under delegatecall ether.fi sees `msg.sender = Safe`, which its claim path requires (`ownerOf == msg.sender`). Removal on claim never blocks the claim: the assistant swallows `CoordinateNotCached` (id acquired outside the assistant or already cleared) and `CoordinateStillLive`, and re-throws anything else.

<figure><picture><source srcset="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FmZ6TnZ6TTBQGBkhv5VOy%2Fwithdraw-request-flow_D.png?alt=media&amp;token=1139eb2b-cf88-46f1-b3d8-345070cd3bd9" media="(prefers-color-scheme: dark)"><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FHn6kNDZbu61n1FKhGwna%2Fwithdraw-request-flow.png?alt=media&amp;token=5747206e-1c82-4ff8-9c6c-2d8f238185c6" alt="Flow to request an ether.fi withdrawal: the Manager Safe drives the Portfolio Safe to delegatecall the assistant, which burns eETH via the LiquidityPool and submits the resulting requestId to the adapter."></picture><figcaption><p><strong>Requesting a withdrawal.</strong> The Safe delegatecalls the assistant, which burns eETH via the LiquidityPool (minting the <code>WithdrawRequestNFT</code>) and <code>submit</code>s the returned requestId to the adapter: all 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%2FMeH7C2C2mELHOh4Sr7Nq%2Fclaim-withdraw-flow_D.png?alt=media&amp;token=bf71cd3c-0364-47d9-950f-ed253fa4634a" media="(prefers-color-scheme: dark)"><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2F2Lfxe7sHrpSvXs43eYyL%2Fclaim-withdraw-flow.png?alt=media&amp;token=5c500890-e419-41e6-aa9f-548c600668f7" alt="Flow to claim an ether.fi withdrawal: the Safe delegatecalls the assistant, which claims (burning the NFT, ETH to the Safe) then best-effort removes the requestId from the adapter cache."></picture><figcaption><p><strong>Claiming.</strong> The assistant claims first, burning the NFT and sending ETH to the Safe, then best-effort <code>remove</code>s the requestId from the adapter's cache.</p></figcaption></figure>

## Balance calculation

<figure><picture><source srcset="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2FT0yAeIE3xl9LhpD6UVMU%2Fget-adapter-positions-liquidity_D.png?alt=media&amp;token=36e02f2e-beb1-4b4b-84e9-833beec12a77" media="(prefers-color-scheme: dark)"><img src="https://1699303810-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUsQM4bzcmOPSgkWddkeN%2Fuploads%2F0T9BO9ijzDfxbeUhHqbf%2Fget-adapter-positions-liquidity.png?alt=media&amp;token=b7d6e0ac-5f0d-4f3e-b710-214c0b0fe44a" alt="Flowchart of the ether.fi Withdrawal Queue balance adapter: cached tokenIds are re-verified and valued into a PositionBalance entry."></picture><figcaption><p>ether.fi Withdrawal Queue adapter: how the underlying balances reported to the NAV Calculator are derived.</p></figcaption></figure>

For each cached `tokenId`, the adapter re-verifies that `account` still owns the request and emits one leg:

```
for each cached tokenId owned by account:
    if nft.isFinalized(tokenId):
        amount = nft.getClaimableAmount(tokenId); finalized = true
    else:
        amount = min(amountOfEEth, LiquidityPool.amountForShare(shareOfEEth)) - feeGwei; finalized = false   // current estimate
    emit leg { amount, isLocked = !finalized, positionInstanceId = bytes32(tokenId) }
```

Pending requests convert the request's locked shares to ETH at the current rate. Each id is valued behind the base's per-coordinate self-`staticcall` (every external read try/catches to 0), so a stale, invalid, or reverting id contributes nothing and never drops the rest.

## Identity

* **positionId:** `abi.encode(withdrawRequestNFT)` (static; the ether.fi `WithdrawRequestNFT` address)
* **positionKind:** `Supplied`
* **positionInstanceId:** `bytes32(tokenId)` (ephemeral, burned on claim)
* **Labels:** `positionLabels(positionId)` returns `["Withdrawal Queue", "eETH"]` (verbose read path only; full breadcrumb `["ether.fi", "Withdrawal Queue", "eETH"]`)

The reconciliation key is `keccak256(abi.encode(chainId, protocolSubId, positionId, balanceAsset.asset, positionKind))`. It **excludes** `isLocked` and `positionInstanceId`, so all of an account's requests, claimable and pending, reconcile into **one coordinate** and sum to the ETH owed. Read `isLocked` per leg for the split.

## Constructor

```solidity
constructor(
    address withdrawRequestNft_,
    address liquidityPool_,
    address underlyingToken_,
    address navCalculator_
)
```

| Parameter             | Description                                                                                               |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| `withdrawRequestNft_` | ether.fi `WithdrawRequestNFT`, source of ownership + per-request data. Must be a contract                 |
| `liquidityPool_`      | ether.fi `LiquidityPool`, `amountForShare` converts a request's shares to current ETH. Must be a contract |
| `underlyingToken_`    | Payout asset, native ETH (ERC-7528 sentinel). Must be non-zero                                            |
| `navCalculator_`      | NAVCalculator address, used for asset-registry metadata. Must be a contract                               |

There is no `admin_` / `assistant_` argument. The `EtherFiWithdrawalQueueAssistant` is deployed separately and pinned to this adapter (plus the LiquidityPool, WithdrawRequestNFT, and eETH token) at its own construction.

## 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/etherfi-withdrawal-queue.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.
