docs(protocol): document v0.14 asset encoding

docs/builder/migration/05-asset-vault-faucet.md

@@ -16,12 +16,11 @@ Assets are now represented as two words (`ASSET_KEY` + `ASSET_VALUE`) instead of
 
 ### Summary
 
-The single 4-felt `ASSET` word has been split into two words:
+The single 4-felt `ASSET` word has been split into two words: `ASSET_KEY` (identity + faucet + callback flag) and `ASSET_VALUE` (amount or data hash). Every kernel procedure and standard-library helper that previously accepted or returned `ASSET` now works with the `ASSET_KEY, ASSET_VALUE` pair.
 
-- **`ASSET_KEY`** = `[asset_id_suffix, asset_id_prefix, (faucet_id_suffix << 8) | callbacks_enabled, faucet_id_prefix]`
-- **`ASSET_VALUE`** = `[amount, 0, 0, 0]` for fungible assets, or `DATA_HASH` for non-fungible assets.
-
-Every kernel procedure and standard-library helper that previously accepted or returned `ASSET` now works with the `ASSET_KEY, ASSET_VALUE` pair.
+:::note Canonical layout
+The full field-by-field layout — including how the per-asset callback flag is packed into the reserved low byte of `faucet_id_suffix` — is documented in [Asset encoding](../../core-concepts/protocol/asset.md#encoding). This page covers the v0.13 → v0.14 delta only.
+:::
 
 ### Affected Code
 
@@ -74,15 +73,23 @@ The `asset::build_fungible_asset` and `asset::build_non_fungible_asset` procedur
 
 ### Affected Code
 
-**MASM (fungible asset creation):**
+**MASM (asset creation):**
 ```masm
-# Before (0.13): stack = [faucet_id_prefix, faucet_id_suffix, amount, ...]
+# Before (0.13): fungible stack = [faucet_id_prefix, faucet_id_suffix, amount, ...]
 exec.asset::build_fungible_asset
 # -> [ASSET, ...]
 
-# After (0.14): stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount, ...]
+# Before (0.13): non-fungible stack = [faucet_id_prefix, faucet_id_suffix, DATA_HASH, ...]
+exec.asset::build_non_fungible_asset
+# -> [ASSET, ...]
+
+# After (0.14): fungible stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount, ...]
 exec.asset::create_fungible_asset
 # -> [ASSET_KEY, ASSET_VALUE, ...]
+
+# After (0.14): non-fungible stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH, ...]
+exec.asset::create_non_fungible_asset
+# -> [ASSET_KEY, ASSET_VALUE, ...]
 ```
 
 **Rust:**
@@ -101,7 +108,7 @@ let asset = FungibleAsset::new(faucet_id, amount)?;
 1. Rename all `exec.asset::build_fungible_asset` calls to `exec.asset::create_fungible_asset`.
 2. Rename all `exec.asset::build_non_fungible_asset` calls to `exec.asset::create_non_fungible_asset`.
 3. Add the `enable_callbacks` flag as the new top-of-stack element.
-4. Note the changed argument order: `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]`.
+4. Note the changed argument order: `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]` for fungible assets and `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH]` for non-fungible assets.
 5. Update consumers to expect `[ASSET_KEY, ASSET_VALUE]` on the stack instead of a single `[ASSET]`.
 
 ### Common Errors
@@ -110,7 +117,7 @@ let asset = FungibleAsset::new(faucet_id, amount)?;
 | --- | --- | --- |
 | `unknown procedure asset::build_fungible_asset` | Procedure renamed | Use `asset::create_fungible_asset`. |
 | `unknown procedure asset::build_non_fungible_asset` | Procedure renamed | Use `asset::create_non_fungible_asset`. |
-| `FailedAssertion` in `create_fungible_asset` | Missing `enable_callbacks` flag or wrong argument order | Push `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]`. |
+| `FailedAssertion` in `create_*_asset` | Missing `enable_callbacks` flag or wrong argument order | Push `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]` for fungible assets, or `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH]` for non-fungible assets. |
 
 ---
 

versioned_docs/version-0.14/builder/migration/05-asset-vault-faucet.md

@@ -16,12 +16,11 @@ Assets are now represented as two words (`ASSET_KEY` + `ASSET_VALUE`) instead of
 
 ### Summary
 
-The single 4-felt `ASSET` word has been split into two words:
+The single 4-felt `ASSET` word has been split into two words: `ASSET_KEY` (identity + faucet + callback flag) and `ASSET_VALUE` (amount or data hash). Every kernel procedure and standard-library helper that previously accepted or returned `ASSET` now works with the `ASSET_KEY, ASSET_VALUE` pair.
 
-- **`ASSET_KEY`** = `[asset_id_suffix, asset_id_prefix, (faucet_id_suffix << 8) | callbacks_enabled, faucet_id_prefix]`
-- **`ASSET_VALUE`** = `[amount, 0, 0, 0]` for fungible assets, or `DATA_HASH` for non-fungible assets.
-
-Every kernel procedure and standard-library helper that previously accepted or returned `ASSET` now works with the `ASSET_KEY, ASSET_VALUE` pair.
+:::note Canonical layout
+The full field-by-field layout — including how the per-asset callback flag is packed into the reserved low byte of `faucet_id_suffix` — is documented in [Asset encoding](../../core-concepts/protocol/asset.md#encoding). This page covers the v0.13 → v0.14 delta only.
+:::
 
 ### Affected Code
 
@@ -74,15 +73,23 @@ The `asset::build_fungible_asset` and `asset::build_non_fungible_asset` procedur
 
 ### Affected Code
 
-**MASM (fungible asset creation):**
+**MASM (asset creation):**
 ```masm
-# Before (0.13): stack = [faucet_id_prefix, faucet_id_suffix, amount, ...]
+# Before (0.13): fungible stack = [faucet_id_prefix, faucet_id_suffix, amount, ...]
 exec.asset::build_fungible_asset
 # -> [ASSET, ...]
 
-# After (0.14): stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount, ...]
+# Before (0.13): non-fungible stack = [faucet_id_prefix, faucet_id_suffix, DATA_HASH, ...]
+exec.asset::build_non_fungible_asset
+# -> [ASSET, ...]
+
+# After (0.14): fungible stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount, ...]
 exec.asset::create_fungible_asset
 # -> [ASSET_KEY, ASSET_VALUE, ...]
+
+# After (0.14): non-fungible stack = [enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH, ...]
+exec.asset::create_non_fungible_asset
+# -> [ASSET_KEY, ASSET_VALUE, ...]
 ```
 
 **Rust:**
@@ -101,7 +108,7 @@ let asset = FungibleAsset::new(faucet_id, amount)?;
 1. Rename all `exec.asset::build_fungible_asset` calls to `exec.asset::create_fungible_asset`.
 2. Rename all `exec.asset::build_non_fungible_asset` calls to `exec.asset::create_non_fungible_asset`.
 3. Add the `enable_callbacks` flag as the new top-of-stack element.
-4. Note the changed argument order: `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]`.
+4. Note the changed argument order: `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]` for fungible assets and `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH]` for non-fungible assets.
 5. Update consumers to expect `[ASSET_KEY, ASSET_VALUE]` on the stack instead of a single `[ASSET]`.
 
 ### Common Errors
@@ -110,7 +117,7 @@ let asset = FungibleAsset::new(faucet_id, amount)?;
 | --- | --- | --- |
 | `unknown procedure asset::build_fungible_asset` | Procedure renamed | Use `asset::create_fungible_asset`. |
 | `unknown procedure asset::build_non_fungible_asset` | Procedure renamed | Use `asset::create_non_fungible_asset`. |
-| `FailedAssertion` in `create_fungible_asset` | Missing `enable_callbacks` flag or wrong argument order | Push `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]`. |
+| `FailedAssertion` in `create_*_asset` | Missing `enable_callbacks` flag or wrong argument order | Push `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, amount]` for fungible assets, or `[enable_callbacks, faucet_id_suffix, faucet_id_prefix, DATA_HASH]` for non-fungible assets. |
 
 ---
 

versioned_docs/version-0.14/core-concepts/protocol/asset.md

@@ -60,6 +60,45 @@ Non-fungible assets are encoded by hashing the `Asset` data into 32 bytes and pl
     <img src={require('./img/asset/asset-storage.png').default} style={{width: '70%'}} alt="Asset storage"/>
 </p>
 
+### 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.
+
+```
+ASSET_KEY   = [asset_id_suffix, asset_id_prefix, faucet_id_suffix_with_metadata, faucet_id_prefix]
+ASSET_VALUE = [amount, 0, 0, 0]   # fungible
+ASSET_VALUE = DATA_HASH           # non-fungible
+```
+
+The `asset_id_*` limbs distinguish different assets issued by the same faucet:
+
+- 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.
+
+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 remaining 7 bits are reserved for future asset-level metadata.
+
+#### 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:
+
+```text
+[ 0,                       ← asset_id_suffix (zero for fungible)
+  0,                       ← asset_id_prefix (zero for fungible)
+  447750849984126721,      ← faucet_id_suffix | callbacks_enabled (suffix ends in 0x00, OR'd with 0x01)
+  12959558562786060576,    ← faucet_id_prefix
+  10000,                   ← amount
+  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`.
+
 ### Burning
 
 Assets in Miden can be burned through various methods, such as rendering them unspendable by storing them in an unconsumable note, or sending them back to their original faucet for burning using it's dedicated function.