@aztec/entrypoints 0.81.0 → 0.82.1-alpha-testnet.1

package/src/default_multi_call_entrypoint.ts

@@ -0,0 +1,109 @@
+import { ProtocolContractAddress } from '@aztec/protocol-contracts';
+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 { EncodedCallsForEntrypoint } from './encoding.js';
+import type { EntrypointInterface, FeeOptions } from './interfaces.js';
+import type { ExecutionPayload } from './payload.js';
+
+/**
+ * Implementation for an entrypoint interface that can execute multiple function calls in a single transaction
+ */
+export class DefaultMultiCallEntrypoint implements EntrypointInterface {
+  constructor(
+    private chainId: number,
+    private version: number,
+    private address: AztecAddress = ProtocolContractAddress.MultiCallEntrypoint,
+  ) {}
+
+  async createTxExecutionRequest(exec: ExecutionPayload, fee: FeeOptions): Promise<TxExecutionRequest> {
+    // Initial request with calls, authWitnesses and capsules
+    const { calls, authWitnesses, capsules, extraHashedArgs } = exec;
+
+    // Get the execution payload for the fee, it includes the calls and potentially authWitnesses
+    const {
+      calls: feeCalls,
+      authWitnesses: feeAuthwitnesses,
+      extraHashedArgs: feeExtraHashedArgs,
+    } = await fee.paymentMethod.getExecutionPayload(fee.gasSettings);
+
+    // Encode the calls, including the fee calls
+    // (since this entrypoint does not distinguish between app and fee calls)
+    const encodedCalls = await EncodedCallsForEntrypoint.fromAppExecution(calls.concat(feeCalls));
+
+    // Obtain the entrypoint hashed args, built from the encoded calls
+    const abi = this.getEntrypointAbi();
+    const entrypointHashedArgs = await HashedValues.fromArgs(encodeArguments(abi, [encodedCalls]));
+
+    // Assemble the tx request
+    const txRequest = TxExecutionRequest.from({
+      firstCallArgsHash: entrypointHashedArgs.hash,
+      origin: this.address,
+      functionSelector: await FunctionSelector.fromNameAndParameters(abi.name, abi.parameters),
+      txContext: new TxContext(this.chainId, this.version, fee.gasSettings),
+      argsOfCalls: [...encodedCalls.hashedArguments, entrypointHashedArgs, ...extraHashedArgs, ...feeExtraHashedArgs],
+      authWitnesses: [...feeAuthwitnesses, ...authWitnesses],
+      capsules,
+    });
+
+    return Promise.resolve(txRequest);
+  }
+
+  private getEntrypointAbi() {
+    return {
+      name: 'entrypoint',
+      isInitializer: false,
+      functionType: 'private',
+      isInternal: false,
+      isStatic: false,
+      parameters: [
+        {
+          name: 'app_payload',
+          type: {
+            kind: 'struct',
+            path: 'authwit::entrypoint::app::AppPayload',
+            fields: [
+              {
+                name: 'function_calls',
+                type: {
+                  kind: 'array',
+                  length: 4,
+                  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::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',
+        },
+      ],
+      returnTypes: [],
+      errorTypes: {},
+    } as FunctionAbi;
+  }
+}

package/src/encoding.ts

@@ -0,0 +1,230 @@
+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;
+
+/* eslint-disable camelcase */
+/** 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;
+};
+/* eslint-enable camelcase */
+
+/** 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,
+    /** The nonce for the payload, used to emit a nullifier identifying the call */
+    public 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 nonce - The nonce for the payload, used to emit a nullifier identifying the call
+   * @returns The encoded calls
+   */
+  static async fromAppExecution(
+    functionCalls: FunctionCall[] | Tuple<FunctionCall, typeof APP_MAX_CALLS>,
+    nonce = 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,
+      nonce,
+    );
+  }
+
+  /**
+   * 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,
+    nonce: Fr,
+  ) {
+    super(encodedFunctionCalls, hashedArguments, generatorIndex, nonce);
+  }
+
+  override toFields(): Fr[] {
+    return [...this.functionCallsToFields(), this.nonce];
+  }
+}
+
+/** Encoded calls for fee payment */
+export class EncodedFeeEntrypointCalls extends EncodedCallsForEntrypoint {
+  #isFeePayer: boolean;
+
+  constructor(
+    encodedFunctionCalls: EncodedFunctionCall[],
+    hashedArguments: HashedValues[],
+    generatorIndex: number,
+    nonce: Fr,
+    isFeePayer: boolean,
+  ) {
+    super(encodedFunctionCalls, hashedArguments, generatorIndex, nonce);
+    this.#isFeePayer = isFeePayer;
+  }
+
+  override toFields(): Fr[] {
+    return [...this.functionCallsToFields(), this.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

@@ -8,3 +8,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,93 @@
+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;
+  /** The nonce to use for the transaction. */
+  nonce?: 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 - 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);
+}