ERC-7540 Vault
Tahoe uses an ERC-7540 vault to exchange USDC subscriptions for fund shares and to settle redemptions back into USDC. Both directions happen in stages: a request commits the assets or shares, the fund manager fulfills it at an accepted price, and the investor claims the result.
This lets the fund complete pricing and obtain redemption liquidity before settlement. A manager accepting an investment, an investor sending money, and an investor receiving shares are distinct events.
What ERC-7540 Adds
ERC-7540 extends the ERC-4626 tokenized-vault interface with asynchronous requests. ERC-4626 normally exchanges assets and shares in a single transaction. ERC-7540 supports a waiting period between committing funds and collecting the result.
| Stage | Deposit | Redemption |
|---|---|---|
| Pending | USDC has entered the vault through requestDeposit. | Shares have been committed through requestRedeem. |
| Claimable | Fulfillment has established the assets/shares pair available to claim. | Fulfillment has established the shares/assets pair available to claim. |
| Claimed | deposit or mint delivers the shares. | redeem or withdraw delivers the assets. |
The familiar deposit, mint, withdraw, and redeem names are claim functions on an asynchronous side. Calling deposit again does not fund a new subscription. The standard leaves the fulfillment policy to the implementation and does not define a request-cancellation mechanism.
In Tahoe, the two manager-controlled transitions are exposed by fulfillDeposit and fulfillRedeem. They prepare a claim; the investor completes delivery in a separate transaction.
The Vault And The Two Wallets
| Component | Role in Tahoe |
|---|---|
| Investor wallet | Controls the investor's requests, receives claimed shares, requests redemptions, and receives claimed USDC. |
| Self-Custody Wallet | The fund's wallet. Receives subscription funding before the vault deposit and signs fund-controlled approval, request, and fulfillment calls. |
| Treasury Wallet | The deployed vault contract. Holds USDC, tracks pending and claimable balances, and implements the fund's share token. |
The contract distinguishes the owner supplying assets or shares, the request controller entitled to claim, and the receiver collecting the result. In Tahoe's deposit flow, the owner is the fund's Self-Custody Wallet and the request controller is the investor wallet. The investor remains entitled to the claim even though the USDC enters the vault from the fund wallet.
The separate fulfillmentController is the fund wallet address fixed at deployment. Only that address can fulfill requests, draw strategy assets, return strategy assets, or report strategy value. It is not the investor's request controller, and it has no setter in this contract. These rules are implemented in Tahoe's Vault7540ERC20.
A Subscription From Funding To Shares
- Receive funding. The investment's funding must reach the Self-Custody Wallet and be reconciled to that investment. For the USDC wallet-funding path, the investor transfers USDC to this wallet. Money received here has not yet entered an ERC-7540 deposit request.
- Approve the vault. The fund wallet approves the exact USDC amount that the vault may pull. The backend sequences approval and any required allowance cleanup before preparing the deposit request.
- Request the deposit. The fund wallet calls
requestDeposit(assets, investorWallet, fundWallet). USDC moves from the fund wallet into the vault, and the investor's pending deposit balance increases. No shares are minted at this step. - Accept the price and fulfill. In Investment Management, Issue Shares opens the price review and signing flow. Tahoe sends the manager's price per share to the backend. Once the request is ready, the fund owner signs
fulfillDeposit(assets, shares, investorWallet). Confirmation makes the amount claimable. - Claim the shares. The investor portal prepares
deposit(assets, investorWallet, investorWallet). The investor signs the claim, and the vault mints shares to that wallet. The original USDC is already in the vault; claiming does not transfer it in again.
For example, a 1,000 USDC subscription fulfilled at 10 USDC per share produces a claim for 100 shares. Before the claim, the investor has a claimable entitlement. After the claim, the investor has 100 additional shares in their wallet. Tahoe's vault uses 18 share decimals; with a six-decimal USDC asset, the contract amounts are 1000000000 assets and 100000000000000000000 shares.
The Issue Shares button therefore starts fulfillment; the actual mint occurs when the investor claims. The sequence is implemented by the allowance coordinator and Tahoe's manager workflow.
A Redemption From Shares To USDC
- Create and sign the request. The investor portal prepares
requestRedeem(shares, investorWallet, investorWallet). The investor signs it with the wallet holding the shares. - Commit the shares. In this implementation, the request burns the shares immediately. A separate accounting counter keeps those shares included in the vault's adjusted
totalSupply()until the redemption is claimed. - Accept the redemption price. The manager submits the price through the redemption fulfillment flow. The response can indicate that the request is waiting for liquidity, waiting for an earlier request, or awaiting the owner's signature.
- Fulfill when liquid. The fund wallet signs
fulfillRedeem(shares, assets, investorWallet). The contract checks available liquidity and reserves the USDC needed for this claim. Fulfillment does not pay the investor yet. - Claim the proceeds. The investor signs
redeem(shares, investorWallet, investorWallet). The vault pays USDC to the investor, reduces the reserved redemption assets, and removes the corresponding shares from the adjusted supply.
For example, 100 shares fulfilled at 11 USDC per share produce a claim for 1,100 USDC. The investor's spendable share balance falls at request time; the USDC arrives at claim time.
The portal also exposes a cancellation action for eligible business requests. The vault has no on-chain cancellation entry point: that action cannot restore shares burned by an already executed requestRedeem. Claim and cancellation handling are visible in the investor store.
Pricing And Request Ordering
The vault receives explicit asset and share amounts at fulfillment. Its Solidity functions do not fetch an appraisal or decide whether a manager-entered price is correct. Tahoe's backend supplies the priced pair, checks fulfillment readiness, and prepares the exact call for the fund wallet to sign.
The inherited admin extensions use requestId = 0 and aggregate balances by controller. This ID is not a Tahoe investment number or redemption number. Multiple unclaimed fulfillments at different prices would blend into a single claimable asset/share ratio.
Tahoe's fulfillment coordinator locks processing by vault, controller, and direction. It waits while that controller has a claimable balance in the same direction, verifies pending amounts at a finalized block, and checks redemption liquidity before creating the next operation. Consequently, an earlier unclaimed amount can hold up a later fulfillment.
Claims operate on the controller's reconciled claimable balance. The claim builder does not assume that an aggregate balance always belongs to a single business row. It attaches the investment or redemption identity only when the assigned amount matches the reconciled claimable amount.
All four ERC-4626 preview functions revert for this fully asynchronous vault. A current conversion estimate does not guarantee the eventual fulfillment price. Once fulfilled, the claimable asset/share pair determines the claim, including proportional rounding for partial claims. This behavior comes from the inherited admin deposit and admin redemption extensions.
Cash, Strategy Assets, And Share Supply
The vault separates USDC it physically holds from the reported value of assets deployed outside it.
| Contract value | Meaning |
|---|---|
USDC balanceOf(vault) | All USDC physically at the vault address, including reserved amounts. |
totalPendingDepositAssets() | Deposit reserve. With Tahoe's mint-on-claim behavior, this includes deposits already claimable but not yet claimed. |
liquidAssets() | Vault USDC balance minus the deposit reserve. |
strategyAssets() | The last recorded absolute value managed outside the vault. |
totalAssets() | liquidAssets() + strategyAssets(). This is not the amount available to withdraw immediately. |
totalClaimableRedemptionAssets() | USDC reserved for fulfilled redemptions awaiting claims. |
freeLiquidAssets() | USDC balance minus the deposit reserve and claimable redemption reserve, floored at zero. |
Only free liquidity can fund a new redemption liability or a strategy drawdown. For example, a 5,000 USDC vault balance with 1,000 reserved for deposits and 1,500 reserved for redemption claims leaves 2,500 USDC free.
The fund wallet can call drawdownStrategyAssets to receive free USDC from the vault; the contract increases strategyAssets by the same amount. returnStrategyAssets pulls approved USDC back from the fund wallet and reduces that value. reportStrategyAssets replaces the reported strategy value without transferring cash. The report depends on the authorized caller's valuation; the contract does not independently observe off-chain assets.
Share supply also needs care. The inherited ERC7540 base adds outstanding redemption shares back to the underlying ERC-20 supply until claim. Summing wallet balances or reconstructing mint/burn events alone can therefore differ from totalSupply(). Deposit shares are minted on claim, while redemption shares are burned on request.
These distinctions explain why Tahoe's wallet balance, fund valuation, share chart, and claimable amounts can show different numbers.
How Tahoe Submits And Displays Operations
| Tahoe surface | Interaction with the vault |
|---|---|
| Investment Management | Reviews subscription and redemption prices, prepares fund-wallet operations, and presents the owner's signing flow. |
| Investor portal | Requests redemptions and claims deposit shares or redemption USDC. |
| Vault Operations | Refreshes wallet identity, vault state, balances, and lifecycle projections. Its monitoring controls do not initiate strategy transfers. |
| NAV Management | Manages NAV records. Recording a value does not itself execute a vault fulfillment or pay a redemption. |
| Ledger | Displays indexed business and protocol activity as reconciliation updates arrive. |
Manager operations use the registered Turnkey owner and Alchemy's sponsored-call executor. The manager signing adapter checks the fund wallet, target, selector, amounts, controller, and prepared payload. It arms the durable backend operation before submission and registers the provider call ID and transaction hash for reconciliation. This adapter is configured for Sepolia.
The inspected investor portal uses a different transport: its browser wallet adapter checks the connected EVM account and chain, arms the prepared operation, and calls eth_sendTransaction. This path does not use the manager's sponsored-call executor; the investor must connect the wallet matching the prepared request.
A submitted transaction can remain in confirmation while the backend processes chain evidence. Refreshing a page does not execute the next lifecycle step. For a waiting operation, check the specific stage: missing funding, an earlier claim, missing liquidity, an owner signature, an investor claim, or receipt reconciliation.
OpenZeppelin's Implementation And Discussion
Tahoe's Vault7540ERC20 combines OpenZeppelin Community Contracts' ERC7540AdminDeposit and ERC7540AdminRedeem. OpenZeppelin supplies the request/controller accounting and claim mechanics; Tahoe adds the immutable fund-wallet authority, explicit fulfillment entry points, strategy accounting, liquidity reserves, and 18-decimal shares.
The relevant upstream links are:
- ERC7540 contract on GitHub and OpenZeppelin's ERC-7540 guide: the base implementation and available admin, delay, and synchronous combinations.
- Implementation discussion #4761: why fulfillment policy, synchronous/asynchronous combinations, and safe inheritance needed separate design decisions. The vault-class and fulfillment proposal explains the manual, batch, and time-based alternatives.
- Merged Community Contracts implementation #228: the implementation lineage used here. The maintainer announcement places it in Community Contracts and describes migration to the main Contracts library as pending an audit.
- Epoch design discussion #6447 and epoch implementation proposal #230: settlement windows and shared pricing are a separate design. Tahoe's inspected contract uses the admin extensions with per-controller accounting.
The repository also contains Vault7540ERC7943, which extends the same asynchronous vault with regulated-share controls such as allowlisting, freezing, and forced transfers. Those controls belong to that variant; they are not guarantees supplied by ERC-7540 itself.