@aztec/entrypoints 0.0.0-test.1 → 0.0.1-fake-ceab37513c

package/src/encoding.ts

@@ -0,0 +1,234 @@
+import { GeneratorIndex } from '@aztec/constants';
+import { padArrayEnd } from '@aztec/foundation/collection';
+import { poseidon2HashWithSeparator } from '@aztec/foundation/crypto';
+import { Fr } from '@aztec/foundation/fields';
+import type { Tuple } from '@aztec/foundation/serialize';
+import { FunctionCall, FunctionType } from '@aztec/stdlib/abi';
+import { HashedValues } from '@aztec/stdlib/tx';
+
+// These must match the values defined in:
+// - noir-projects/aztec-nr/aztec/src/entrypoint/app.nr
+const APP_MAX_CALLS = 4;
+// - and noir-projects/aztec-nr/aztec/src/entrypoint/fee.nr
+const FEE_MAX_CALLS = 2;
+
+/** Encoded function call for an Aztec entrypoint */
+export type EncodedFunctionCall = {
+  /** Arguments hash for the call. */
+  /** This should be the calldata hash `hash([function_selector, ...args])` if `is_public` is true. */
+  args_hash: Fr;
+  /** Selector of the function to call */
+  function_selector: Fr;
+  /** Address of the contract to call */
+  target_address: Fr;
+  /** Whether the function is public or private */
+  is_public: boolean;
+  /** Whether the function can alter state */
+  is_static: boolean;
+};
+
+/** Type that represents function calls ready to be sent to a circuit for execution */
+export type EncodedCalls = {
+  /** Function calls in the expected format (Noir's convention) */
+  encodedFunctionCalls: EncodedFunctionCall[];
+  /** The hashed args for the call, ready to be injected in the execution cache */
+  hashedArguments: HashedValues[];
+};
+
+/**
+ * Entrypoints derive their arguments from the calls that they'll ultimate make.
+ * This utility class helps in creating the payload for the entrypoint by taking into
+ * account how the calls are encoded and hashed.
+ * */
+export abstract class EncodedCallsForEntrypoint implements EncodedCalls {
+  constructor(
+    /** Function calls in the expected format (Noir's convention) */
+    public encodedFunctionCalls: EncodedFunctionCall[],
+    /** The hashed args for the call, ready to be injected in the execution cache */
+    public hashedArguments: HashedValues[],
+    /** The index of the generator to use for hashing */
+    public generatorIndex: number,
+    /**
+     * A nonce to inject into the payload of the transaction. When used with cancellable=true, this nonce will be
+     * used to compute a nullifier that allows cancelling this transaction by submitting a new one with the same nonce
+     * but higher fee. The nullifier ensures only one transaction can succeed.
+     */
+    // eslint-disable-next-line camelcase
+    public tx_nonce: Fr,
+  ) {}
+
+  /* eslint-disable camelcase */
+  /**
+   * The function calls to execute. This uses snake_case naming so that it is compatible with Noir encoding
+   * @internal
+   */
+  get function_calls() {
+    return this.encodedFunctionCalls;
+  }
+  /* eslint-enable camelcase */
+
+  /**
+   * Serializes the payload to an array of fields
+   * @returns The fields of the payload
+   */
+  abstract toFields(): Fr[];
+
+  /**
+   * Hashes the payload
+   * @returns The hash of the payload
+   */
+  hash() {
+    return poseidon2HashWithSeparator(this.toFields(), this.generatorIndex);
+  }
+
+  /** Serializes the function calls to an array of fields. */
+  protected functionCallsToFields() {
+    return this.encodedFunctionCalls.flatMap(call => [
+      call.args_hash,
+      call.function_selector,
+      call.target_address,
+      new Fr(call.is_public),
+      new Fr(call.is_static),
+    ]);
+  }
+
+  /**
+   * Encodes a set of function calls for a dapp entrypoint
+   * @param functionCalls - The function calls to execute
+   * @returns The encoded calls
+   */
+  static async fromFunctionCalls(functionCalls: FunctionCall[]) {
+    const encoded = await encode(functionCalls);
+    return new EncodedAppEntrypointCalls(encoded.encodedFunctionCalls, encoded.hashedArguments, 0, Fr.random());
+  }
+
+  /**
+   * Encodes the functions for the app-portion of a transaction from a set of function calls and a nonce
+   * @param functionCalls - The function calls to execute
+   * @param txNonce - A nonce used to enable transaction cancellation when cancellable=true. Transactions with the same
+   * nonce can be replaced by submitting a new one with a higher fee.
+   * @returns The encoded calls
+   */
+  static async fromAppExecution(
+    functionCalls: FunctionCall[] | Tuple<FunctionCall, typeof APP_MAX_CALLS>,
+    txNonce = Fr.random(),
+  ) {
+    if (functionCalls.length > APP_MAX_CALLS) {
+      throw new Error(`Expected at most ${APP_MAX_CALLS} function calls, got ${functionCalls.length}`);
+    }
+    const paddedCalls = padArrayEnd(functionCalls, FunctionCall.empty(), APP_MAX_CALLS);
+    const encoded = await encode(paddedCalls);
+    return new EncodedAppEntrypointCalls(
+      encoded.encodedFunctionCalls,
+      encoded.hashedArguments,
+      GeneratorIndex.SIGNATURE_PAYLOAD,
+      txNonce,
+    );
+  }
+
+  /**
+   * Creates an encoded set of functions to pay the fee for a transaction
+   * @param functionCalls - The calls generated by the payment method
+   * @param isFeePayer - Whether the sender should be appointed as fee payer
+   * @returns The encoded calls
+   */
+  static async fromFeeCalls(
+    functionCalls: FunctionCall[] | Tuple<FunctionCall, typeof FEE_MAX_CALLS>,
+    isFeePayer: boolean,
+  ) {
+    const paddedCalls = padArrayEnd(functionCalls, FunctionCall.empty(), FEE_MAX_CALLS);
+    const encoded = await encode(paddedCalls);
+    return new EncodedFeeEntrypointCalls(
+      encoded.encodedFunctionCalls,
+      encoded.hashedArguments,
+      GeneratorIndex.FEE_PAYLOAD,
+      Fr.random(),
+      isFeePayer,
+    );
+  }
+}
+
+/** Encoded calls for app phase execution. */
+export class EncodedAppEntrypointCalls extends EncodedCallsForEntrypoint {
+  constructor(
+    encodedFunctionCalls: EncodedFunctionCall[],
+    hashedArguments: HashedValues[],
+    generatorIndex: number,
+    txNonce: Fr,
+  ) {
+    super(encodedFunctionCalls, hashedArguments, generatorIndex, txNonce);
+  }
+
+  override toFields(): Fr[] {
+    return [...this.functionCallsToFields(), this.tx_nonce];
+  }
+}
+
+/** Encoded calls for fee payment */
+export class EncodedFeeEntrypointCalls extends EncodedCallsForEntrypoint {
+  #isFeePayer: boolean;
+
+  constructor(
+    encodedFunctionCalls: EncodedFunctionCall[],
+    hashedArguments: HashedValues[],
+    generatorIndex: number,
+    txNonce: Fr,
+    isFeePayer: boolean,
+  ) {
+    super(encodedFunctionCalls, hashedArguments, generatorIndex, txNonce);
+    this.#isFeePayer = isFeePayer;
+  }
+
+  override toFields(): Fr[] {
+    return [...this.functionCallsToFields(), this.tx_nonce, new Fr(this.#isFeePayer)];
+  }
+
+  /* eslint-disable camelcase */
+  /** Whether the sender should be appointed as fee payer. */
+  get is_fee_payer() {
+    return this.#isFeePayer;
+  }
+  /* eslint-enable camelcase */
+}
+
+/**
+ * Computes a hash of a combined set of app and fee calls.
+ * @param appCalls - A set of app calls.
+ * @param feeCalls - A set of calls used to pay fees.
+ * @returns A hash of a combined call set.
+ */
+export async function computeCombinedPayloadHash(
+  appPayload: EncodedAppEntrypointCalls,
+  feePayload: EncodedFeeEntrypointCalls,
+): Promise<Fr> {
+  return poseidon2HashWithSeparator(
+    [await appPayload.hash(), await feePayload.hash()],
+    GeneratorIndex.COMBINED_PAYLOAD,
+  );
+}
+
+/** Encodes FunctionCalls for execution, following Noir's convention */
+export async function encode(calls: FunctionCall[]): Promise<EncodedCalls> {
+  const hashedArguments: HashedValues[] = [];
+  for (const call of calls) {
+    const hashed =
+      call.type === FunctionType.PUBLIC
+        ? await HashedValues.fromCalldata([call.selector.toField(), ...call.args])
+        : await HashedValues.fromArgs(call.args);
+    hashedArguments.push(hashed);
+  }
+
+  /* eslint-disable camelcase */
+  const encodedFunctionCalls: EncodedFunctionCall[] = calls.map((call, index) => ({
+    args_hash: hashedArguments[index].hash,
+    function_selector: call.selector.toField(),
+    target_address: call.to.toField(),
+    is_public: call.type == FunctionType.PUBLIC,
+    is_static: call.isStatic,
+  }));
+
+  return {
+    encodedFunctionCalls,
+    hashedArguments,
+  };
+}

package/src/index.ts

@@ -7,4 +7,7 @@
  */
 
 export * from './account_entrypoint.js';
-export * from './dapp_entrypoint.js';
+export * from './interfaces.js';
+export * from './default_entrypoint.js';
+export * from './encoding.js';
+export * from './default_multi_call_entrypoint.js';

package/src/interfaces.ts

@@ -0,0 +1,97 @@
+import type { Fr } from '@aztec/foundation/fields';
+import type { FieldsOf } from '@aztec/foundation/types';
+import type { AuthWitness } from '@aztec/stdlib/auth-witness';
+import type { AztecAddress } from '@aztec/stdlib/aztec-address';
+import type { GasSettings } from '@aztec/stdlib/gas';
+import type { TxExecutionRequest } from '@aztec/stdlib/tx';
+
+import type { ExecutionPayload } from './payload.js';
+
+/**
+ * General options for the tx execution.
+ */
+export type TxExecutionOptions = {
+  /** Whether the transaction can be cancelled. */
+  cancellable?: boolean;
+  /**
+   * A nonce to inject into the app payload of the transaction. When used with cancellable=true, this nonce will be
+   * used to compute a nullifier that allows cancelling this transaction by submitting a new one with the same nonce
+   * but higher fee. The nullifier ensures only one transaction can succeed.
+   */
+  txNonce?: Fr;
+};
+
+/**
+ * Creates transaction execution requests out of a set of function calls, a fee payment method and
+ * general options for the transaction
+ */
+export interface EntrypointInterface {
+  /**
+   * Generates an execution request out of set of function calls.
+   * @param exec - The execution intents to be run.
+   * @param fee - The fee options for the transaction.
+   * @param options - Transaction nonce and whether the transaction is cancellable.
+   * @returns The authenticated transaction execution request.
+   */
+  createTxExecutionRequest(
+    exec: ExecutionPayload,
+    fee: FeeOptions,
+    options: TxExecutionOptions,
+  ): Promise<TxExecutionRequest>;
+}
+
+/** Creates authorization witnesses. */
+export interface AuthWitnessProvider {
+  /**
+   * Computes an authentication witness from either a message hash
+   * @param messageHash - The message hash to approve
+   * @returns The authentication witness
+   */
+  createAuthWit(messageHash: Fr | Buffer): Promise<AuthWitness>;
+}
+
+/**
+ * Holds information about how the fee for a transaction is to be paid.
+ */
+export interface FeePaymentMethod {
+  /** The asset used to pay the fee. */
+  getAsset(): Promise<AztecAddress>;
+  /**
+   * Returns the data to be added to the final execution request
+   * to pay the fee in the given asset
+   * @param gasSettings - The gas limits and max fees.
+   * @returns The function calls to pay the fee.
+   */
+  getExecutionPayload(gasSettings: GasSettings): Promise<ExecutionPayload>;
+  /**
+   * The expected fee payer for this tx.
+   * @param gasSettings - The gas limits and max fees.
+   */
+  getFeePayer(gasSettings: GasSettings): Promise<AztecAddress>;
+}
+
+/**
+ * Fee payment options for a transaction.
+ */
+export type FeeOptions = {
+  /** The fee payment method to use */
+  paymentMethod: FeePaymentMethod;
+  /** The gas settings */
+  gasSettings: GasSettings;
+};
+
+// docs:start:user_fee_options
+/** Fee options as set by a user. */
+export type UserFeeOptions = {
+  /** The fee payment method to use */
+  paymentMethod?: FeePaymentMethod;
+  /** The gas settings */
+  gasSettings?: Partial<FieldsOf<GasSettings>>;
+  /** Percentage to pad the base fee by, if empty, defaults to 0.5 */
+  baseFeePadding?: number;
+  /** Whether to run an initial simulation of the tx with high gas limit to figure out actual gas settings. */
+  estimateGas?: boolean;
+  /** Percentage to pad the estimated gas limits by, if empty, defaults to 0.1. Only relevant if estimateGas is set. */
+  estimatedGasPadding?: number;
+};
+// docs:end:user_fee_options

package/src/payload.ts

@@ -0,0 +1,35 @@
+import { FunctionCall } from '@aztec/stdlib/abi';
+import type { AuthWitness } from '@aztec/stdlib/auth-witness';
+import { Capsule, HashedValues } from '@aztec/stdlib/tx';
+
+/**
+ * Represents data necessary to perform an action in the network successfully.
+ * This class can be considered Aztec's "minimal execution unit".
+ * */
+export class ExecutionPayload {
+  public constructor(
+    /** The function calls to be executed. */
+    public calls: FunctionCall[],
+    /** Any transient auth witnesses needed for this execution */
+    public authWitnesses: AuthWitness[],
+    /** Data passed through an oracle for this execution. */
+    public capsules: Capsule[],
+    /** Extra hashed values to be injected in the execution cache */
+    public extraHashedArgs: HashedValues[] = [],
+  ) {}
+
+  static empty() {
+    return new ExecutionPayload([], [], []);
+  }
+}
+
+/**
+ * Merges an array ExecutionPayloads combining their calls, authWitnesses, capsules and extraArgHashes.
+ */
+export function mergeExecutionPayloads(requests: ExecutionPayload[]): ExecutionPayload {
+  const calls = requests.map(r => r.calls).flat();
+  const combinedAuthWitnesses = requests.map(r => r.authWitnesses ?? []).flat();
+  const combinedCapsules = requests.map(r => r.capsules ?? []).flat();
+  const combinedextraHashedArgs = requests.map(r => r.extraHashedArgs ?? []).flat();
+  return new ExecutionPayload(calls, combinedAuthWitnesses, combinedCapsules, combinedextraHashedArgs);
+}

package/dest/dapp_entrypoint.d.ts

@@ -1,19 +0,0 @@
-import type { AuthWitnessProvider } from '@aztec/aztec.js/account';
-import { type EntrypointInterface, type ExecutionRequestInit } from '@aztec/aztec.js/entrypoint';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { TxExecutionRequest } from '@aztec/stdlib/tx';
-/**
- * Implementation for an entrypoint interface that follows the default entrypoint signature
- * for an account, which accepts an AppPayload and a FeePayload as defined in noir-libs/aztec-noir/src/entrypoint module
- */
-export declare class DefaultDappEntrypoint implements EntrypointInterface {
-    private userAddress;
-    private userAuthWitnessProvider;
-    private dappEntrypointAddress;
-    private chainId;
-    private version;
-    constructor(userAddress: AztecAddress, userAuthWitnessProvider: AuthWitnessProvider, dappEntrypointAddress: AztecAddress, chainId?: number, version?: number);
-    createTxExecutionRequest(exec: ExecutionRequestInit): Promise<TxExecutionRequest>;
-    private getEntrypointAbi;
-}
-//# sourceMappingURL=dapp_entrypoint.d.ts.map

package/dest/dapp_entrypoint.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dapp_entrypoint.d.ts","sourceRoot":"","sources":["../src/dapp_entrypoint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,KAAK,mBAAmB,EAAqB,KAAK,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAEpH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAA2B,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI/E;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,mBAAmB;IAE7D,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,uBAAuB;IAC/B,OAAO,CAAC,qBAAqB;IAC7B,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,OAAO;gBAJP,WAAW,EAAE,YAAY,EACzB,uBAAuB,EAAE,mBAAmB,EAC5C,qBAAqB,EAAE,YAAY,EACnC,OAAO,GAAE,MAAyB,EAClC,OAAO,GAAE,MAAwB;IAGrC,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAqCvF,OAAO,CAAC,gBAAgB;CAiEzB"}

package/src/dapp_entrypoint.ts

@@ -1,125 +0,0 @@
-import { Fr, computeAuthWitMessageHash, computeInnerAuthWitHash } from '@aztec/aztec.js';
-import type { AuthWitnessProvider } from '@aztec/aztec.js/account';
-import { type EntrypointInterface, EntrypointPayload, type ExecutionRequestInit } from '@aztec/aztec.js/entrypoint';
-import { type FunctionAbi, FunctionSelector, encodeArguments } from '@aztec/stdlib/abi';
-import type { AztecAddress } from '@aztec/stdlib/aztec-address';
-import { HashedValues, TxContext, TxExecutionRequest } from '@aztec/stdlib/tx';
-
-import { DEFAULT_CHAIN_ID, DEFAULT_VERSION } from './constants.js';
-
-/**
- * Implementation for an entrypoint interface that follows the default entrypoint signature
- * for an account, which accepts an AppPayload and a FeePayload as defined in noir-libs/aztec-noir/src/entrypoint module
- */
-export class DefaultDappEntrypoint implements EntrypointInterface {
-  constructor(
-    private userAddress: AztecAddress,
-    private userAuthWitnessProvider: AuthWitnessProvider,
-    private dappEntrypointAddress: AztecAddress,
-    private chainId: number = DEFAULT_CHAIN_ID,
-    private version: number = DEFAULT_VERSION,
-  ) {}
-
-  async createTxExecutionRequest(exec: ExecutionRequestInit): Promise<TxExecutionRequest> {
-    const { calls, fee, capsules = [] } = exec;
-    if (calls.length !== 1) {
-      throw new Error(`Expected exactly 1 function call, got ${calls.length}`);
-    }
-
-    const payload = await EntrypointPayload.fromFunctionCalls(calls);
-
-    const abi = this.getEntrypointAbi();
-    const entrypointHashedArgs = await HashedValues.fromValues(encodeArguments(abi, [payload, this.userAddress]));
-    const functionSelector = await FunctionSelector.fromNameAndParameters(abi.name, abi.parameters);
-    // Default msg_sender for entrypoints is now Fr.max_value rather than 0 addr (see #7190 & #7404)
-    const innerHash = await computeInnerAuthWitHash([
-      Fr.MAX_FIELD_VALUE,
-      functionSelector.toField(),
-      entrypointHashedArgs.hash,
-    ]);
-    const outerHash = await computeAuthWitMessageHash(
-      { consumer: this.dappEntrypointAddress, innerHash },
-      { chainId: new Fr(this.chainId), version: new Fr(this.version) },
-    );
-
-    const authWitness = await this.userAuthWitnessProvider.createAuthWit(outerHash);
-
-    const txRequest = TxExecutionRequest.from({
-      firstCallArgsHash: entrypointHashedArgs.hash,
-      origin: this.dappEntrypointAddress,
-      functionSelector,
-      txContext: new TxContext(this.chainId, this.version, fee.gasSettings),
-      argsOfCalls: [...payload.hashedArguments, entrypointHashedArgs],
-      authWitnesses: [authWitness],
-      capsules,
-    });
-
-    return txRequest;
-  }
-
-  private getEntrypointAbi() {
-    return {
-      name: 'entrypoint',
-      isInitializer: false,
-      functionType: 'private',
-      isInternal: false,
-      isStatic: false,
-      parameters: [
-        {
-          name: 'payload',
-          type: {
-            kind: 'struct',
-            path: 'dapp_payload::DAppPayload',
-            fields: [
-              {
-                name: 'function_calls',
-                type: {
-                  kind: 'array',
-                  length: 1,
-                  type: {
-                    kind: 'struct',
-                    path: 'authwit::entrypoint::function_call::FunctionCall',
-                    fields: [
-                      { name: 'args_hash', type: { kind: 'field' } },
-                      {
-                        name: 'function_selector',
-                        type: {
-                          kind: 'struct',
-                          path: 'authwit::aztec::protocol_types::abis::function_selector::FunctionSelector',
-                          fields: [{ name: 'inner', type: { kind: 'integer', sign: 'unsigned', width: 32 } }],
-                        },
-                      },
-                      {
-                        name: 'target_address',
-                        type: {
-                          kind: 'struct',
-                          path: 'authwit::aztec::protocol_types::address::aztec_address::AztecAddress',
-                          fields: [{ name: 'inner', type: { kind: 'field' } }],
-                        },
-                      },
-                      { name: 'is_public', type: { kind: 'boolean' } },
-                      { name: 'is_static', type: { kind: 'boolean' } },
-                    ],
-                  },
-                },
-              },
-              { name: 'nonce', type: { kind: 'field' } },
-            ],
-          },
-          visibility: 'public',
-        },
-        {
-          name: 'user_address',
-          type: {
-            kind: 'struct',
-            path: 'authwit::aztec::protocol_types::address::aztec_address::AztecAddress',
-            fields: [{ name: 'inner', type: { kind: 'field' } }],
-          },
-          visibility: 'public',
-        },
-      ],
-      returnTypes: [],
-      errorTypes: {},
-    } as FunctionAbi;
-  }
-}