Struct AccountBuilder 

pub struct AccountBuilder { /* private fields */ }

A convenient builder for an Account allowing for safe construction of an account by combining multiple AccountComponents.

This will build a valid new account with these properties:

• An empty AssetVault.
• The nonce set to Felt::ZERO.
• A seed which results in an AccountId valid for the configured account type.

By default, the builder is initialized with:

• The account_type set to AccountType::Private.
• The version set to AccountIdVersion::Version1.

Asset Callbacks

The AssetCallbackFlag determines whether the tx kernel dispatches asset callbacks for assets issued by the account (if any) and is encoded into the resulting AccountId at creation. Note that the flag only enables the dispatch: whether a callback actually runs additionally depends on the corresponding callback slot being present and holding a non-empty procedure root, so an enabled flag means callbacks may be invoked, not that the account has any.

The flag is derived from the account’s storage: it is AssetCallbackFlag::Enabled if any component installs one of the protocol-reserved asset callback slots (see AccountStorage::has_callback_slots) and AssetCallbackFlag::Disabled otherwise. There is deliberately no way to disable the flag for an account that does install such a slot, since the tx kernel gates callback invocation on the flag alone and the flag cannot be changed after the ID is ground, so such a callback could never be invoked.

The converse is allowed: AccountBuilder::enable_asset_callbacks enables the flag without installing a callback slot, so that the account retains the ability to add a callback slot via an account upgrade later. This is particularly useful if new types of callbacks are introduced.

An enabled flag makes the account’s state a required input of every transaction that moves one of its assets: dispatching a callback starts a foreign context against the issuing account, and the foreign state is loaded before the callback slot is looked up, so the load happens even when no callback procedure root is registered. An AccountType::Private account publishes only its commitment, so its holders have to obtain that state out of band. Both the account type and the flag are immutable parts of the AccountId, so this is settled at creation.

AccountBuilder::with_component (or AccountBuilder::with_components) must be called at least once, and exactly one of the added components must be an authentication component (i.e. a component exporting a procedure marked with the @auth_script attribute). The auth component is identified and extracted automatically when AccountBuilder::build is called.

Security

The builder only enforces the structural requirement of exactly one auth component; it does not check that the auth component is a sensible choice for the other components on the account. In particular, an auth component that performs no authentication makes the account permissionless: every state-changing procedure it exposes can be called by anyone. This is especially dangerous when combined with components that rely on the auth component as their sole access gate (such as authority-controlled setters), which then become permissionless as well. Higher-level factory functions vet these combinations; when building an account directly, the caller is responsible for pairing a suitable auth component with the account’s other components.

Under the testing feature, it is possible to:

• Build an existing account using AccountBuilder::build_existing, which will set the account’s nonce to 1 by default, or to the configured value.
• Add assets to the account’s vault; this only succeeds when using AccountBuilder::build_existing.

Account Procedure Order

Note that the auth procedure is always moved to the first position, since the tx kernel assumes procedure index 0 is the auth procedure within an AccountCode. The procedures of all other components are merged and sorted, so the order in which with_component is called does not affect the resulting account code commitment.

Implementations

impl AccountBuilder

pub fn new(init_seed: [u8; 32]) -> AccountBuilder

Creates a new builder for an account and sets the initial seed from which the grinding process for that account’s AccountId will start.

This initial seed should come from a cryptographic random number generator.

pub fn version(self, version: AccountIdVersion) -> AccountBuilder

Sets the AccountIdVersion of the account ID.

pub fn account_type(self, account_type: AccountType) -> AccountBuilder

Sets the account type of the account.

pub fn enable_asset_callbacks(self) -> AccountBuilder

Enables the immutable AssetCallbackFlag of the account even if none of its components install an asset callback slot.

See the type-level docs for details.

pub fn with_component( self, account_component: impl Into<AccountComponent>, ) -> AccountBuilder

Adds an AccountComponent to the builder. This method can be called multiple times and must be called at least once since an account must export at least one procedure.

All components will be merged to form the final code and storage of the built account. Exactly one of the added components must be an authentication component (see AccountComponent::is_auth_component); it is identified and moved to the front of the procedure list automatically when Self::build is called, while all other procedures are sorted.

For composite configurations that expand into multiple components (such as AccessControl or TokenPolicyManager), use Self::with_components.

pub fn with_components( self, components: impl IntoIterator<Item = impl Into<AccountComponent>>, ) -> AccountBuilder

Adds the components yielded by components to the builder.

This is a convenience wrapper around repeated Self::with_component calls. It is most useful for installing the variable number of components produced by composite configurations whose component count is not known at the call site (for example, a configuration value that expands into one or several components depending on its variant).

pub fn storage_schemas(&self) -> impl Iterator<Item = &StorageSchema>

Returns an iterator of storage schemas attached to the builder’s components.

pub fn build(self) -> Result<Account, AccountError>

Builds an Account out of the configured builder.

Errors

Returns an error if:

• The init seed is not set.
• The number of procedures in all merged components is 0 or exceeds AccountCode::MAX_NUM_PROCEDURES.
• Two or more packages export a procedure with the same MAST root.
• Authentication component is missing.
• Multiple authentication procedures are found.
• The number of StorageSlots of all components exceeds 255.
• MastForest::merge fails on the given components.
• If duplicate assets were added to the builder (only under the testing feature).
• If the vault is not empty on new accounts (only under the testing feature).

Trait Implementations

impl AccountBuilderSchemaCommitmentExt for AccountBuilder

fn build_with_schema_commitment(self) -> Result<Account, AccountError>

Builds an Account out of the configured builder after computing the storage schema commitment from all components currently in the builder and adding an AccountSchemaCommitment component.

impl Clone for AccountBuilder

fn clone(&self) -> AccountBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AccountBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.