ERC-4626 Vault Shares vs Underlying Assets
Distinguish vault shares from underlying asset quantities, compare preview and conversion methods, and avoid treating a share token as a fixed asset amount.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A tokenised vault represents participation through shares. The amount of underlying assets corresponding to those shares can change. Store both units explicitly instead of treating shares as interchangeable with the deposited asset.
Identify the two quantities
Share balance belongs to the vault token; asset quantity belongs to the underlying asset. Conversion and preview methods answer related but different questions under ERC-4626, including operation-specific rounding or fees. A current conversion observation should not automatically be applied to historical share balances.
Worked example: a changing conversion
A wallet owns ten shares. At one block the applicable conversion gives twelve underlying units; later it gives thirteen. The share count is unchanged, while the exposure estimate changes. A transfer-only share history cannot fully describe that underlying-value change without the conversion context.
Test operational boundaries
Record vault address, underlying asset, block reference and method used. Test small quantities, rounding, deposit or withdrawal limits and implementation-specific fees. A preview is not a guarantee that a later transaction executes under unchanged conditions. Keep estimated redeemable assets separate from a confirmed withdrawal amount and its execution evidence.
A practical acceptance test
Keep ten vault shares while changing the conversion from twelve to thirteen underlying units. Verify unchanged share quantity and changed exposure separately. Compare a preview with later execution under changed state, and retain both observations. A failed withdrawal must not be recorded as received underlying assets simply because an earlier preview returned a positive amount.
Questions about the topic
Frequently asked questions
Does one share always equal one underlying unit?
No. The conversion depends on vault accounting.
Is a preview a confirmed withdrawal?
No. It is a method result under the observed state and interface rules.
Standards & technical documentation