@aztec-labs/aztec.js 6.0.0-nightly.20260829

package/src/wallet/account_manager.ts

@@ -0,0 +1,164 @@
+import { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+import {
+  CompleteAddress,
+  type ContractInstanceWithAddress,
+  getContractInstanceFromInstantiationParams,
+} from '@aztec-labs/stdlib/contract';
+import type { PublicKeys } from '@aztec-labs/stdlib/keys';
+import { deriveKeys } from '@aztec-labs/stdlib/keys';
+
+import type { AccountContract } from '../account/account_contract.js';
+import type { Account, Salt } from '../account/index.js';
+import { Contract } from '../contract/contract.js';
+import { DeployAccountMethod } from './deploy_account_method.js';
+import type { Wallet } from './wallet.js';
+
+/**
+ * Optional overrides passed to {@link AccountManager.create}.
+ */
+export interface AccountManagerCreateOptions {
+  /** Contract instantiation salt. Defaults to a random `Fr`. */
+  salt?: Salt;
+  /**
+   * Commitment to the contract's immutable storage values. Folded into the salted initialization
+   * hash, so a non-zero value affects the derived address. Defaults to `Fr.ZERO`.
+   */
+  immutablesHash?: Fr;
+  /** Address recorded as the instance deployer. Defaults to `AztecAddress.ZERO`. */
+  deployer?: AztecAddress;
+}
+
+/**
+ * Manages a user account. Provides methods for calculating the account's address and other related data,
+ * plus a helper to return a preconfigured deploy method.
+ */
+export class AccountManager {
+  private constructor(
+    private wallet: Wallet,
+    private secretKey: Fr,
+    private accountContract: AccountContract,
+    private instance: ContractInstanceWithAddress,
+  ) {}
+
+  static async create(
+    wallet: Wallet,
+    secretKey: Fr,
+    accountContract: AccountContract,
+    opts?: AccountManagerCreateOptions,
+  ) {
+    const { publicKeys } = await deriveKeys(secretKey);
+    const salt = opts?.salt !== undefined ? new Fr(opts.salt) : Fr.random();
+
+    const { constructorName, constructorArgs } = (await accountContract.getInitializationFunctionAndArgs()) ?? {
+      constructorName: undefined,
+      constructorArgs: undefined,
+    };
+
+    const artifact = await accountContract.getContractArtifact();
+    const instance = await getContractInstanceFromInstantiationParams(artifact, {
+      constructorArtifact: constructorName,
+      constructorArgs,
+      salt,
+      publicKeys,
+      deployer: opts?.deployer,
+      immutablesHash: opts?.immutablesHash ?? (await accountContract.getImmutablesHash()),
+    });
+
+    return new AccountManager(wallet, secretKey, accountContract, instance);
+  }
+
+  protected getPublicKeys(): PublicKeys {
+    return this.instance.publicKeys;
+  }
+
+  protected getPublicKeysHash(): Promise<Fr> {
+    return this.getPublicKeys().hash();
+  }
+
+  /**
+   * Gets the calculated complete address associated with this account.
+   * Does not require the account to have been published for public execution.
+   * @returns The address, partial address, and encryption public key.
+   */
+  public getCompleteAddress(): Promise<CompleteAddress> {
+    return CompleteAddress.fromSecretKeyAndInstance(this.secretKey, this.instance);
+  }
+
+  /**
+   * Returns the secret key used to derive the rest of the privacy keys for this contract
+   */
+  public getSecretKey() {
+    return this.secretKey;
+  }
+
+  get address(): AztecAddress {
+    return this.instance.address;
+  }
+
+  /**
+   * Returns the contract instance definition associated with this account.
+   * Does not require the account to have been published for public execution.
+   * @returns ContractInstance instance.
+   */
+  public getInstance(): ContractInstanceWithAddress {
+    return this.instance;
+  }
+
+  /**
+   * Returns the account (the transaction signer) backed by this account contract. Use it to build and authorize
+   * transactions from this account.
+   */
+  public async getAccount(): Promise<Account> {
+    const completeAddress = await this.getCompleteAddress();
+    return this.accountContract.getAccount(completeAddress);
+  }
+
+  /**
+   * Returns the account contract that backs this account.
+   * @returns The account contract
+   */
+  getAccountContract(): AccountContract {
+    return this.accountContract;
+  }
+
+  /**
+   * Returns a preconfigured deploy method that contains all the necessary function
+   * calls to deploy the account contract.
+   */
+  public async getDeployMethod(): Promise<DeployAccountMethod> {
+    const artifact = await this.accountContract.getContractArtifact();
+
+    if (!(await this.hasInitializer())) {
+      // TODO(https://github.com/AztecProtocol/aztec-packages/issues/15576):
+      // there should be a path which enables an account contract's class & instance to be published,
+      // even if the account contract doesn't have an initializer function. This should not throw.
+      throw new Error(`Account contract ${artifact.name} does not have an initializer function to call.`);
+    }
+
+    const { constructorName, constructorArgs } = (await this.accountContract.getInitializationFunctionAndArgs()) ?? {
+      constructorName: undefined,
+      constructorArgs: undefined,
+    };
+
+    const account = await this.getAccount();
+    return new DeployAccountMethod(
+      this.getPublicKeys(),
+      this.wallet,
+      artifact,
+      instance => Contract.at(instance.address, artifact, this.wallet),
+      this.instance.salt,
+      this.instance.immutablesHash,
+      account,
+      constructorArgs,
+      constructorName,
+    );
+  }
+
+  /**
+   * Returns whether this account contract has an initializer function.
+   */
+  public async hasInitializer() {
+    return (await this.accountContract.getInitializationFunctionAndArgs()) !== undefined;
+  }
+}

package/src/wallet/capabilities.ts

@@ -0,0 +1,505 @@
+import type { Fr } from '@aztec-labs/foundation/curves/bn254';
+import type { AztecAddress } from '@aztec-labs/stdlib/aztec-address';
+
+import type { Aliased } from './wallet.js';
+
+/**
+ * Current capability manifest version.
+ */
+export const CAPABILITY_VERSION = '1.0' as const;
+
+/**
+ * Pattern for matching contract functions with wildcards.
+ *
+ * Used in simulation and transaction capabilities to specify which
+ * contract functions are allowed.
+ *
+ * @example
+ * // Allow any function on a specific contract
+ * \{ contract: ammAddress, function: '*' \}
+ *
+ * @example
+ * // Allow only 'swap' function on a specific contract
+ * \{ contract: ammAddress, function: 'swap' \}
+ *
+ * @example
+ * // Allow 'transfer' on any contract
+ * \{ contract: '*', function: 'transfer' \}
+ */
+export interface ContractFunctionPattern {
+  /** Contract address or '*' for any contract */
+  contract: AztecAddress | '*';
+
+  /** Function name or '*' for any function */
+  function: string;
+
+  /**
+   * Additional addresses whose private state and keys are accessible
+   * when calling this function, beyond the sender's.
+   * - undefined: No additional scopes allowed
+   * - AztecAddress[]: Only these specific addresses allowed as additional scopes
+   * - '*': All known address allowed as an additional scope
+   */
+  additionalScopes?: AztecAddress[] | '*';
+}
+
+/**
+ * Account access capability - grants access to user accounts.
+ *
+ * Maps to wallet methods:
+ * - getAccounts (when canGet: true)
+ * - createAuthWit (when canCreateAuthWit: true)
+ *
+ * The wallet decides which accounts to reveal to the app.
+ * Apps don't specify which accounts they want - they just request
+ * the capability and the wallet shows them the available accounts.
+ */
+export interface AccountsCapability {
+  /** Discriminator for capability type */
+  type: 'accounts';
+
+  /** Can get accounts from wallet. Maps to: getAccounts */
+  canGet?: boolean;
+
+  /** Can create auth witnesses for accounts. Maps to: createAuthWit */
+  canCreateAuthWit?: boolean;
+}
+
+/**
+ * Granted account access capability.
+ *
+ * Extends the request with specific accounts that were granted by the wallet.
+ */
+export interface GrantedAccountsCapability extends AccountsCapability {
+  /** Specific accounts granted by the wallet with their aliases. The wallet adds this when granting the capability. */
+  accounts: Aliased<AztecAddress>[];
+}
+
+/**
+ * Contract interaction capability - for registering and querying contracts.
+ *
+ * Maps to wallet methods:
+ * - registerContract (when canRegister: true)
+ * - getContractMetadata (when canGetMetadata: true)
+ *
+ * Matching is done by contract address, not class ID. This allows updating
+ * existing contracts with new artifacts (e.g., when contract is upgraded
+ * to a new contractClassId onchain).
+ *
+ * Note: For querying contract class metadata, use ContractClassesCapability instead.
+ *
+ * @example
+ * // Register and query specific contracts
+ * \{
+ *   type: 'contracts',
+ *   contracts: [ammAddress, tokenAddress],
+ *   canRegister: true,
+ *   canGetMetadata: true
+ * \}
+ *
+ * @example
+ * // Query any contract (read-only)
+ * \{
+ *   type: 'contracts',
+ *   contracts: '*',
+ *   canGetMetadata: true
+ * \}
+ */
+export interface ContractsCapability {
+  /** Discriminator for capability type */
+  type: 'contracts';
+
+  /**
+   * Which contracts this applies to:
+   * - '*': Any contract address
+   * - AztecAddress[]: Specific contract addresses
+   */
+  contracts: '*' | AztecAddress[];
+
+  /**
+   * Can register contracts and update existing registrations.
+   * Maps to: registerContract
+   *
+   * When true, allows:
+   * - Registering new contract instances at specified addresses
+   * - Re-registering existing contracts with updated artifacts (e.g., after upgrade)
+   */
+  canRegister?: boolean;
+
+  /** Can query contract metadata. Maps to: getContractMetadata */
+  canGetMetadata?: boolean;
+}
+
+/**
+ * Granted contract interaction capability.
+ *
+ * The wallet may reduce the scope (e.g., from '*' to specific addresses).
+ */
+export interface GrantedContractsCapability extends ContractsCapability {}
+
+/**
+ * Contract class capability - for querying contract class metadata and registering contract classes.
+ *
+ * Maps to wallet methods:
+ * - getContractClassMetadata (when canGetMetadata: true)
+ * - registerContractClass (when canRegister: true)
+ *
+ * Contract classes are identified by their class ID (Fr), not by contract address.
+ * Multiple contract instances can share the same class. This capability grants
+ * permission to query metadata for, and register, specific contract classes.
+ *
+ * Apps typically acquire this permission automatically when registering a contract
+ * with an artifact (the wallet auto-grants permission for that contract's class ID).
+ *
+ * @example
+ * // Register and query a specific contract class
+ * \{
+ *   type: 'contractClasses',
+ *   classes: [classId1],
+ *   canRegister: true,
+ *   canGetMetadata: true
+ * \}
+ *
+ * @example
+ * // Query any contract class (wildcard)
+ * \{
+ *   type: 'contractClasses',
+ *   classes: '*',
+ *   canGetMetadata: true
+ * \}
+ */
+export interface ContractClassesCapability {
+  /** Discriminator for capability type */
+  type: 'contractClasses';
+
+  /**
+   * Which contract classes this applies to:
+   * - '*': Any contract class ID
+   * - Fr[]: Specific contract class IDs
+   */
+  classes: '*' | Fr[];
+
+  /** Can register a contract class artifact in the local PXE. Maps to: registerContractClass */
+  canRegister?: boolean;
+
+  /** Can query contract class metadata. Maps to: getContractClassMetadata */
+  canGetMetadata: boolean;
+}
+
+/**
+ * Granted contract class capability.
+ *
+ * The wallet may reduce the scope (e.g., from '*' to specific class IDs).
+ */
+export interface GrantedContractClassesCapability extends ContractClassesCapability {}
+
+/**
+ * Transaction simulation capability - for simulating transactions and executing utilities.
+ *
+ * Maps to wallet methods:
+ * - simulateTx (when transactions scope specified)
+ * - executeUtility (when utilities scope specified)
+ * - profileTx (when transactions scope specified)
+ *
+ * @example
+ * // Simulate any transaction on specific contracts
+ * \{
+ *   type: 'simulation',
+ *   transactions: \{
+ *     scope: [
+ *       \{ contract: ammAddress, function: '*' \},
+ *       \{ contract: tokenAddress, function: 'transfer' \}
+ *     ]
+ *   \}
+ * \}
+ *
+ * @example
+ * // Simulate any transaction and execute any utility call
+ * \{
+ *   type: 'simulation',
+ *   transactions: \{ scope: '*' \},
+ *   utilities: \{ scope: '*' \}
+ * \}
+ */
+export interface SimulationCapability {
+  /** Discriminator for capability type */
+  type: 'simulation';
+
+  /** Transaction simulation scope. Maps to: simulateTx, profileTx */
+  transactions?: {
+    /**
+     * Which contracts/functions to allow:
+     * - '*': Any transaction
+     * - ContractFunctionPattern[]: Specific contract functions
+     */
+    scope: '*' | ContractFunctionPattern[];
+  };
+
+  /** Utility execution scope (unconstrained calls). Maps to: executeUtility */
+  utilities?: {
+    /**
+     * Which contracts/functions to allow:
+     * - '*': Any utility call
+     * - ContractFunctionPattern[]: Specific contract functions
+     */
+    scope: '*' | ContractFunctionPattern[];
+  };
+}
+
+/**
+ * Granted transaction simulation capability.
+ *
+ * The wallet may reduce the scope (e.g., from '*' to specific patterns).
+ */
+export interface GrantedSimulationCapability extends SimulationCapability {}
+
+/**
+ * Transaction execution capability - for sending transactions.
+ *
+ * Maps to wallet methods:
+ * - sendTx
+ *
+ * Policy enforcement (rate limits, spending limits) should be handled
+ * at the contract level in Aztec, not at the wallet level.
+ *
+ * @example
+ * // Send specific transactions with approval
+ * \{
+ *   type: 'transaction',
+ *   scope: [
+ *     \{ contract: ammAddress, function: 'swap' \},
+ *     \{ contract: ammAddress, function: 'addLiquidity' \}
+ *   ]
+ * \}
+ *
+ * @example
+ * // Send any transaction
+ * \{
+ *   type: 'transaction',
+ *   scope: '*'
+ * \}
+ */
+export interface TransactionCapability {
+  /** Discriminator for capability type */
+  type: 'transaction';
+
+  /**
+   * Which contracts/functions to allow:
+   * - '*': Any transaction
+   * - ContractFunctionPattern[]: Specific patterns
+   */
+  scope: '*' | ContractFunctionPattern[];
+}
+
+/**
+ * Granted transaction execution capability.
+ *
+ * The wallet may reduce the scope (e.g., from '*' to specific patterns).
+ */
+export interface GrantedTransactionCapability extends TransactionCapability {}
+
+/**
+ * Data access capability - for querying private data.
+ *
+ * Maps to wallet methods:
+ * - getAddressBook (when addressBook: true)
+ * - getPrivateEvents (when privateEvents specified)
+ *
+ * @example
+ * // Access address book and events from specific contract
+ * \{
+ *   type: 'data',
+ *   addressBook: true,
+ *   privateEvents: \{
+ *     contracts: [ammAddress],
+ *     events: ['Swap', 'LiquidityAdded']
+ *   \}
+ * \}
+ *
+ * @example
+ * // Access all events from any contract
+ * \{
+ *   type: 'data',
+ *   privateEvents: \{
+ *     contracts: '*',
+ *     events: '*'
+ *   \}
+ * \}
+ */
+export interface DataCapability {
+  /** Discriminator for capability type */
+  type: 'data';
+
+  /** Access to address book. Maps to: getAddressBook */
+  addressBook?: boolean;
+
+  /** Access to private events. Maps to: getPrivateEvents */
+  privateEvents?: {
+    /**
+     * Which contracts to allow event queries from:
+     * - '*': Any contract
+     * - AztecAddress[]: Specific contracts
+     */
+    contracts: '*' | AztecAddress[];
+  };
+}
+
+/**
+ * Granted data access capability.
+ *
+ * The wallet may reduce the scope (e.g., from '*' to specific contracts).
+ */
+export interface GrantedDataCapability extends DataCapability {}
+
+/**
+ * Union type of all capability scopes (app request).
+ *
+ * Capabilities group wallet operations by their security sensitivity
+ * and functional cohesion, making permission requests understandable
+ * to users.
+ */
+export type Capability =
+  | AccountsCapability
+  | ContractsCapability
+  | ContractClassesCapability
+  | SimulationCapability
+  | TransactionCapability
+  | DataCapability;
+
+/**
+ * Union type of all granted capabilities (wallet response).
+ *
+ * The wallet may augment capabilities with additional information:
+ * - AccountsCapability: adds specific accounts granted
+ * - Other capabilities: may reduce scope (e.g., '*' to specific addresses)
+ */
+export type GrantedCapability =
+  | GrantedAccountsCapability
+  | GrantedContractsCapability
+  | GrantedContractClassesCapability
+  | GrantedSimulationCapability
+  | GrantedTransactionCapability
+  | GrantedDataCapability;
+
+/**
+ * Application capability manifest.
+ *
+ * Sent by dApp to declare all operations it needs. This reduces authorization
+ * friction from multiple dialogs to a single comprehensive permission request.
+ *
+ * @example
+ * // DEX application manifest
+ * const manifest: AppCapabilities = \{
+ *   version: CAPABILITY_VERSION,
+ *   metadata: \{
+ *     name: 'MyDEX',
+ *     version: '1.0.0',
+ *     description: 'Decentralized exchange for private token swaps',
+ *     url: 'https://example.com',
+ *     icon: 'https://example.com/icon.png'
+ *   \},
+ *   capabilities: [
+ *     \{
+ *       type: 'accounts',
+ *       canGet: true,
+ *       canCreateAuthWit: true
+ *     \},
+ *     \{
+ *       type: 'contracts',
+ *       contracts: [ammAddress, tokenAAddress, tokenBAddress],
+ *       canRegister: true,
+ *       canGetMetadata: true
+ *     \},
+ *     \{
+ *       type: 'simulation',
+ *       transactions: \{
+ *         scope: [\{ contract: ammAddress, function: '*' \}]
+ *       \}
+ *     \},
+ *     \{
+ *       type: 'transaction',
+ *       scope: [\{ contract: ammAddress, function: 'swap' \}]
+ *     \}
+ *   ]
+ * \};
+ */
+export interface AppCapabilities {
+  /**
+   * Manifest version for forward compatibility.
+   * Currently only '1.0' is supported.
+   */
+  version: typeof CAPABILITY_VERSION;
+
+  /** Application metadata for display in authorization dialogs. */
+  metadata: {
+    /** Human-readable app name */
+    name: string;
+
+    /** App version */
+    version: string;
+
+    /** Optional description of what the app does */
+    description?: string;
+
+    /** Optional website URL */
+    url?: string;
+
+    /** Optional icon URL or data URI */
+    icon?: string;
+  };
+
+  /**
+   * Requested capabilities grouped by scope.
+   */
+  capabilities: Capability[];
+}
+
+/**
+ * Wallet capability response.
+ *
+ * Returned by wallet after user reviews and approves/denies the capability request.
+ *
+ * The wallet can modify requested capabilities:
+ * - Reduce scope (e.g., restrict to specific contracts instead of '*')
+ * - Add information (e.g., specify which accounts are granted)
+ * - Deny capabilities (by omitting them from the `granted` array)
+ *
+ * @example
+ * // App requests
+ * const manifest: AppCapabilities = \{
+ *   version: '1.0',
+ *   metadata: \{ name: 'MyDApp', version: '1.0.0' \},
+ *   capabilities: [
+ *     \{ type: 'accounts', canGet: true \},
+ *     \{ type: 'contracts', contracts: '*', canRegister: true \}
+ *   ]
+ * \};
+ *
+ * // Wallet responds with specific accounts and restricted contracts
+ * const response = await wallet.requestCapabilities(manifest);
+ * console.log(response.granted);
+ * // [
+ * //   \{ type: 'accounts', canGet: true, accounts: [addr1, addr2] \},
+ * //   \{ type: 'contracts', contracts: [specificContract], canRegister: true \}
+ * // ]
+ */
+export interface WalletCapabilities {
+  /** Response version for forward compatibility. */
+  version: typeof CAPABILITY_VERSION;
+
+  /**
+   * Capabilities granted by the wallet.
+   * Capabilities not in this array were implicitly denied.
+   * Empty array means the user denied all capabilities.
+   */
+  granted: GrantedCapability[];
+
+  /** Wallet implementation details. */
+  wallet: {
+    /** Wallet name/implementation */
+    name: string;
+
+    /** Wallet version */
+    version: string;
+  };
+}