starknet 3.0.0 → 3.3.0

package/src/contract.ts

@@ -3,11 +3,18 @@ import assert from 'minimalistic-assert';
 
 import { Provider, defaultProvider } from './provider';
 import { BlockIdentifier } from './provider/utils';
-import { Abi, AbiEntry, FunctionAbi, RawCalldata, Signature, StructAbi } from './types';
-import { BigNumberish, toBN } from './utils/number';
+import { Abi, AbiEntry, Calldata, FunctionAbi, Signature, StructAbi } from './types';
+import { BigNumberish, toBN, toFelt } from './utils/number';
 
+export type Struct = {
+  type: 'struct';
+  [k: string]: BigNumberish;
+};
+export type ParsedStruct = {
+  [key: string]: BigNumberish | ParsedStruct;
+};
 export type Args = {
-  [inputName: string]: string | string[] | { type: 'struct'; [k: string]: BigNumberish };
+  [inputName: string]: BigNumberish | BigNumberish[] | ParsedStruct | ParsedStruct[];
 };
 
 function parseFelt(candidate: string): BN {
@@ -18,27 +25,6 @@ function parseFelt(candidate: string): BN {
   }
 }
 
-function isFelt(candidate: string): boolean {
-  try {
-    parseFelt(candidate);
-    return true;
-  } catch (e) {
-    return false;
-  }
-}
-
-export function compileCalldata(args: Args): RawCalldata {
-  return Object.values(args).flatMap((value) => {
-    if (Array.isArray(value))
-      return [toBN(value.length).toString(), ...value.map((x) => toBN(x).toString())];
-    if (typeof value === 'object' && 'type' in value)
-      return Object.entries(value)
-        .filter(([k]) => k !== 'type')
-        .map(([, v]) => toBN(v).toString());
-    return toBN(value).toString();
-  });
-}
-
 export class Contract {
   connectedTo: string | null = null;
 
@@ -69,11 +55,24 @@ export class Contract {
       );
   }
 
+  /**
+   * Saves the address of the contract deployed on network that will be used for interaction
+   *
+   * @param address - address of the contract
+   * @returns Contract
+   */
   public connect(address: string): Contract {
     this.connectedTo = address;
     return this;
   }
 
+  /**
+   * Validates if all arguments that are passed to the method are corresponding to the ones in the abi
+   *
+   * @param type - type of the method
+   * @param method  - name of the method
+   * @param args - arguments that are passed to the method
+   */
   private validateMethodAndArgs(type: 'INVOKE' | 'CALL', method: string, args: Args = {}) {
     // ensure provided method exists
     const invokeableFunctionNames = this.abi
@@ -96,64 +95,235 @@ export class Contract {
       const arg = args[input.name];
       if (arg !== undefined) {
         if (input.type === 'felt') {
-          assert(typeof arg === 'string', `arg ${input.name} should be a felt (string)`);
-          assert(isFelt(arg as string), `arg ${input.name} should be decimal or hexadecimal`);
-        } else if (typeof arg === 'object' && 'type' in arg) {
-          assert(arg.type === 'struct', `arg ${input.name} should be a struct`);
+          assert(
+            typeof arg === 'string' || typeof arg === 'number' || arg instanceof BN,
+            `arg ${input.name} should be a felt (string, number, BigNumber)`
+          );
+        } else if (typeof arg === 'object' && input.type in this.structs) {
+          this.structs[input.type].members.forEach(({ name }) => {
+            assert(Object.keys(arg).includes(name), `arg should have a property ${name}`);
+          });
         } else {
-          assert(Array.isArray(arg), `arg ${input.name} should be a felt* (string[])`);
-          (arg as string[]).forEach((felt, i) => {
+          assert(Array.isArray(arg), `arg ${input.name} should be an Array`);
+          if (input.type === 'felt*') {
+            arg.forEach((felt) => {
+              assert(
+                typeof felt === 'string' || typeof felt === 'number' || felt instanceof BN,
+                `arg ${input.name} should be an array of string, number or BigNumber`
+              );
+            });
+          } else if (/\(felt/.test(input.type)) {
+            const tupleLength = input.type.split(',').length;
             assert(
-              typeof felt === 'string',
-              `arg ${input.name}[${i}] should be a felt (string) as part of a felt* (string[])`
+              arg.length === tupleLength,
+              `arg ${input.name} should have ${tupleLength} elements in tuple`
             );
-            assert(
-              isFelt(felt),
-              `arg ${input.name}[${i}] should be decimal or hexadecimal as part of a felt* (string[])`
-            );
-          });
+            arg.forEach((felt) => {
+              assert(
+                typeof felt === 'string' || typeof felt === 'number' || felt instanceof BN,
+                `arg ${input.name} should be an array of string, number or BigNumber`
+              );
+            });
+          } else {
+            const arrayType = input.type.replace('*', '');
+            arg.forEach((struct) => {
+              this.structs[arrayType].members.forEach(({ name }) => {
+                assert(
+                  Object.keys(struct).includes(name),
+                  `arg ${input.name} should be an array of ${arrayType}`
+                );
+              });
+            });
+          }
         }
       }
     });
   }
 
