docs(protocol): document asset two-word encoding#2867
docs(protocol): document asset two-word encoding#2867BrianSeong99 wants to merge 1 commit intomainfrom
Conversation
|
|
||
| ### Encoding | ||
|
|
||
| Every asset in an account vault is stored as a key/value pair of two `Word`s (eight field elements). The same encoding is used by both the kernel and the standard library, and is the canonical layout when assets cross the MASM/Rust boundary. |
There was a problem hiding this comment.
| Every asset in an account vault is stored as a key/value pair of two `Word`s (eight field elements). The same encoding is used by both the kernel and the standard library, and is the canonical layout when assets cross the MASM/Rust boundary. | |
| Every asset in an account vault is stored as a key/value pair of two `Word`s (eight field elements). |
The last sentence doesn't really make sense to me.
| ASSET_VALUE = DATA_HASH # non-fungible | ||
| ``` | ||
|
|
||
| The `asset_id_*` limbs distinguish different assets issued by the same faucet: |
There was a problem hiding this comment.
| The `asset_id_*` limbs distinguish different assets issued by the same faucet: | |
| The `asset_id_*` limbs determine whether two assets issued by the same faucet are fungible (can be merged or splitted) - if the asset ID is the same, they are, if it's different, they are not. |
| - For fungible assets they are always `0`. A faucet only ever issues one asset, so the faucet ID alone identifies it. | ||
| - For non-fungible assets they are `DATA_HASH[0]` and `DATA_HASH[1]` — the first two field elements of the hash of the asset data. |
There was a problem hiding this comment.
| - For fungible assets they are always `0`. A faucet only ever issues one asset, so the faucet ID alone identifies it. | |
| - For non-fungible assets they are `DATA_HASH[0]` and `DATA_HASH[1]` — the first two field elements of the hash of the asset data. | |
| - For fungible assets they are always `0`, because as the name implies, two fungible assets issued by the same faucet are always fungible with each other. | |
| - For non-fungible assets they are `DATA_HASH[0]` and `DATA_HASH[1]` — the first two field elements of the hash of the asset data. This way, the asset IDs of two assets issued by the same faucet have a very low chance of colliding and so the tx kernel never attempts to merge or split those. |
| The third element of the key, `faucet_id_suffix_with_metadata`, packs the faucet's account-ID suffix together with a small metadata byte. The lower 8 bits of every account-ID suffix are reserved zero by construction (`validate_suffix` in `account/account_id/v0/mod.rs`), and `AssetVaultKey::to_word()` (`asset/vault/vault_key.rs`) bit-OR's the metadata byte into those reserved bits. There is no left-shift; the suffix is already aligned. | ||
|
|
||
| Today only the lowest of those 8 bits is used, holding the per-asset callback flag from `AssetCallbackFlag` (`asset/asset_callbacks_flag.rs`): | ||
|
|
||
| - `Disabled = 0` — the kernel skips faucet callbacks for this asset. | ||
| - `Enabled = 1` — the kernel checks for and invokes the faucet's callback procedures (see [Callbacks](#callbacks) below). |
There was a problem hiding this comment.
| The third element of the key, `faucet_id_suffix_with_metadata`, packs the faucet's account-ID suffix together with a small metadata byte. The lower 8 bits of every account-ID suffix are reserved zero by construction (`validate_suffix` in `account/account_id/v0/mod.rs`), and `AssetVaultKey::to_word()` (`asset/vault/vault_key.rs`) bit-OR's the metadata byte into those reserved bits. There is no left-shift; the suffix is already aligned. | |
| Today only the lowest of those 8 bits is used, holding the per-asset callback flag from `AssetCallbackFlag` (`asset/asset_callbacks_flag.rs`): | |
| - `Disabled = 0` — the kernel skips faucet callbacks for this asset. | |
| - `Enabled = 1` — the kernel checks for and invokes the faucet's callback procedures (see [Callbacks](#callbacks) below). | |
| The third element of the key, `faucet_id_suffix_with_metadata`, packs the faucet's account ID suffix together with a metadata byte. The lower 8 bits of every account-ID suffix are reserved zero by construction, leaving room for this asset metadata. | |
| The asset metadata holds the per-asset callback flag: | |
| - `Disabled = 0`: the kernel skips faucet callbacks for this asset. | |
| - `Enabled = 1`: the kernel checks for and invokes the faucet's callback procedures (see [Callbacks](#callbacks) below). |
Too many low-level details, imo, and procedure names and file paths go stale fast, so I wouldn't include them.
|
|
||
| The remaining 7 bits are reserved for future asset-level metadata. | ||
|
|
||
| #### Worked example |
There was a problem hiding this comment.
| #### Worked example | |
| #### Example |
Not sure what "worked" means.
|
|
||
| #### Worked example | ||
|
|
||
| A fungible asset with `amount = 10000`, callbacks enabled, issued by a faucet whose ID has `suffix = 447750849984126720` and `prefix = 12959558562786060576` lays out in vault memory as: |
There was a problem hiding this comment.
| A fungible asset with `amount = 10000`, callbacks enabled, issued by a faucet whose ID has `suffix = 447750849984126720` and `prefix = 12959558562786060576` lays out in vault memory as: | |
| A fungible asset with `amount = 10000`, callbacks enabled, issued by a faucet whose ID has `suffix = 447750849984126720` and `prefix = 12959558562786060576` is laid out as: |
I wouldn't scope to just the asset vault, because assets also appear in other places (e.g. note assets - which we don't call a vault).
| 0, 0, 0 ] ← ASSET_VALUE padding | ||
| ``` | ||
|
|
||
| For a non-fungible asset the last four elements are replaced with `DATA_HASH` and the first two elements of the key are filled from `DATA_HASH[0..2]`. See `FungibleAsset::to_value_word()` and `NonFungibleAsset::to_value_word()` in `asset/fungible.rs` and `asset/nonfungible.rs`. |
There was a problem hiding this comment.
| For a non-fungible asset the last four elements are replaced with `DATA_HASH` and the first two elements of the key are filled from `DATA_HASH[0..2]`. See `FungibleAsset::to_value_word()` and `NonFungibleAsset::to_value_word()` in `asset/fungible.rs` and `asset/nonfungible.rs`. | |
| For a non-fungible asset the last four elements are replaced with `DATA_HASH` and the first two elements of the key are filled from `DATA_HASH[0..2]`. |
In principle the references are nice, but we usually don't include such references. If you'd like to include them, I'd recommend linking to docs.rs (with version set to latest), which would automatically provide the latest published view of the source.
Summary
Adds a canonical Asset encoding section to
docs/src/asset.md, covering the two-wordASSET_KEY/ASSET_VALUElayout for fungible and non-fungible assets, howasset_id_*is derived, and how the asset callback flag is packed into the reserved low byte offaucet_id_suffix.Also fixes the
miden::protocol::asset::create_non_fungible_assetstdlib row so its inputs include theenable_callbacksflag, matching the MASM procedure signature.Context
Addresses the live-docs side of 0xMiden/docs#270. The docs site ingests current
/core-concepts/protocol/*pages from0xMiden/protocol/docs/src, so the source fix belongs here. A companion docs PR covers the v0.14 snapshot and migration-page mirror.Verification
git diff --check origin/main..HEADnode:20-bookworm-slim, with this protocol docs source populated into the docs aggregator worktree:npm ci && NODE_OPTIONS=--max-old-space-size=8192 npm run build[SUCCESS]. It still reports existing generated-doc broken link/anchor warnings unrelated to this patch.