@aztec/aztec.js 0.1.0-alpha13

package/src/contract/checker.test.ts

@@ -0,0 +1,177 @@
+import { abiChecker } from './checker.js';
+
+describe('abiChecker', () => {
+  let abi: any;
+
+  it('should throw an error if it has no functions', () => {
+    abi = {
+      name: 'TEST_ABI',
+    };
+    expect(() => abiChecker(abi)).toThrowError('ABI has no functions');
+    abi = {
+      name: 'TEST_ABI',
+      functions: [],
+    };
+    expect(() => abiChecker(abi)).toThrowError('ABI has no functions');
+  });
+
+  it('should error if ABI has no names', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [{ bytecode: '0af', parameters: [{ type: { kind: 'test' } }] }],
+    };
+    expect(() => abiChecker(abi)).toThrowError('ABI function has no name');
+  });
+
+  it('should error if ABI function has unrecognised type', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'Function name',
+          bytecode: '0af',
+          parameters: [{ type: { kind: 'test' } }],
+        },
+      ],
+    };
+    expect(() => abiChecker(abi)).toThrowError('ABI function parameter has an unrecognised type');
+  });
+
+  it('should error if integer is incorrectly formed', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [{ type: { kind: 'integer', sign: 5 } }],
+        },
+      ],
+    };
+    expect(() => abiChecker(abi)).toThrowError('Unrecognised attribute on type integer');
+  });
+
+  it('should error if string is incorrectly formed', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [{ type: { kind: 'string', sign: 5, additionalParam: true } }],
+        },
+      ],
+    };
+    expect(() => abiChecker(abi)).toThrowError('Unrecognised attribute on type string');
+  });
+
+  it('should error if struct is incorrectly formed', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [
+            {
+              type: {
+                kind: 'struct',
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(() => abiChecker(abi)).toThrowError('Unrecognised attribute on type struct');
+  });
+
+  it('should error if array is incorrectly formed', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [
+            {
+              type: {
+                kind: 'array',
+                length: 5,
+                type: {
+                  kind: 'array',
+                  length: '5',
+                  type: {
+                    sign: 'value',
+                    width: 5,
+                    kind: 'integer',
+                  },
+                },
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(() => abiChecker(abi)).toThrowError('ABI function parameter has an incorrectly formed array');
+  });
+
+  it('valid matrix should pass checker', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [
+            {
+              type: {
+                kind: 'array',
+                length: 5,
+                type: {
+                  kind: 'array',
+                  length: 5,
+                  type: {
+                    sign: 'value',
+                    width: 5,
+                    kind: 'integer',
+                  },
+                },
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(abiChecker(abi)).toBe(true);
+  });
+
+  it('valid struct should pass checker', () => {
+    abi = {
+      name: 'TEST_ABI',
+      functions: [
+        {
+          name: 'constructor',
+          bytecode: '0af',
+          parameters: [
+            {
+              type: {
+                kind: 'struct',
+                fields: [
+                  {
+                    name: 'name',
+                    type: {
+                      sign: 'value',
+                      width: 5,
+                      kind: 'integer',
+                    },
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+    };
+    expect(abiChecker(abi)).toBe(true);
+  });
+});

package/src/contract/checker.ts

@@ -0,0 +1,117 @@
+import { ABIType, BasicType, ContractAbi, StructType } from '@aztec/foundation/abi';
+
+/**
+ * Represents a type derived from input type T with the 'kind' property removed.
+ * Useful when checking attributes of a specific kind and validating their types.
+ */
+type TypeWithoutKind<T> = Omit<{ [key in keyof T]: any }, 'kind'>;
+
+/**
+ * Validates the given ContractAbi object by checking its functions and their parameters.
+ * Ensures that the ABI has at least one function, a constructor, valid bytecode, and correct parameter types.
+ * Throws an error if any inconsistency is detected during the validation process.
+ *
+ * @param abi - The ContractAbi object to be validated.
+ * @returns A boolean value indicating whether the ABI is valid or not.
+ */
+export function abiChecker(abi: ContractAbi) {
+  if (!abi.functions || abi.functions.length === 0) {
+    throw new Error('ABI has no functions');
+  }
+
+  abi.functions.forEach(func => {
+    if (!('name' in func && typeof func.name === 'string' && func.name.length > 0)) {
+      throw new Error('ABI function has no name');
+    }
+
+    // TODO: implement a better check for bytecode (right now only checks if it's > 0)
+    if (!('bytecode' in func && typeof func.bytecode === 'string' && func.bytecode.length > 0)) {
+      throw new Error('ABI function parameter has incorrect bytecode');
+    }
+
+    func.parameters.forEach(param => {
+      if (!param.type) {
+        throw new Error('ABI function parameter has no type');
+      }
+
+      abiParameterTypeChecker(param.type);
+    });
+  });
+
+  // TODO: implement a better check for constructor (right now only checks if it has it or not)
+  if (!abi.functions.find(func => func.name === 'constructor')) {
+    throw new Error('ABI has no constructor');
+  }
+
+  return true;
+}
+
+/**
+ * Validates the ABI function parameter's type by checking its kind and attributes.
+ * Throws an error if the type has an unrecognized kind or incorrectly formed attributes.
+ * Additionally, checks nested types for array and struct kinds.
+ *
+ * @param type - The ABIType object representing the type of the ABI function parameter.
+ * @returns A boolean value indicating whether the type is valid or not.
+ */
+function abiParameterTypeChecker(type: ABIType): boolean {
+  switch (type.kind) {
+    case 'field':
+    case 'boolean':
+      return checkAttributes(type, {});
+    case 'integer':
+      return checkAttributes(type, { sign: 'string', width: 'number' });
+    case 'string':
+      return checkAttributes(type, { length: 'number' });
+    case 'array':
+      return checkAttributes(type, { length: 'number', type: 'object' }) && abiParameterTypeChecker(type.type);
+    case 'struct':
+      return checkAttributes(type, { fields: 'object' }) && checkStruct(type);
+    default:
+      throw new Error('ABI function parameter has an unrecognised type');
+  }
+}
+
+/**
+ * Check if the structure of the ABIType 'struct' is valid by ensuring field names are strings
+ * and their type attribute passes the abiParameterTypeChecker. Returns true on successful validation,
+ * otherwise throws an error providing insight into the incorrect formation in the struct.
+ *
+ * @param type - The StructType object containing an array of fields to validate.
+ * @returns A boolean value indicating successful validation of the struct's fields.
+ */
+function checkStruct(type: StructType) {
+  return type.fields.reduce((acc, field) => {
+    if (!('name' in field && typeof field.name === 'string')) {
+      throw new Error('ABI function parameter has an incorrectly formed struct');
+    }
+    return acc && abiParameterTypeChecker(field.type);
+  }, true);
+}
+
+/**
+ * Check if a provided ABI type has the correct attributes and their associated types.
+ * This function compares the given 'type' object's keys with the expected attribute types
+ * specified in 'incompleteAttributes', as well as the required 'kind' property.
+ * Throws an error if there are any unrecognised attributes or incorrect attribute types.
+ *
+ * @param type - The ABI type object to be checked for correct attributes.
+ * @param incompleteAttributes - An object representing the expected attribute types without the 'kind' property.
+ * @returns Returns true if the provided ABI type has the correct attributes and their associated types, otherwise throws an error.
+ */
+function checkAttributes<T extends BasicType<string>>(type: T, incompleteAttributes: TypeWithoutKind<T>) {
+  const typeKeys = Object.keys(type);
+  const attributes = { ...incompleteAttributes, kind: 'string' };
+
+  if (typeKeys.length !== Object.keys(attributes).length) {
+    throw new Error(`Unrecognised attribute on type ${type.kind}`);
+  }
+
+  typeKeys.forEach(element => {
+    if (!(element in type && typeof (type as any)[element] === (attributes as any)[element])) {
+      throw new Error(`ABI function parameter has an incorrectly formed ${type.kind}`);
+    }
+  });
+
+  return true;
+}

package/src/contract/contract.test.ts

@@ -0,0 +1,160 @@
+import { AztecAddress, DeployedContract, EthAddress, NodeInfo, Tx, TxHash, TxReceipt } from '@aztec/aztec-rpc';
+import { MockProxy, mock } from 'jest-mock-extended';
+
+import { ABIParameterVisibility, ContractAbi, FunctionType } from '@aztec/foundation/abi';
+import { randomBytes } from '@aztec/foundation/crypto';
+import { TxExecutionRequest } from '@aztec/types';
+import { Wallet } from '../aztec_rpc_client/wallet.js';
+import { Contract } from './contract.js';
+
+describe('Contract Class', () => {
+  let wallet: MockProxy<Wallet>;
+
+  const contractAddress = AztecAddress.random();
+  const account = AztecAddress.random();
+
+  const mockTx = { type: 'Tx' } as any as Tx;
+  const mockTxRequest = { type: 'TxRequest' } as any as TxExecutionRequest;
+  const mockTxHash = { type: 'TxHash' } as any as TxHash;
+  const mockTxReceipt = { type: 'TxReceipt' } as any as TxReceipt;
+  const mockViewResultValue = 1;
+  const mockNodeInfo: NodeInfo = { version: 1, chainId: 2 };
+
+  const defaultAbi: ContractAbi = {
+    name: 'FooContract',
+    functions: [
+      {
+        name: 'bar',
+        functionType: FunctionType.SECRET,
+        parameters: [
+          {
+            name: 'value',
+            type: {
+              kind: 'field',
+            },
+            visibility: ABIParameterVisibility.PUBLIC,
+          },
+          {
+            name: 'value',
+            type: {
+              kind: 'field',
+            },
+            visibility: ABIParameterVisibility.SECRET,
+          },
+        ],
+        returnTypes: [],
+        bytecode: '0af',
+      },
+      {
+        name: 'baz',
+        functionType: FunctionType.OPEN,
+        parameters: [],
+        returnTypes: [],
+        bytecode: '0be',
+      },
+      {
+        name: 'qux',
+        functionType: FunctionType.UNCONSTRAINED,
+        parameters: [
+          {
+            name: 'value',
+            type: {
+              kind: 'field',
+            },
+            visibility: ABIParameterVisibility.PUBLIC,
+          },
+        ],
+        returnTypes: [
+          {
+            kind: 'integer',
+            sign: '',
+            width: 32,
+          },
+        ],
+        bytecode: '0cd',
+      },
+    ],
+  };
+
+  const randomContractAbi = (): ContractAbi => ({
+    name: randomBytes(4).toString('hex'),
+    functions: [],
+  });
+
+  const randomDeployContract = (): DeployedContract => ({
+    abi: randomContractAbi(),
+    address: AztecAddress.random(),
+    portalContract: EthAddress.random(),
+  });
+
+  beforeEach(() => {
+    wallet = mock<Wallet>();
+    wallet.createAuthenticatedTxRequest.mockResolvedValue(mockTxRequest);
+    wallet.sendTx.mockResolvedValue(mockTxHash);
+    wallet.viewTx.mockResolvedValue(mockViewResultValue);
+    wallet.getTxReceipt.mockResolvedValue(mockTxReceipt);
+    wallet.getNodeInfo.mockResolvedValue(mockNodeInfo);
+    wallet.simulateTx.mockResolvedValue(mockTx);
+  });
+
+  it('should create and send a contract method tx', async () => {
+    const fooContract = new Contract(contractAddress, defaultAbi, wallet);
+    const param0 = 12;
+    const param1 = 345n;
+    const sentTx = fooContract.methods.bar(param0, param1).send({
+      from: account,
+    });
+    const txHash = await sentTx.getTxHash();
+    const receipt = await sentTx.getReceipt();
+
+    expect(txHash).toBe(mockTxHash);
+    expect(receipt).toBe(mockTxReceipt);
+    expect(wallet.createAuthenticatedTxRequest).toHaveBeenCalledTimes(1);
+    expect(wallet.sendTx).toHaveBeenCalledTimes(1);
+    expect(wallet.sendTx).toHaveBeenCalledWith(mockTx);
+  });
+
+  it('should call view on an unconstrained function', async () => {
+    const fooContract = new Contract(contractAddress, defaultAbi, wallet);
+    const result = await fooContract.methods.qux(123n).view({
+      from: account,
+    });
+    expect(wallet.viewTx).toHaveBeenCalledTimes(1);
+    expect(wallet.viewTx).toHaveBeenCalledWith('qux', [123n], contractAddress, account);
+    expect(result).toBe(mockViewResultValue);
+  });
+
+  it('should not call send on an unconstrained function', () => {
+    const fooContract = new Contract(contractAddress, defaultAbi, wallet);
+    expect(() =>
+      fooContract.methods.qux().send({
+        from: account,
+      }),
+    ).toThrow();
+  });
+
+  it('should not call view on a secret or open function', () => {
+    const fooContract = new Contract(contractAddress, defaultAbi, wallet);
+    expect(() => fooContract.methods.bar().view()).toThrow();
+    expect(() => fooContract.methods.baz().view()).toThrow();
+  });
+
+  it('should add contract and dependencies to aztec rpc', async () => {
+    const entry = randomDeployContract();
+    const contract = new Contract(entry.address, entry.abi, wallet);
+
+    {
+      await contract.attach(entry.portalContract);
+      expect(wallet.addContracts).toHaveBeenCalledTimes(1);
+      expect(wallet.addContracts).toHaveBeenCalledWith([entry]);
+      wallet.addContracts.mockClear();
+    }
+
+    {
+      const dependencies = [randomDeployContract(), randomDeployContract()];
+      await contract.attach(entry.portalContract, dependencies);
+      expect(wallet.addContracts).toHaveBeenCalledTimes(1);
+      expect(wallet.addContracts).toHaveBeenCalledWith([entry, ...dependencies]);
+    }
+  });
+});

package/src/contract/contract.ts

@@ -0,0 +1,80 @@
+import { DeployedContract, generateFunctionSelector } from '@aztec/aztec-rpc';
+import { ContractAbi, FunctionAbi } from '@aztec/foundation/abi';
+import { AztecAddress } from '@aztec/foundation/aztec-address';
+import { EthAddress } from '@aztec/foundation/eth-address';
+import { Wallet } from '../aztec_rpc_client/wallet.js';
+import { ContractFunctionInteraction } from './contract_function_interaction.js';
+
+/**
+ * Type representing a contract method that returns a ContractFunctionInteraction instance
+ * and has a readonly 'selector' property of type Buffer. Takes any number of arguments.
+ */
+type ContractMethod = ((...args: any[]) => ContractFunctionInteraction) & {
+  /**
+   * The unique identifier for a contract function in bytecode.
+   */
+  readonly selector: Buffer;
+};
+
+/**
+ * The Contract class represents a contract and provides utility methods for interacting with it.
+ * It enables the creation of ContractFunctionInteraction instances for each function in the contract's ABI,
+ * allowing users to call or send transactions to these functions. Additionally, the Contract class can be used
+ * to attach the contract instance to a deployed contract on-chain through the AztecRPCClient, which facilitates
+ * interaction with Aztec's privacy protocol.
+ */
+export class Contract {
+  /**
+   * An object containing contract methods mapped to their respective names.
+   */
+  public methods: { [name: string]: ContractMethod } = {};
+
+  constructor(
+    /**
+     * The deployed contract's address.
+     */
+    public readonly address: AztecAddress,
+    /**
+     * The Application Binary Interface for the contract.
+     */
+    public readonly abi: ContractAbi,
+    /**
+     * The wallet.
+     */
+    private wallet: Wallet,
+  ) {
+    abi.functions.forEach((f: FunctionAbi) => {
+      const interactionFunction = (...args: any[]) => {
+        return new ContractFunctionInteraction(this.wallet, this.address!, f, args);
+      };
+
+      this.methods[f.name] = Object.assign(interactionFunction, {
+        /**
+         * A getter for users to fetch the function selector.
+         * @returns Selector of the function.
+         */
+        get selector() {
+          return generateFunctionSelector(f.name, f.parameters);
+        },
+      });
+    });
+  }
+
+  /**
+   * Attach the current contract instance to a portal contract and optionally add its dependencies.
+   * The function will return a promise that resolves when all contracts have been added to the AztecRPCClient.
+   * This is useful when you need to interact with a deployed contract that has multiple nested contracts.
+   *
+   * @param portalContract - The Ethereum address of the portal contract.
+   * @param dependencies - An optional array of additional DeployedContract instances to be attached.
+   * @returns A promise that resolves when all contracts are successfully added to the AztecRPCClient.
+   */
+  attach(portalContract: EthAddress, dependencies: DeployedContract[] = []) {
+    const deployedContract: DeployedContract = {
+      abi: this.abi,
+      address: this.address,
+      portalContract,
+    };
+    return this.wallet.addContracts([deployedContract, ...dependencies]);
+  }
+}

package/src/contract/contract_function_interaction.ts

@@ -0,0 +1,141 @@
+import { encodeArguments } from '@aztec/acir-simulator';
+import { generateFunctionSelector, Tx } from '@aztec/aztec-rpc';
+import { AztecAddress, Fr, FunctionData, TxContext } from '@aztec/circuits.js';
+import { FunctionAbi, FunctionType } from '@aztec/foundation/abi';
+import { ExecutionRequest, TxExecutionRequest } from '@aztec/types';
+import { Wallet } from '../aztec_rpc_client/wallet.js';
+import { SentTx } from './sent_tx.js';
+
+/**
+ * Represents options for calling a (constrained) function in a contract.
+ * Allows the user to specify the sender address and nonce for a transaction.
+ */
+export interface SendMethodOptions {
+  /**
+   * Sender's address initiating the transaction.
+   */
+  from?: AztecAddress;
+  /**
+   * The nonce representing the order of transactions sent by the address.
+   */
+  nonce?: Fr;
+}
+
+/**
+ * Represents the options for a view method in a contract function interaction.
+ * Allows specifying the address from which the view method should be called.
+ */
+export interface ViewMethodOptions {
+  /**
+   * The sender's Aztec address.
+   */
+  from?: AztecAddress;
+}
+
+/**
+ * This is the class that is returned when calling e.g. `contract.methods.myMethod(arg0, arg1)`.
+ * It contains available interactions one can call on a method.
+ */
+export class ContractFunctionInteraction {
+  protected tx?: Tx;
+  protected txRequest?: TxExecutionRequest;
+
+  constructor(
+    protected wallet: Wallet,
+    protected contractAddress: AztecAddress,
+    protected functionDao: FunctionAbi,
+    protected args: any[],
+  ) {}
+
+  /**
+   * Create an Aztec transaction instance by combining the transaction request and its signature.
+   * This function will first check if a signature exists, and if not, it will call the `sign` method
+   * to obtain the signature before creating the transaction. Throws an error if the function is
+   * of unconstrained type or if the transaction request and signature are missing.
+   *
+   * @param options - An optional object containing additional configuration for the transaction.
+   * @returns A Promise that resolves to a transaction instance.
+   */
+  public async create(options: SendMethodOptions = {}): Promise<TxExecutionRequest> {
+    if (this.functionDao.functionType === FunctionType.UNCONSTRAINED) {
+      throw new Error("Can't call `create` on an unconstrained function.");
+    }
+    if (!this.txRequest) {
+      const executionRequest = this.getExecutionRequest(this.contractAddress, options.from);
+      const nodeInfo = await this.wallet.getNodeInfo();
+      const txContext = TxContext.empty(new Fr(nodeInfo.chainId), new Fr(nodeInfo.version));
+      const txRequest = await this.wallet.createAuthenticatedTxRequest([executionRequest], txContext);
+      this.txRequest = txRequest;
+    }
+    return this.txRequest;
+  }
+
+  /**
+   * Simulates a transaction's execution.
+   * @param options - optional arguments to be used in the creation of the transaction
+   * @returns The resulting transaction
+   */
+  public async simulate(options: SendMethodOptions): Promise<Tx> {
+    const txRequest = this.txRequest ?? (await this.create(options));
+    // TODO: Why do we need from separately, and cannot get it from txRequest.origin? When would they differ?
+    this.tx = await this.wallet.simulateTx(txRequest, txRequest.origin);
+    return this.tx;
+  }
+
+  protected getExecutionRequest(to: AztecAddress, from?: AztecAddress): ExecutionRequest {
+    const flatArgs = encodeArguments(this.functionDao, this.args);
+
+    const functionData = new FunctionData(
+      generateFunctionSelector(this.functionDao.name, this.functionDao.parameters),
+      this.functionDao.functionType === FunctionType.SECRET,
+      this.functionDao.name === 'constructor',
+    );
+
+    return {
+      args: flatArgs,
+      functionData,
+      to,
+      from: from || AztecAddress.ZERO,
+    };
+  }
+
+  /**
+   * Sends a transaction to the contract function with the specified options.
+   * This function throws an error if called on an unconstrained function.
+   * It creates and signs the transaction if necessary, and returns a SentTx instance,
+   * which can be used to track the transaction status, receipt, and events.
+   *
+   * @param options - An optional object containing 'from' property representing
+   * the AztecAddress of the sender. If not provided, the default address is used.
+   * @returns A SentTx instance for tracking the transaction status and information.
+   */
+  public send(options: SendMethodOptions = {}) {
+    if (this.functionDao.functionType === FunctionType.UNCONSTRAINED) {
+      throw new Error("Can't call `send` on an unconstrained function.");
+    }
+
+    const promise = (async () => {
+      const tx = this.tx ?? (await this.simulate(options));
+      return this.wallet.sendTx(tx);
+    })();
+
+    return new SentTx(this.wallet, promise);
+  }
+
+  /**
+   * Execute a view (read-only) transaction on an unconstrained function.
+   * This method is used to call functions that do not modify the contract state and only return data.
+   * Throws an error if called on a non-unconstrained function.
+   *
+   * @param options - An optional object containing additional configuration for the transaction.
+   * @returns The result of the view transaction as returned by the contract function.
+   */
+  public view(options: ViewMethodOptions = {}) {
+    if (this.functionDao.functionType !== FunctionType.UNCONSTRAINED) {
+      throw new Error('Can only call `view` on an unconstrained function.');
+    }
+
+    const { from } = options;
+    return this.wallet.viewTx(this.functionDao.name, this.args, this.contractAddress, from);
+  }
+}

package/src/contract/index.ts

@@ -0,0 +1,3 @@
+export * from './contract.js';
+export * from './contract_function_interaction.js';
+export * from './sent_tx.js';