-  private parseResponseField(
-    element: AbiEntry | FunctionAbi,
-    responseIterator: Iterator<string>
-  ): Args {
-    let entries: AbiEntry[] = [];
-    if (['felt', 'felt*'].includes(element.type)) {
-      return responseIterator.next().value;
+  /**
+   * Deep parse of the object that has been passed to the method
+   *
+   * @param element - element that needs to be parsed
+   * @param type  - name of the method
+   * @return {string | string[]} - parsed arguments in format that contract is expecting
+   */
+  private parseCalldataObject(
+    element: ParsedStruct | BigNumberish,
+    type: string
+  ): string | string[] {
+    if (element === undefined) {
+      throw Error('Missing element in calldata object');
+    }
+    // checking if the passed element is struct or element in struct
+    if (this.structs[type] && this.structs[type].members.length) {
+      // going through all the members of the struct and parsing the value
+      return this.structs[type].members.reduce((acc, member: AbiEntry) => {
+        // if the member of the struct is another struct this will return array of the felts if not it will be single felt
+        // TODO: refactor types so member name can be used as keyof ParsedStruct
+        /* @ts-ignore */
+        const parsedData = this.parseCalldataObject(element[member.name], member.type);
+        if (typeof parsedData === 'string') {
+          acc.push(parsedData);
+        } else {
+          acc.push(...parsedData);
+        }
+        return acc;
+      }, [] as string[]);
     }
-    if (element.type in this.structs) {
-      entries = this.structs[element.type].members;
-    } else if ('outputs' in element) {
-      entries = element.outputs;
+    return toFelt(element as BigNumberish);
+  }
+
+  /**
+   * Parse of the response elements that are converted to Object (Struct) by using the abi
+   *
+   * @param responseIterator - iterator of the response
+   * @param type - type of the struct
+   * @return {BigNumberish | ParsedStruct} - parsed arguments in format that contract is expecting
+   */
+  private parseResponseStruct(
+    responseIterator: Iterator<string>,
+    type: string
+  ): BigNumberish | ParsedStruct {
+    // check the type of current element
+    if (type in this.structs && this.structs[type]) {
+      return this.structs[type].members.reduce((acc, el) => {
+        // parse each member of the struct (member can felt or nested struct)
+        acc[el.name] = this.parseResponseStruct(responseIterator, el.type);
+        return acc;
+      }, {} as any);
     }
-    return entries.reduce(
-      (acc, member) => ({
-        ...acc,
-        [member.name]: this.parseResponseField(member, responseIterator),
-      }),
-      {}
-    );
+    return parseFelt(responseIterator.next().value);
   }
 
+  /**
+   * Parse one field of the calldata by using input field from the abi for that method
+   *
+   * @param args - value of the field
+   * @param input  - input(field) information from the abi that will be used to parse the data
+   * @return {string | string[]} - parsed arguments in format that contract is expecting
+   */
+  private parsCalldataField(args: Args, input: AbiEntry): string | string[] {
+    const { name, type } = input;
+    const value = args[name];
+    const propName = name.replace(/_len$/, '');
+    switch (true) {
+      case /_len$/.test(name):
+        if (Array.isArray(args[propName])) {
+          const arr = args[propName] as (BigNumberish | ParsedStruct)[];
+          return toFelt(arr.length);
+        }
+        throw Error(`Expected ${propName} to be array`);
+      case /\*/.test(type):
+        if (Array.isArray(value)) {
+          return (value as (BigNumberish | ParsedStruct)[]).reduce((acc, el) => {
+            if (/felt/.test(type)) {
+              acc.push(toFelt(el as BigNumberish));
+            } else {
+              acc.push(...this.parseCalldataObject(el, type.replace('*', '')));
+            }
+            return acc;
+          }, [] as string[]);
+        }
+        throw Error(`Expected ${name} to be array`);
+      case type in this.structs:
+        return this.parseCalldataObject(value as ParsedStruct, type);
+      case /\(felt/.test(type):
+        if (Array.isArray(value)) {
+          return value.map((el) => toFelt(el as BigNumberish));
+        }
+        throw Error(`Expected ${name} to be array`);
+      default:
+        return toFelt(value as BigNumberish);
+    }
+  }
+
+  /**
+   * Parse the calldata by using input fields from the abi for that method
+   *
+   * @param args - arguments passed the the method
+   * @param inputs  - list of inputs(fields) that are in the abi
+   * @return {Calldata} - parsed arguments in format that contract is expecting
+   */
+  private compileCalldata(args: Args, inputs: AbiEntry[]): Calldata {
+    return inputs.reduce((acc, input) => {
+      const parsedData = this.parsCalldataField(args, input);
+      if (Array.isArray(parsedData)) {
+        acc.push(...parsedData);
+      } else {
+        acc.push(parsedData);
+      }
+      return acc;
+    }, [] as Calldata);
+  }
+
+  /**
+   * Parse elements of the response and structuring them into one field by using output property from the abi for that method
+   *
+   * @param responseIterator - iterator of the response
+   * @param output  - output(field) information from the abi that will be used to parse the data
+   * @return - parsed response corresponding to the abi structure of the field
+   */
+  private parseResponseField(
+    responseIterator: Iterator<string>,
+    output: AbiEntry,
+    parsedResult?: Args
+  ): any {
+    const { name, type } = output;
+    let arrLen: number;
+    const parsedDataArr: (BigNumberish | ParsedStruct)[] = [];
+    switch (true) {
+      case /_len$/.test(name):
+        return parseFelt(responseIterator.next().value).toNumber();
+      case /\(felt/.test(type):
+        return type.split(',').reduce((acc) => {
+          acc.push(parseFelt(responseIterator.next().value));
+          return acc;
+        }, [] as BigNumberish[]);
+      case /\*/.test(type):
+        if (parsedResult && parsedResult[`${name}_len`]) {
+          arrLen = parsedResult[`${name}_len`] as number;
+          while (parsedDataArr.length < arrLen) {
+            parsedDataArr.push(
+              this.parseResponseStruct(responseIterator, output.type.replace('*', ''))
+            );
+          }
+        }
+        return parsedDataArr;
+      case type in this.structs:
+        return this.parseResponseStruct(responseIterator, type);
+      default:
+        return parseFelt(responseIterator.next().value);
+    }
+  }
+
+  /**
+   * Parse elements of the response array and structuring them into response object
+   *
+   * @param method - method name
+   * @param response  - response from the method
+   * @return - parsed response corresponding to the abi
+   */
   private parseResponse(method: string, response: string[]): Args {
-    const methodAbi = this.abi.find((abi) => abi.name === method) as FunctionAbi;
+    const { outputs } = this.abi.find((abi) => abi.name === method) as FunctionAbi;
     const responseIterator = response.flat()[Symbol.iterator]();
-    return this.parseResponseField(methodAbi, responseIterator);
+    return outputs.flat().reduce((acc, output) => {
+      acc[output.name] = this.parseResponseField(responseIterator, output, acc);
+      if (acc[output.name] && acc[`${output.name}_len`]) {
+        delete acc[`${output.name}_len`];
+      }
+      return acc;
+    }, {} as Args);
   }
 
   public invoke(method: string, args: Args = {}, signature?: Signature) {
     // ensure contract is connected
     assert(this.connectedTo !== null, 'contract isnt connected to an address');
-
     // validate method and args
     this.validateMethodAndArgs('INVOKE', method, args);
+    const { inputs } = this.abi.find((abi) => abi.name === method) as FunctionAbi;
 
     // compile calldata
-    const calldata = compileCalldata(args);
+    const calldata = this.compileCalldata(args, inputs);
 
     return this.provider.invokeFunction({
       contractAddress: this.connectedTo,
@@ -169,16 +339,16 @@ export class Contract {
 
     // validate method and args
     this.validateMethodAndArgs('CALL', method, args);
+    const { inputs } = this.abi.find((abi) => abi.name === method) as FunctionAbi;
 
     // compile calldata
-    const calldata = compileCalldata(args);
-
+    const calldata = this.compileCalldata(args, inputs);
     return this.provider
       .callContract(
         {
           contractAddress: this.connectedTo,
-          entrypoint: method,
           calldata,
+          entrypoint: method,
         },
         blockIdentifier
       )

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

@@ -15,23 +15,19 @@ import {
   GetTransactionResponse,
   GetTransactionStatusResponse,
   Invocation,
+  Signature,
   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 +129,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 +318,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 +332,32 @@ export class Provider implements ProviderInterface {
     });
   }
 
-  public async waitForTx(txHash: BigNumberish, retryInterval: number = 8000) {
+  /**
+   * 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
+   * @returns response from addTransaction
+   */
+  public LEGACY_invokeFunction(
+    contractAddress: string,
+    entrypointSelector: string,
+    calldata?: string[],
+    signature?: Signature
+  ): Promise<AddTransactionResponse> {
+    return this.fetchEndpoint('add_transaction', undefined, {
+      type: 'INVOKE_FUNCTION',
+      contract_address: contractAddress,
+      entry_point_selector: entrypointSelector,
+      calldata: bigNumberishArrayToDecimalStringArray(calldata ?? []),
+      signature: bigNumberishArrayToDecimalStringArray(signature ?? []),
+    });
+  }
+
+  public async waitForTransaction(txHash: BigNumberish, retryInterval: number = 8000) {
     let onchain = false;
     await wait(retryInterval);
 
@@ -344,10 +370,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 = {
@@ -163,3 +168,9 @@ export type TransactionReceipt = {
   l2_to_l1_messages: string[];
   events: string[];
 };
+
+export type RawArgs = {
+  [inputName: string]: string | string[] | { type: 'struct'; [k: string]: BigNumberish };
+};
+
+export type Calldata = string[];

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[][] {