An ERC-4626 share is a claim represented in a vault's share units, not a promise that one share equals one underlying token. A useful deposit screen must distinguish a conversion estimate, an action preview, a transaction limit, and the amount actually received. Combining those numbers under one label can make a technically functioning integration misleading.
TL;DR: Read the asset and share units separately, preview the exact action the user intends, check the relevant limits, and preserve the quote's state context. Use enforceable transaction bounds when available rather than treating an earlier preview as a guarantee. The worked examples below describe hypothetical vaults and interface decisions; they are not return forecasts or endorsements.
The quotation desk receives four different requests
A user arrives with one hundred underlying tokens and wants to deposit all of them. Another user wants exactly one hundred vault shares and asks how many underlying tokens are required. A third wants to withdraw exactly one hundred underlying tokens. A fourth wants to redeem all one hundred shares already owned. These are four distinct requests even though each contains the number one hundred.
ERC-4626 defines corresponding deposit, mint, withdraw, and redeem operations. Its conversion methods describe an idealized exchange without fees, while action previews reflect the relevant operation's conditions and fees. Limits are exposed separately. Those distinctions are the small amount of interface vocabulary needed before the product team can design a clear quotation. ERC-4626 specification
The fictional interface in this article, called Ledgerglass, begins by asking which quantity the user wants to fix: assets paid, shares received, assets received, or shares spent. It then labels the other quantity as an estimate or maximum requirement, as appropriate. This prevents a deposit form from silently switching into an exact-share mint when the user edits the wrong field.
The action choice also determines the unit of any protection. A user fixing the asset input cares about a minimum share output. A user fixing a share output cares about a maximum asset input. On exit, a fixed asset withdrawal has a maximum share cost, while a fixed share redemption has a minimum asset output. The screen should make that direction legible in ordinary language.
A generic exchange-rate label can still be useful as context, but it is not the user's complete transaction. A rate omits the amount, integer rounding, fees, limits, and state changes that determine an actual result. Ledgerglass therefore treats the rate as supporting information rather than the main confirmation promise.
Quote sheet A: the units are part of the amount
Assume the underlying token uses six decimal places and the vault share token uses eighteen. An underlying raw balance of 1,000,000 represents one displayed asset token. A share raw balance of 1,000,000 represents only one trillionth of a displayed share. The same integer has radically different meaning under the two scales.
ERC-20's decimals metadata describes the conversion between raw amounts and user-facing representation. It is optional in the base token standard, so integrations must establish the units they rely on rather than assuming every asset follows the same convention. ERC-20 specification
Ledgerglass keeps raw integer amounts through calculation and transaction construction, then formats them for display. It records the chain, asset contract, vault contract, and decimals associated with each amount. A symbol such as USD is not sufficient identity because different contracts can use similar labels and different units.
The product's internal amount type distinguishes assets from shares. This is an engineering recommendation for the example, not a requirement imposed by the token standard. It prevents a developer from passing an already formatted share quantity into a function expecting raw asset units merely because both values happen to be represented as numbers.
The interface also separates display precision from transaction precision. Showing four decimal places can make a balance easier to read, but truncating the underlying transaction amount to those four places changes what the user sends. Conversely, rounding a displayed maximum upward can imply that more can be withdrawn than the contract permits.
A review case uses a share balance of 12.345678 shares. A compact display may show 12.3457, but the redeem-all action should use the verified raw balance, subject to the applicable transaction rules. Typing the rounded display back into a numeric field is a different action and should not be treated as identical to selecting all.
Quote sheet B: rounding has an economic direction
Consider a deliberately coarse hypothetical vault with one hundred indivisible share units backed by one hundred fifty indivisible asset units. Ignore fees, virtual offsets, and other implementation details for this arithmetic exercise. The initial ratio is one and a half asset units per share unit.
A deposit of ten asset units corresponds ideally to six and two-thirds share units. If the operation rounds the share output down to six, the user receives fewer units than the fractional calculation suggests. The difference is economically meaningful because the units are intentionally coarse. Real token decimal scales often make rounding much smaller, but the direction still matters.
An exact mint of seven share units at the same starting ratio requires ten and a half asset units before integer treatment. If the vault requires sufficient whole asset units, the input becomes eleven. A withdrawal of ten asset units similarly requires enough shares to cover the amount, while redeeming seven share units produces the whole-asset amount allowed by the operation's rounding rule.
| Hypothetical request at the starting ratio | Fractional calculation | Illustrative integer result |
|---|---|---|
| Deposit 10 asset units | 6.666… share units | 6 shares received |
| Mint 7 share units | 10.5 asset units | 11 assets required |
| Withdraw 10 asset units | 6.666… share units | 7 shares required |
| Redeem 7 share units | 10.5 asset units | 10 assets received |
This table describes independent requests evaluated at the same starting state. It is not a sequence of transactions. Executing the first transaction would change the vault state, so the remaining rows would need new calculations. That distinction prevents a teaching example from accidentally implying that a rate remains fixed while balances change.
OpenZeppelin's vault documentation illustrates how share precision and exchange rates affect rounding losses, and its implementation provides concrete conversion behavior. Ledgerglass uses the actual deployed vault's preview and implementation evidence rather than assuming that the simplified ratio above reproduces every vault. OpenZeppelin vault guide
The product decision follows from the example: a small input that yields negligible or zero shares should not be presented as an ordinary successful investment. The interface should show the actual quoted output and make any minimum useful amount visible. It should not hide a large relative rounding loss behind a rate rounded to several attractive decimal places.
Quote sheet C: fees need a defined base
Suppose a fictional vault charges a one percent entry fee calculated on the net assets credited to the position. A user pays 101 asset tokens in total: one hundred become the net deposit base and one is the fee. If the interface instead subtracts one percent of the gross input, it would calculate a fee of 1.01 and a net amount of 99.99. The difference comes from the fee definition.
Both gross-based and net-based conventions can be described mathematically, but they are not interchangeable. Ledgerglass's fee panel states the amount paid, the amount used to determine shares, and the fee amount according to the actual implementation. It does not infer the fee formula from a marketing label that says one percent.
A second example uses a two percent fee applied to gross input. On a payment of one hundred tokens, the fee is two and the net amount is ninety-eight. At a hypothetical two assets per share, that net amount corresponds to forty-nine shares before any further rounding. The screen's idealized fifty-share conversion and its forty-nine-share action preview answer different questions.
The difference should not be automatically called market slippage. It may include a documented fee, rounding, or another action-specific condition. A useful quote explains the parts that can be identified and leaves unknown differences clearly labeled. Calling every discrepancy yield or slippage would conceal information the user needs to understand the transaction.
OpenZeppelin's documentation includes fee customization examples and emphasizes keeping previews consistent with the operation. Those examples are implementation guidance, not evidence that every deployed vault uses the same fee schedule. OpenZeppelin ERC-4626 implementation documentation
The exit quote deserves the same treatment. A displayed asset equivalent of a share balance may exceed the amount received after a redemption fee. Ledgerglass therefore avoids labeling the ideal conversion as withdrawable cash. It presents the relevant exit preview and limits when the user actually considers leaving the position.
A preview can be useful while the action is unavailable
Imagine a vault that would exchange a deposit at a favorable rate but has reached its current deposit cap. Its mathematical preview may still describe what the operation would produce under its preview semantics, while the relevant maximum deposit is zero. An interface that reads only the preview could invite the user to approve and submit an unavailable action.
Ledgerglass checks the action limit for the intended receiver or owner, as relevant, and distinguishes it from the user's wallet balance and allowance. These constraints answer different questions. A vault can accept more than the user owns, a user can own enough without approving spending, and an approved amount can still exceed a vault limit.
For a worked screen, assume the user owns five hundred assets, has approved three hundred, and the current vault deposit limit for the recipient is two hundred. The immediately usable amount is constrained by the smallest relevant requirement, but the explanation should identify each one. Increasing allowance to five hundred would not raise the vault's two-hundred limit.
Now suppose the limit changes while the user reviews the transaction. An earlier successful check cannot guarantee later acceptance. The interface should refresh the quote and clearly distinguish an observed limit from a reservation. Unless the contract actually reserves capacity, the product should not imply that opening the screen secured a place in the vault.
On withdrawal, the user's accounting claim and immediate liquidity can also differ. A share balance may represent assets that cannot all be withdrawn through the current synchronous path. Ledgerglass shows the amount currently available through that path and explains any separately supported request flow. It does not erase the remaining claim or pretend that it is immediately liquid.
The quote has a block context and an expiration problem
A quotation is a statement about state observed at a particular point. Between the read and transaction inclusion, other users can act, strategy accounting can update, or fees and limits can change where the implementation permits. A preview is therefore valuable evidence about a proposed transaction, not a promise that the state will remain frozen.
The JSON-RPC interface allows calls to be evaluated with a block parameter. An integration can use that capability to make related reads refer to a coherent state where supported by its provider and workflow. It should also record the context so that an unexpected result can be investigated. Ethereum JSON-RPC documentation
Ledgerglass stores the quote's chain, vault, action, input amount, receiver or owner context, block identifier, and displayed output. If the user switches networks or accounts, the old quote is invalidated. If the input changes, the old output is visibly replaced rather than remaining on screen while a new request is pending.
A stale-response race is easy to reproduce. The user types one hundred, then one thousand. The request for one thousand returns first, followed by the older request for one hundred. Without request identity or cancellation handling, the interface may display a plausible output for the wrong input. This is a product correctness problem independent of whether the contract behaves correctly.
The confirmation screen should show the exact quantity being fixed and the bound being enforced. If the transaction path cannot enforce the displayed protection, the interface must not imply otherwise. A countdown timer alone does not create an on-chain guarantee; it only expresses how long the product chooses to consider its observation fresh.
A bound belongs in the transaction path
For a deposit quoted at one hundred shares, suppose the user accepts no fewer than ninety-nine shares. An enforceable minimum-output condition can cause the transaction to fail if execution would deliver less. The product must verify that the selected contract path actually checks that condition, whether through a supported extension, router, or other appropriate integration.
ERC-5143 proposes explicit slippage-bound variants of vault actions. Its proposal is useful for understanding the desired interface, but its status and deployment support must be checked; an ERC-4626 vault does not automatically implement it. ERC-5143 proposal
The quote review distinguishes an expected output from a minimum accepted output. They should not appear as two unlabeled numbers. The expected output helps users understand the current estimate, while the bound states the worst result the chosen transaction path is permitted to accept under that condition.
For an exact-share mint, the direction reverses: the user needs a maximum asset input. Reusing a deposit's minimum-output field for every action is a conceptual bug. The same care applies to withdrawal and redemption, whose fixed and variable quantities differ. A shared interface component should preserve those distinctions rather than flatten them into a generic swap form.
Bounds also need sensible units and rounding. If a displayed minimum of ninety-nine shares is converted using asset decimals, the transaction may enforce a meaningless value. Ledgerglass's test cases therefore include different decimal scales, very small amounts, and values near integer boundaries. These cases test the meaning of protection, not merely whether a button produces a transaction.
Asynchronous vaults need a request timeline
Some vault flows separate requesting an action from claiming its result. ERC-7540 extends the tokenized-vault interface for asynchronous deposit and redemption requests, with pending and claimable states and modified preview behavior for asynchronous flows. An interface designed only around immediate exchange must recognize that different lifecycle. ERC-7540 specification
Ledgerglass uses a timeline for a hypothetical asynchronous redemption: shares committed to a request, request pending, assets claimable, claim submitted, and assets received. The exact supported transitions come from the implementation. The product does not invent cancellation rights or completion deadlines simply because users would find them convenient.
A pending request should not be counted simultaneously as freely redeemable shares and already received assets. The portfolio view needs to distinguish ownership, committed amounts, claimable amounts, and completed transfers. Otherwise, the same economic position can appear twice during the transition.
The user also needs to know which quantity is fixed when the request is made and which remains dependent on later accounting. A projected amount can be useful if clearly labeled, but it should not be presented as a settled claim unless the contract's state establishes that fact. The request model determines what the interface can honestly promise.
A failed preview call in an asynchronous flow should not automatically be rendered as a broken vault. The integration must understand the supported interface and the standard's altered semantics. Conversely, swallowing every failure and displaying zero would hide genuine errors. The product should distinguish an unsupported preview from a valid zero quote and from an unavailable service response.
A quotation test matrix exercises meaning, not only arithmetic
The product review includes a fictional vault whose current preview produces zero shares for a very small deposit. The expected interface behavior is to show that result and prevent an accidental submission under the product's policy, not to substitute a rounded display value of 0.0001. That substitution would turn a formatting choice into a false statement about the contract's output.
A second fixture returns a positive preview while the current deposit limit is zero. The screen should explain that deposits are unavailable rather than offering approval as a supposed remedy. A third fixture has sufficient vault capacity but insufficient wallet balance. These cases can share a disabled action button while requiring different explanations and different next steps.
A fourth fixture changes the recipient without changing the sender. If the vault applies recipient-specific limits, the previous limit cannot be reused merely because the wallet address paying for the transaction stayed the same. The quote identity must include the parameters that determine the action, not only the amount and chain.
A fifth fixture simulates a provider failure while refreshing a quote. The last observed value may remain useful as historical information, but it should not retain the appearance of a fresh executable quote. A stale-data label and a clear pending or unavailable state preserve the distinction. Replacing every failed read with zero can falsely suggest that the user lost their position.
Finally, the review submits a transaction that succeeds with an output different from the earlier estimate but within the enforced bound. The history should record the actual result and explain the comparison. It should not classify every quote difference as a failed transaction, nor should it erase the original estimate when the user needs to understand what changed.
A share ratio is not an annual return
Suppose one share represents 1.20 underlying assets today. That number alone does not establish a twenty percent annual yield. The initial ratio may have been different, the share units may use a different scale, and the ratio may reflect a period longer or shorter than a year. Fees, losses, and external asset movements can also affect the interpretation.
A return chart needs comparable observations over a defined interval and an explanation of what the ratio includes. If Ledgerglass cannot establish those inputs, it should display the current conversion without manufacturing an annualized performance claim. A useful account balance does not require an unsupported yield number beside it.
Reconcile the completed action before reporting performance
After execution, Ledgerglass records the actual assets and shares associated with the action and reconciles them with the transaction result and relevant events. The earlier quote remains useful for explaining any difference, but it is not substituted for the completed amount in the user's history.
A portfolio return calculation then needs a cash-flow history. Suppose a user deposits one hundred assets, later adds another fifty, and ends with a position valued at one hundred sixty. The difference between the ending value and the original one hundred is not a sixty percent investment return because fifty of the increase came from a new contribution.
Share transfers create another distinction. Receiving shares from another wallet increases the recipient's position without being yield generated by the vault during that recipient's holding period. A performance view must decide how to value the incoming position and disclose its method. The standard's balance interface does not supply a complete personal investment history.
The underlying asset's market price can move independently of the share-to-asset ratio. A position can gain underlying tokens while losing value in the user's reporting currency. Ledgerglass therefore separates the quantity of underlying assets represented from the currency valuation, including the price source and time used for the latter.
The final quote review asks a narrow but demanding question: can a user tell what they are paying, what they expect to receive, what the transaction will enforce, and what remains uncertain? A correct answer requires more than reading one conversion function. It requires preserving the meaning of units, actions, state, and settlement throughout the interface.