From afdfc514c46354beb81e3870d98f8c269ce867da Mon Sep 17 00:00:00 2001 From: Dominik Schmid Date: Sun, 2 Mar 2025 22:17:43 +0100 Subject: [PATCH] updating account Id in the docs --- docs/architecture/account.md | 57 +++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 23 deletions(-) diff --git a/docs/architecture/account.md b/docs/architecture/account.md index 082b11fff..d8341a388 100644 --- a/docs/architecture/account.md +++ b/docs/architecture/account.md @@ -1,10 +1,10 @@ -# Account +# Account / Smart Contract An `Account` represents the primary entity of the protocol. Capable of holding assets, storing data, and executing custom code. Each `Account` is a specialized smart contract providing a programmable interface for interacting with its state and assets. ## What is the purpose of an account? -In Miden's hybrid UTXO and account-based model `Account`s enable the creation of expressive smart contracts via a Turing-complete language. +In Miden's hybrid UTXO- and account-based model `Account`s enable the creation of expressive smart contracts via a Turing-complete language. ## Account core components @@ -20,26 +20,35 @@ These components are: 2. [Code](#code) 3. [Storage](#storage) 4. [Vault](#vault) -5. [Nonce](#nonce) +5. [Nonce](#nonce) ### ID > An immutable and unique identifier for the `Account`. -A 63-bit long number represents the `Account` ID. It's four most significant bits encode: -- [**Account type:**](#the-accounts-type) basic or faucet. -- [**Account storage mode:**](#the-accounts-storage-mode) public or private. +A 120-bit long number represents the `Account` ID. This identifier is structured to encapsulate specific account metadata while preventing precomputed attack vectors (e.g., rainbow table attacks). -This encoding allows the ID to convey both the `Account`’s unique identity and its operational settings. +The ID is generated by hashing a user-generated random seed together with commitments to the initial code and storage of the `Account` and the anchor block. The anchor block refers to specific blockchain epoch block in which the account is created. The resulting 256-bit long hash is then manipulated and shortened to 120-bit. Manipulation includes encoding the [account type](#the-accounts-type), [account storage mode](#the-accounts-storage-mode), the version of the `Account` ID scheme, and the anchor block. + +Account type, storage mode, and version are included in the ID, to ensure these properties can be determined without additional computation. Anyone can immediately tell those properties by just looking at the ID in bit representation. + +Also, the ID generation process ensures that an attacker cannot precompute an ID before the anchor block's commitment is available. This significantly mitigates the risk of ID hijacking, where an adversary might attempt to claim assets sent to an unregistered ID. +By anchoring the ID to a recent epoch block, the window for potential attacks is minimized, reinforcing the security of asset transfers and account registration. + +An `Account` ID is considered invalid if: + +- The metadata (storage mode, type, or version) does not match any recognized values. +- The anchor epoch exceeds $2^{16}-1$. +- The least significant 8 bits of the ID are nonzero. ### Code > A collection of functions defining the `Account`’s programmable interface. -Every Miden `Account` is essentially a smart contract. The `Code` component defines the account’s functions, which can be invoked through both [Note scripts](notes.md#the-note-script) and transaction scripts. Key characteristics include: +Every Miden `Account` is essentially a smart contract. The `Code` component defines the account’s functions, which can be invoked through both [Note scripts](notes.md#the-note-script) and [transaction scripts](transaction.md#inputs). Key characteristics include: -- **Mutable access:** Only the `Account`’s own functions can modify its storage and vault. All state changes—such as updating storage slots, incrementing the nonce, or transferring assets—must occur through these functions. -- **Function commitment:** Each function can be called by its [MAST](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) root. The root represents the underlying code tree as a 32-byte hash. This ensures integrity, i.e., the caller calls what he expects. +- **Mutable access:** Only the `Account`’s own functions can modify its storage and vault. All state changes—such as updating storage slots, incrementing the nonce, or transferring assets—must occur through these functions. +- **Function commitment:** Each function can be called by its [MAST](https://0xpolygonmiden.github.io/miden-vm/user_docs/assembly/main.html) root. The root represents the underlying code tree as a 32-byte commitment. This ensures integrity, i.e., the caller calls what he expects. - **Note creation:** `Account` functions can generate new notes. ### Storage @@ -48,8 +57,8 @@ Every Miden `Account` is essentially a smart contract. The `Code` component defi The [storage](../../objects/src/accounts/storage/mod.rs) is divided into a maximum of 255 indexed [storage slots](../../objects/src/accounts/storage/slot/mod.rs). Each slot can either store a 32-byte value or serve as a pointer to a key-value store with large amounts capacity. -- **`StorageSlot::Value`:** Contains 32 bytes of arbitrary data. -- **`StorageSlot::Map`:** Contains a [StorageMap](../../objects/src/accounts/storage/map.rs), a key-value store where both keys and values are 32 bytes. The slot's value is a commitment (hash) to the entire map. +- **`StorageSlot::Value`:** Contains 32 bytes of arbitrary data. +- **`StorageSlot::Map`:** Contains a [StorageMap](../../objects/src/accounts/storage/map.rs), a key-value store where both keys and values are 32 bytes. The slot's value is a commitment to the entire map. ### Vault @@ -61,14 +70,16 @@ Large amounts of fungible and non-fungible assets can be stored in the `Account` > A counter incremented with each state update to the `Account`. -The nonce enforces ordering and prevents replay attacks. It must strictly increase with every `Account` state update. The increment must be less than `2^32` but always greater than the previous nonce, ensuring a well-defined sequence of state changes. +The nonce enforces ordering and prevents replay attacks. It must strictly increase with every `Account` state update. The increment must be less than $2^{32}$ but always greater than the previous nonce, ensuring a well-defined sequence of state changes. + +If a smart contract function should be callable by other users, it must increment the `Account`'s nonce. Otherwise, only the contract owner—i.e., the party possessing the contract's key—can execute the function. ## Account lifecycle Throughout its lifetime, an `Account` progresses through various phases: - **Creation and Deployment:** Initialization of the `Account` on the network. -- **Active Operation:** Continuous state updates via `Account` functions that modify the storage, nonce, and vault. +- **Active Operation:** Continuous state updates via `Account` functions that modify the storage, nonce, and vault. - **Termination or Deactivation:** Optional, depending on the contract’s design and governance model. ### Account creation @@ -77,11 +88,11 @@ For an `Account` to be recognized by the network, it must exist in the [account However, a user can locally create a new `Account` ID before it’s recognized network-wide. The typical process might be: -1. Alice generates a new `Account` ID locally (according to the desired `Account` type) using the Miden client. -2. The Miden client checks with a Miden node to ensure the ID does not already exist. -3. Alice shares the new ID with Bob (for example, to receive assets). -4. Bob executes a transaction, creating a note containing assets for Alice. -5. Alice consumes Bob’s note in her own transaction to claim the asset. +1. Alice generates a new `Account` ID locally (according to the desired `Account` type) using the Miden client. +2. The Miden client checks with a Miden node to ensure the ID does not already exist. +3. Alice shares the new ID with Bob (for example, to receive assets). +4. Bob executes a transaction, creating a note containing assets for Alice. +5. Alice consumes Bob’s note in her own transaction to claim the asset. 6. Depending on the `Account`’s storage mode and transaction type, the operator receives the new `Account` ID and, if all conditions are met, includes it in the `Account` database. ## Additional information @@ -90,12 +101,12 @@ However, a user can locally create a new `Account` ID before it’s recognized n There are two main categories of `Account`s in Miden: **basic accounts** and **faucets**. -- **Basic Accounts:** +- **Basic Accounts:** Basic Accounts may be either mutable or immutable: - *Mutable:* Code can be changed after deployment. - *Immutable:* Code cannot be changed once deployed. -- **Faucets:** +- **Faucets:** Faucets are always immutable and can be specialized by the type of assets they issue: - *Fungible Faucet:* Can issue fungible [assets](assets.md). - *Non-fungible Faucet:* Can issue non-fungible [assets](assets.md). @@ -106,10 +117,10 @@ Type and mutability are encoded in the two most significant bits of the `Account Users can choose whether their `Account`s are stored publicly or privately. The preference is encoded in the third and forth most significant bits of the `Account`s [ID](#id): -- **Public `Account`s:** +- **Public `Account`s:** The `Account`’s state is stored on-chain, similar to how `Account`s are stored in public blockchains like Ethereum. Contracts that rely on a shared, publicly accessible state (e.g., a DEX) should be public. -- **Private `Account`s:** +- **Private `Account`s:** Only a commitment (hash) to the `Account`’s state is stored on-chain. This mode is suitable for users who prioritize privacy or plan to store a large amount of data in their `Account`. To interact with a private `Account`, a user must have knowledge of its interface. The storage mode is chosen during `Account` creation, it cannot be changed later.