starknet 3.1.0 → 3.4.0

package/src/account/default.ts

@@ -1,15 +1,27 @@
+import assert from 'minimalistic-assert';
+
 import { Provider } from '../provider';
 import { Signer, SignerInterface } from '../signer';
 import {
   Abi,
   AddTransactionResponse,
-  ExecuteInvocation,
+  Call,
   InvocationsDetails,
+  InvokeFunctionTransaction,
   KeyPair,
   Signature,
+  Transaction,
 } from '../types';
+import { sign } from '../utils/ellipticCurve';
+import {
+  computeHashOnElements,
+  getSelectorFromName,
+  transactionPrefix,
+  transactionVersion,
+} from '../utils/hash';
 import { BigNumberish, bigNumberishArrayToDecimalStringArray, toBN, toHex } from '../utils/number';
-import { compileCalldata, getSelectorFromName } from '../utils/stark';
+import { compileCalldata } from '../utils/stark';
+import { fromCallsToExecuteCalldata } from '../utils/transaction';
 import { TypedData, getMessageHash } from '../utils/typedData';
 import { AccountInterface } from './interface';
 
@@ -41,51 +53,126 @@ export class Account extends Provider implements AccountInterface {
    * @returns a confirmation of invoking a function on the starknet contract
    */
   public async execute(
-    transactions: ExecuteInvocation | ExecuteInvocation[],
-    abis: Abi[] = [],
+    calls: Call | Call[],
+    abis: Abi[] | undefined = undefined,
     transactionsDetail: InvocationsDetails = {}
   ): Promise<AddTransactionResponse> {
-    if (Array.isArray(transactions) && transactions.length !== 1) {
-      throw new Error('Only one transaction at a time is currently supported');
-    }
+    const transactions = Array.isArray(calls) ? calls : [calls];
+
+    const signerDetails = {
+      walletAddress: this.address,
+      nonce: toBN(transactionsDetail.nonce ?? (await this.getNonce())),
+      maxFee: toBN(transactionsDetail.maxFee ?? '0'),
+    };
+
+    const signature = await this.signer.signTransaction(transactions, signerDetails, abis);
+
+    const calldata = [...fromCallsToExecuteCalldata(transactions), signerDetails.nonce.toString()];
+
+    return this.fetchEndpoint('add_transaction', undefined, {
+      type: 'INVOKE_FUNCTION',
+      contract_address: this.address,
+      entry_point_selector: getSelectorFromName('__execute__'),
+      calldata,
+      signature: bigNumberishArrayToDecimalStringArray(signature),
+    });
+  }
+
+  /**
+   * Temporary method to allow dapps on starknet.js v2 to work with Argent X v3
+   * @deprecated to remove ASAP
+   */
+  public async LEGACY_addTransaction(transaction: Transaction): Promise<AddTransactionResponse> {
+    if (transaction.type === 'DEPLOY') throw new Error('No DEPLOYS');
 
-    const {
-      contractAddress,
-      calldata = [],
-      entrypoint,
-      ...invocation
-    } = Array.isArray(transactions) ? transactions[0] : transactions;
-    const { nonce } = transactionsDetail;
-
-    const nonceBn = toBN(nonce ?? (await this.getNonce()));
-    const calldataDecimal = bigNumberishArrayToDecimalStringArray(calldata);
-
-    const signature = await this.signer.signTransaction(
-      [
-        {
-          ...invocation,
-          contractAddress,
-          calldata: calldataDecimal,
-          entrypoint,
-        },
-      ],
-      { walletAddress: this.address, nonce: nonceBn },
-      abis
+    assert(
+      !transaction.signature,
+      "Adding signatures to a signer transaction currently isn't supported"
     );
 
-    const entrypointSelector = getSelectorFromName(entrypoint);
+    let nonceBn;
+    if (transaction.nonce) {
+      nonceBn = toBN(transaction.nonce);
+    } else {
+      const { result } = await this.callContract({
+        contractAddress: this.address,
+        entrypoint: 'get_nonce',
+      });
+      nonceBn = toBN(result[0]);
+    }
 
-    return super.invokeFunction({
-      contractAddress: this.address,
-      entrypoint: 'execute',
-      calldata: [
-        contractAddress,
-        entrypointSelector,
-        calldataDecimal.length.toString(),
-        ...calldataDecimal,
-        nonceBn.toString(),
-      ],
-      signature,
+    function hashMulticall(
+      account: string,
+      transactions: InvokeFunctionTransaction[],
+      nonce: string,
+      maxFee: string
+    ) {
+      const hashArray = transactions
+        .map(({ contract_address, entry_point_selector, calldata }) => [
+          contract_address,
+          entry_point_selector,
+          computeHashOnElements(calldata || []),
+        ])
+        .map(bigNumberishArrayToDecimalStringArray)
+        .map(computeHashOnElements);
+
+      return computeHashOnElements([
+        transactionPrefix,
+        account,
+        computeHashOnElements(hashArray),
+        nonce,
+        maxFee,
+        transactionVersion,
+      ]);
+    }
+    const msgHash = hashMulticall(this.address, [transaction], nonceBn.toString(), '0');
+    if (!('keyPair' in this.signer)) {
+      throw new Error('No keyPair');
+    }
+    const signature = sign((this.signer as any).keyPair, msgHash);
+
+    const transformCallsToMulticallArrays = (calls: InvokeFunctionTransaction[]) => {
+      const callArray: any[] = [];
+      const calldata: BigNumberish[] = [];
+      calls.forEach((call) => {
+        const data = call.calldata || [];
+        callArray.push({
+          to: toBN(call.contract_address).toString(10),
+          selector: toBN(call.entry_point_selector).toString(10),
+          data_offset: calldata.length.toString(),
+          data_len: data.length.toString(),
+        });
+        calldata.push(...data);
+      });
+      return {
+        callArray,
+        calldata: bigNumberishArrayToDecimalStringArray(calldata),
+      };
+    };
+
+    const fromCallsToExecuteCalldata2 = (calls: InvokeFunctionTransaction[]): string[] => {
+      const { callArray, calldata } = transformCallsToMulticallArrays(calls);
+      return [
+        callArray.length.toString(),
+        ...callArray
+          .map(
+            ({ to, selector, data_offset, data_len }) =>
+              [to, selector, data_offset, data_len] as string[]
+          )
+          .flat(),
+        calldata.length.toString(),
+        ...calldata,
+      ];
+    };
+
+    const calldata = [...fromCallsToExecuteCalldata2([transaction]), nonceBn.toString()];
+
+    return this.fetchEndpoint('add_transaction', undefined, {
+      type: 'INVOKE_FUNCTION',
+      contract_address: this.address,
+      entry_point_selector: getSelectorFromName('__execute__'),
+      calldata,
+      signature: bigNumberishArrayToDecimalStringArray(signature),
     });
   }
 
@@ -114,7 +201,7 @@ export class Account extends Provider implements AccountInterface {
   /**
    * Verify a signature of a JSON object
    *
-   * @param json - JSON object to be verified
+   * @param hash - JSON object to be verified
    * @param signature - signature of the JSON object
    * @returns true if the signature is valid, false otherwise
    * @throws {Error} if the JSON object is not a valid JSON or the signature is not a valid signature

package/src/account/interface.ts

@@ -2,8 +2,8 @@ import { ProviderInterface } from '../provider';
 import {
   Abi,
   AddTransactionResponse,
+  Call,
   DeployContractPayload,
-  ExecuteInvocation,
   InvocationsDetails,
   Signature,
 } from '../types';
@@ -41,7 +41,7 @@ export abstract class AccountInterface extends ProviderInterface {
    * @returns response from addTransaction
    */
   public abstract execute(
-    transactions: ExecuteInvocation | ExecuteInvocation[],
+    transactions: Call | Call[],
     abis?: Abi[],
     transactionsDetail?: InvocationsDetails
   ): Promise<AddTransactionResponse>;

package/src/index.ts

@@ -5,6 +5,7 @@ export * from './types';
 export * from './contract';
 export * from './provider';
 export * from './account';
+export * from './signer';
 
 /**
  * Utils

package/src/provider/default.ts

@@ -17,21 +17,16 @@ import {
   Invocation,
   TransactionReceipt,
 } from '../types';
+import { getSelectorFromName } from '../utils/hash';
 import { parse, stringify } from '../utils/json';
 import { BigNumberish, bigNumberishArrayToDecimalStringArray, toBN, toHex } from '../utils/number';
-import { compressProgram, getSelectorFromName, randomAddress } from '../utils/stark';
+import { compressProgram, randomAddress } from '../utils/stark';
 import { ProviderInterface } from './interface';
 import { BlockIdentifier, getFormattedBlockIdentifier, txIdentifier } from './utils';
 
 type NetworkName = 'mainnet-alpha' | 'goerli-alpha';
 
-type ProviderOptions =
-  | {
-      network: NetworkName;
-    }
-  | {
-      baseUrl: string;
-    };
+type ProviderOptions = { network: NetworkName } | { baseUrl: string };
 
 function wait(delay: number) {
   return new Promise((res) => setTimeout(res, delay));
@@ -133,14 +128,21 @@ export class Provider implements ProviderInterface {
     const queryString = this.getQueryString(query);
     const headers = this.getHeaders(method);
 
-    const { data } = await axios.request<Endpoints[T]['RESPONSE']>({
-      method,
-      url: urljoin(baseUrl, endpoint, queryString),
-      data: stringify(request),
-      headers,
-    });
-
-    return data;
+    try {
+      const { data } = await axios.request<Endpoints[T]['RESPONSE']>({
+        method,
+        url: urljoin(baseUrl, endpoint, queryString),
+        data: stringify(request),
+        headers,
+      });
+      return data;
+    } catch (error: any) {
+      const data = error?.response?.data;
+      if (data?.message) {
+        throw new Error(`${data.code}: ${data.message}`);
+      }
+      throw error;
+    }
   }
 
   /**
@@ -315,10 +317,8 @@ export class Provider implements ProviderInterface {
    * Invokes a function on starknet
    * @deprecated This method wont be supported as soon as fees are mandatory
    *
-   * @param contractAddress - target contract address for invoke
-   * @param entrypointSelector - target entrypoint selector for
-   * @param calldata - (optional, default []) calldata
-   * @param signature - (optional) signature to send along
+   * @param invocation
+   * @param _abi - (optional) signature to send along
    * @returns response from addTransaction
    */
   public invokeFunction(invocation: Invocation, _abi?: Abi): Promise<AddTransactionResponse> {
@@ -331,7 +331,7 @@ export class Provider implements ProviderInterface {
     });
   }
 
-  public async waitForTx(txHash: BigNumberish, retryInterval: number = 8000) {
+  public async waitForTransaction(txHash: BigNumberish, retryInterval: number = 8000) {
     let onchain = false;
     await wait(retryInterval);
 
@@ -344,10 +344,20 @@ export class Provider implements ProviderInterface {
       if (res.tx_status === 'ACCEPTED_ON_L1' || res.tx_status === 'ACCEPTED_ON_L2') {
         onchain = true;
       } else if (res.tx_status === 'REJECTED' || res.tx_status === 'NOT_RECEIVED') {
-        const error = Error(res.tx_status) as Error & { response: GetTransactionStatusResponse };
+        const message = res.tx_failure_reason
+          ? `${res.tx_status}: ${res.tx_failure_reason.code}\n${res.tx_failure_reason.error_message}`
+          : res.tx_status;
+        const error = new Error(message) as Error & { response: GetTransactionStatusResponse };
         error.response = res;
         throw error;
       }
     }
   }
+
+  /**
+   * @deprecated use `waitForTransaction` instead
+   */
+  public async waitForTx(txHash: BigNumberish, retryInterval: number = 8000) {
+    return this.waitForTransaction(txHash, retryInterval);
+  }
 }

package/src/provider/interface.ts

@@ -137,5 +137,10 @@ export abstract class ProviderInterface {
    */
   public abstract invokeFunction(invocation: Invocation): Promise<AddTransactionResponse>;
 
-  public abstract waitForTx(txHash: BigNumberish, retryInterval?: number): Promise<void>;
+  public abstract waitForTransaction(txHash: BigNumberish, retryInterval?: number): Promise<void>;
+
+  /**
+   * @deprecated use `waitForTransaction` instead
+   */
+  public abstract waitForTransaction(txHash: BigNumberish, retryInterval?: number): Promise<void>;
 }

package/src/signer/default.ts

@@ -1,9 +1,6 @@
 import { Abi, Invocation, InvocationsSignerDetails, KeyPair, Signature } from '../types';
 import { getStarkKey, sign } from '../utils/ellipticCurve';
-import { addHexPrefix } from '../utils/encode';
-import { hashMessage } from '../utils/hash';
-import { bigNumberishArrayToDecimalStringArray, toBN } from '../utils/number';
-import { getSelectorFromName } from '../utils/stark';
+import { hashMulticall } from '../utils/hash';
 import { TypedData, getMessageHash } from '../utils/typedData';
 import { SignerInterface } from './interface';
 
@@ -21,38 +18,25 @@ export class Signer implements SignerInterface {
   public async signTransaction(
     transactions: Invocation[],
     transactionsDetail: InvocationsSignerDetails,
-    abis: Abi[] = []
+    abis?: Abi[]
   ): Promise<Signature> {
-    if (transactions.length !== 1) {
-      throw new Error('Only one transaction at a time is currently supported by this signer');
-    }
-    if (abis?.length !== 0 && abis.length !== transactions.length) {
+    if (abis && abis.length !== transactions.length) {
       throw new Error('ABI must be provided for each transaction or no transaction');
     }
     // now use abi to display decoded data somewhere, but as this signer is headless, we can't do that
 
-    const { contractAddress, entrypoint, calldata = [] } = transactions[0];
-    const { nonce, walletAddress } = transactionsDetail;
-
-    const nonceBn = toBN(nonce);
-    const entrypointSelector = getSelectorFromName(entrypoint);
-    const calldataDecimal = bigNumberishArrayToDecimalStringArray(calldata);
-
-    const msgHash = addHexPrefix(
-      hashMessage(
-        walletAddress,
-        contractAddress,
-        entrypointSelector,
-        calldataDecimal,
-        nonceBn.toString()
-      )
+    const msgHash = hashMulticall(
+      transactionsDetail.walletAddress,
+      transactions,
+      transactionsDetail.nonce.toString(),
+      transactionsDetail.maxFee.toString()
     );
 
     return sign(this.keyPair, msgHash);
   }
 
-  public async signMessage(typedData: TypedData, walletAddress: string): Promise<Signature> {
-    const msgHash = getMessageHash(typedData, walletAddress);
+  public async signMessage(typedData: TypedData, accountAddress: string): Promise<Signature> {
+    const msgHash = getMessageHash(typedData, accountAddress);
     return sign(this.keyPair, msgHash);
   }
 }

package/src/signer/interface.ts

@@ -13,11 +13,12 @@ export abstract class SignerInterface {
    * Sign an JSON object for off-chain usage with the starknet private key and return the signature
    * This adds a message prefix so it cant be interchanged with transactions
    *
-   * @param json - JSON object to be signed
+   * @param typedData - JSON object to be signed
+   * @param accountAddress - account
    * @returns the signature of the JSON object
    * @throws {Error} if the JSON object is not a valid JSON
    */
-  public abstract signMessage(typedData: TypedData, walletAddress: string): Promise<Signature>;
+  public abstract signMessage(typedData: TypedData, accountAddress: string): Promise<Signature>;
 
   /**
    * Signs a transaction with the starknet private key and returns the signature

package/src/types/api.ts

@@ -137,6 +137,11 @@ export type GetCodeResponse = {
 export type GetTransactionStatusResponse = {
   tx_status: Status;
   block_hash: string;
+  tx_failure_reason?: {
+    tx_id: number;
+    code: string;
+    error_message: string;
+  };
 };
 
 export type GetTransactionResponse = {

package/src/types/lib.ts

@@ -3,7 +3,7 @@ import type { ec as EC } from 'elliptic';
 import type { BigNumberish } from '../utils/number';
 
 export type KeyPair = EC.KeyPair;
-export type Signature = BigNumberish[];
+export type Signature = string[];
 export type RawCalldata = BigNumberish[];
 
 export type DeployContractPayload = {
@@ -19,14 +19,13 @@ export type Invocation = {
   signature?: Signature;
 };
 
-export type ExecuteInvocation = Omit<Invocation, 'signature'>;
+export type Call = Omit<Invocation, 'signature'>;
 
 export type InvocationsDetails = {
   nonce?: BigNumberish;
+  maxFee?: BigNumberish;
 };
 
-export type Call = Omit<Invocation, 'signature' | 'nonce'>;
-
 export type Status =
   | 'NOT_RECEIVED'
   | 'RECEIVED'

package/src/utils/ellipticCurve.ts

@@ -80,7 +80,7 @@ export function sign(keyPair: KeyPair, msgHash: string): Signature {
   assertInRange(r, ONE, toBN(addHexPrefix(MAX_ECDSA_VAL)), 'r');
   assertInRange(s, ONE, toBN(addHexPrefix(EC_ORDER)), 's');
   assertInRange(w, ONE, toBN(addHexPrefix(MAX_ECDSA_VAL)), 'w');
-  return [r, s];
+  return [r.toString(), s.toString()];
 }
 
 function chunkArray(arr: any[], n: number): any[][] {

package/src/utils/hash.ts

@@ -3,9 +3,14 @@ import { keccak256 } from 'ethereum-cryptography/keccak';
 import assert from 'minimalistic-assert';
 
 import { CONSTANT_POINTS, FIELD_PRIME, MASK_250, ONE, ZERO } from '../constants';
+import { Call } from '../types';
 import { ec } from './ellipticCurve';
 import { addHexPrefix, buf2hex, utf8ToArray } from './encode';
-import { BigNumberish, toBN } from './number';
+import { BigNumberish, bigNumberishArrayToDecimalStringArray, toBN, toHex } from './number';
+import { encodeShortString } from './shortString';
+
+export const transactionPrefix = encodeShortString('StarkNet Transaction');
+export const transactionVersion = 0;
 
 function keccakHex(value: string): string {
   return addHexPrefix(buf2hex(keccak256(utf8ToArray(value))));
@@ -22,6 +27,18 @@ export function starknetKeccak(value: string): BN {
   return toBN(keccakHex(value)).and(MASK_250);
 }
 
+/**
+ * Function to get the hex selector from a given function name
+ *
+ * [Reference](https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/public/abi.py#L25-L26)
+ * @param funcName - selectors abi function name
+ * @returns hex selector of given abi function name
+ */
+export function getSelectorFromName(funcName: string) {
+  // sometimes BigInteger pads the hex string with zeros, which isnt allowed in the starknet api
+  return toHex(starknetKeccak(funcName));
+}
+
 const constantPoints = CONSTANT_POINTS.map((coords: string[]) =>
   ec.curve.point(coords[0], coords[1])
 );
@@ -47,17 +64,27 @@ export function computeHashOnElements(data: BigNumberish[]) {
   return [...data, data.length].reduce((x, y) => pedersen([x, y]), 0).toString();
 }
 
-export function hashCalldata(calldata: string[]): string {
-  return computeHashOnElements(calldata);
-}
-
-export function hashMessage(
+export function hashMulticall(
   account: string,
-  to: string,
-  selector: string,
-  calldata: string[],
-  nonce: string
+  transactions: Call[],
+  nonce: string,
+  maxFee: string
 ) {
-  const calldataHash = hashCalldata(calldata);
-  return computeHashOnElements([account, to, selector, calldataHash, nonce]);
+  const hashArray = transactions
+    .map(({ contractAddress, entrypoint, calldata }) => [
+      contractAddress,
+      getSelectorFromName(entrypoint),
+      computeHashOnElements(calldata || []),
+    ])
+    .map(bigNumberishArrayToDecimalStringArray)
+    .map(computeHashOnElements);
+
+  return computeHashOnElements([
+    transactionPrefix,
+    account,
+    computeHashOnElements(hashArray),
+    nonce,
+    maxFee,
+    transactionVersion,
+  ]);
 }

package/src/utils/stark.ts

@@ -3,9 +3,8 @@ import { gzip } from 'pako';
 import { Calldata, CompressedProgram, Program, RawArgs, Signature } from '../types';
 import { genKeyPair, getStarkKey } from './ellipticCurve';
 import { addHexPrefix, btoaUniversal } from './encode';
-import { starknetKeccak } from './hash';
 import { stringify } from './json';
-import { toBN, toHex } from './number';
+import { toBN } from './number';
 
 /**
  * Function to compress compiled cairo program
@@ -20,18 +19,6 @@ export function compressProgram(jsonProgram: Program | string): CompressedProgra
   return btoaUniversal(compressedProgram);
 }
 
-/**
- * Function to get the hex selector from a given function name
- *
- * [Reference](https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/public/abi.py#L25-L26)
- * @param funcName - selectors abi function name
- * @returns hex selector of given abi function name
- */
-export function getSelectorFromName(funcName: string) {
-  // sometimes BigInteger pads the hex string with zeros, which isnt allowed in the starknet api
-  return toHex(starknetKeccak(funcName));
-}
-
 export function randomAddress(): string {
   const randomKeyPair = genKeyPair();
   return getStarkKey(randomKeyPair);

package/src/utils/transaction.ts

@@ -0,0 +1,50 @@
+import { ParsedStruct } from '../contract';
+import { Call } from '../types';
+import { getSelectorFromName } from './hash';
+import { BigNumberish, bigNumberishArrayToDecimalStringArray, toBN } from './number';
+
+/**
+ * Transforms a list of Calls, each with their own calldata, into
+ * two arrays: one with the entrypoints, and one with the concatenated calldata.
+ * @param calls
+ * @returns
+ */
+export const transformCallsToMulticallArrays = (calls: Call[]) => {
+  const callArray: ParsedStruct[] = [];
+  const calldata: BigNumberish[] = [];
+  calls.forEach((call) => {
+    const data = call.calldata || [];
+    callArray.push({
+      to: toBN(call.contractAddress).toString(10),
+      selector: toBN(getSelectorFromName(call.entrypoint)).toString(10),
+      data_offset: calldata.length.toString(),
+      data_len: data.length.toString(),
+    });
+    calldata.push(...data);
+  });
+  return {
+    callArray,
+    calldata: bigNumberishArrayToDecimalStringArray(calldata),
+  };
+};
+
+/**
+ * Transforms a list of calls in the full flattened calldata expected
+ * by the __execute__ protocol.
+ * @param calls
+ * @returns
+ */
+export const fromCallsToExecuteCalldata = (calls: Call[]): string[] => {
+  const { callArray, calldata } = transformCallsToMulticallArrays(calls);
+  return [
+    callArray.length.toString(),
+    ...callArray
+      .map(
+        ({ to, selector, data_offset, data_len }) =>
+          [to, selector, data_offset, data_len] as string[]
+      )
+      .flat(),
+    calldata.length.toString(),
+    ...calldata,
+  ];
+};

package/src/utils/typedData/index.ts

@@ -1,7 +1,6 @@
-import { computeHashOnElements } from '../hash';
+import { computeHashOnElements, getSelectorFromName } from '../hash';
 import { BigNumberish, toBN, toHex } from '../number';
 import { encodeShortString } from '../shortString';
-import { getSelectorFromName } from '../stark';
 import { TypedData } from './types';
 import { validateTypedData } from './utils';
 
@@ -161,7 +160,7 @@ export const getStructHash = <T extends TypedData>(
  * with Keccak256.
  *
  * @param {TypedData} typedData
- * @param {boolean} hash
+ * @param {BigNumberish} account
  * @return {string}
  */
 export const getMessageHash = (typedData: TypedData, account: BigNumberish): string => {

package/types/api.d.ts

@@ -127,6 +127,11 @@ export declare type GetCodeResponse = {
 export declare type GetTransactionStatusResponse = {
   tx_status: Status;
   block_hash: string;
+  tx_failure_reason?: {
+    tx_id: number;
+    code: string;
+    error_message: string;
+  };
 };
 export declare type GetTransactionResponse = {
   status: Status;