From 79df3a9ccaffdf46e7d2043bb57615b6fb131408 Mon Sep 17 00:00:00 2001 From: KutluhanETH Date: Mon, 7 Sep 2026 21:54:52 +0000 Subject: [PATCH 1/2] docs(0.14): document native asset vault key/value encoding Add the ASSET_KEY / ASSET_VALUE layout for fungible and non-fungible assets, including the callback flag in faucet_id_suffix, and align the create_non_fungible_asset Inputs row with enable_callbacks. --- .../version-0.14/reference/protocol/asset.md | 43 +++++++++++++++++++ .../reference/protocol/protocol_library.md | 2 +- 2 files changed, 44 insertions(+), 1 deletion(-) diff --git a/versioned_docs/version-0.14/reference/protocol/asset.md b/versioned_docs/version-0.14/reference/protocol/asset.md index 8cd17a02..66397b4a 100644 --- a/versioned_docs/version-0.14/reference/protocol/asset.md +++ b/versioned_docs/version-0.14/reference/protocol/asset.md @@ -123,6 +123,49 @@ A callback is not invoked in any of these cases: This means assets with callbacks enabled can still be used even if the faucet has not (yet) registered a callback procedure. +## Encoding + +Every native asset occupies two words (64 bytes): an `ASSET_KEY` (vault key) that identifies the asset in an account vault SMT, and an `ASSET_VALUE` that carries the asset payload. + +### `ASSET_KEY` / `AssetVaultKey` layout + +The vault key is a [`Word`](https://docs.rs/miden-protocol) with this limb order (matching `AssetVaultKey::to_word()` in v0.14): + +```text +[ + asset_id_suffix, // Felt + asset_id_prefix, // Felt + faucet_id_suffix_and_metadata, // Felt + faucet_id_prefix // Felt +] +``` + +Where `faucet_id_suffix_and_metadata` packs: + +```text +[ faucet_id_suffix (56 bits) | 7 zero bits | callbacks_enabled (1 bit) ] +``` + +The low byte of the faucet account-id suffix is reserved for metadata (it is zero in a bare faucet id). The least-significant bit of that byte is the [`AssetCallbackFlag`](#callbacks): `0` disabled, `1` enabled. + +### Fungible vs non-fungible keys + +| Kind | `asset_id_*` limbs | Meaning | +| --- | --- | --- | +| Fungible | both zero | All fungible units from a faucet share one vault leaf and merge by amount. | +| Non-fungible | taken from `DATA_HASH[0..2]` | Each NFT has a distinct key (and therefore a distinct leaf). | + +### `ASSET_VALUE` layout + +| Kind | Value word | +| --- | --- | +| Fungible | `[amount, 0, 0, 0]` — `amount ≤ 2⁶³−1` | +| Non-fungible | full 4-limb `DATA_HASH` of the NFT payload | + +### Stdlib helpers + +When building assets from arbitrary code (not as the faucet itself), use `miden::protocol::asset::create_fungible_asset` / `create_non_fungible_asset`. Both take an `enable_callbacks` flag so the metadata bit is set explicitly — see [Protocol library](./protocol_library.md#asset-procedures-midenprotocolasset). + ## Alternative asset models :::note diff --git a/versioned_docs/version-0.14/reference/protocol/protocol_library.md b/versioned_docs/version-0.14/reference/protocol/protocol_library.md index 7981bba1..afe9efd1 100644 --- a/versioned_docs/version-0.14/reference/protocol/protocol_library.md +++ b/versioned_docs/version-0.14/reference/protocol/protocol_library.md @@ -163,4 +163,4 @@ Asset procedures provide utilities for creating fungible and non-fungible assets | Procedure | Description | Context | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `create_fungible_asset` | Builds a fungible asset for the specified fungible faucet and amount.

**Inputs:** `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]`
**Outputs:** `[ASSET_KEY, ASSET_VALUE]` | Any | -| `create_non_fungible_asset` | Builds a non-fungible asset for the specified non-fungible faucet and data hash.

**Inputs:** `[faucet_id_suffix, faucet_id_prefix, DATA_HASH]`
**Outputs:** `[ASSET_KEY, ASSET_VALUE]` | Any | +| `create_non_fungible_asset` | Builds a non-fungible asset for the specified non-fungible faucet and data hash.

**Inputs:** `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH]`
**Outputs:** `[ASSET_KEY, ASSET_VALUE]` | Any | From af9c2fe41069adcf200848fed60c258b21060643 Mon Sep 17 00:00:00 2001 From: KutluhanETH Date: Wed, 9 Sep 2026 12:05:06 +0000 Subject: [PATCH 2/2] docs(0.14): correct fungible MAX_AMOUNT to 2^63-2^31 Align the vault encoding table and fungible asset prose with FungibleAsset::MAX_AMOUNT / FUNGIBLE_ASSET_MAX_AMOUNT (0x7fffffff80000000). --- versioned_docs/version-0.14/reference/protocol/asset.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versioned_docs/version-0.14/reference/protocol/asset.md b/versioned_docs/version-0.14/reference/protocol/asset.md index 66397b4a..a9e2965f 100644 --- a/versioned_docs/version-0.14/reference/protocol/asset.md +++ b/versioned_docs/version-0.14/reference/protocol/asset.md @@ -46,7 +46,7 @@ Faucets can issue either fungible or non-fungible assets as defined at account c #### Fungible asset -Fungible assets are encoded with the amount and the `faucet_id` of the issuing faucet. The amount is always $2^{63}-1$ or smaller, representing the maximum supply for any fungible `Asset`. Examples include ETH and various stablecoins (e.g., DAI, USDT, USDC). +Fungible assets are encoded with the amount and the `faucet_id` of the issuing faucet. The amount is always $2^{63}-2^{31}$ or smaller, representing the maximum supply for any fungible `Asset`. Examples include ETH and various stablecoins (e.g., DAI, USDT, USDC). #### Non-fungible asset @@ -159,7 +159,7 @@ The low byte of the faucet account-id suffix is reserved for metadata (it is zer | Kind | Value word | | --- | --- | -| Fungible | `[amount, 0, 0, 0]` — `amount ≤ 2⁶³−1` | +| Fungible | `[amount, 0, 0, 0]` — `amount ≤ 2⁶³−2³¹` | | Non-fungible | full 4-limb `DATA_HASH` of the NFT payload | ### Stdlib helpers