Skip to content

docs(protocol): document asset two-word encoding#2867

Draft
BrianSeong99 wants to merge 1 commit intomainfrom
brian/protocol-asset-encoding-docs-270
Draft

docs(protocol): document asset two-word encoding#2867
BrianSeong99 wants to merge 1 commit intomainfrom
brian/protocol-asset-encoding-docs-270

Conversation

@BrianSeong99
Copy link
Copy Markdown

Summary

Adds a canonical Asset encoding section to docs/src/asset.md, covering the two-word ASSET_KEY / ASSET_VALUE layout for fungible and non-fungible assets, how asset_id_* is derived, and how the asset callback flag is packed into the reserved low byte of faucet_id_suffix.

Also fixes the miden::protocol::asset::create_non_fungible_asset stdlib row so its inputs include the enable_callbacks flag, matching the MASM procedure signature.

Context

Addresses the live-docs side of 0xMiden/docs#270. The docs site ingests current /core-concepts/protocol/* pages from 0xMiden/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..HEAD
  • Docker docs build from node: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
  • The Docker build completed with [SUCCESS]. It still reports existing generated-doc broken link/anchor warnings unrelated to this patch.

@BrianSeong99 BrianSeong99 added the no changelog This PR does not require an entry in the `CHANGELOG.md` file label May 5, 2026
Comment thread docs/src/asset.md

### 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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread docs/src/asset.md
ASSET_VALUE = DATA_HASH # non-fungible
```

The `asset_id_*` limbs distinguish different assets issued by the same faucet:
Copy link
Copy Markdown
Contributor

@PhilippGackstatter PhilippGackstatter May 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread docs/src/asset.md
Comment on lines +75 to +76
- 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.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.

Comment thread docs/src/asset.md
Comment on lines +78 to +83
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).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Comment thread docs/src/asset.md

The remaining 7 bits are reserved for future asset-level metadata.

#### Worked example
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Worked example
#### Example

Not sure what "worked" means.

Comment thread docs/src/asset.md

#### 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:
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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).

Comment thread docs/src/asset.md
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`.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

no changelog This PR does not require an entry in the `CHANGELOG.md` file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants