starknet 2.9.0 → 3.2.0

package/src/provider/default.ts

@@ -1,39 +1,46 @@
-import axios from 'axios';
+import axios, { AxiosRequestHeaders } from 'axios';
 import urljoin from 'url-join';
 
 import {
+  Abi,
   AddTransactionResponse,
+  Call,
   CallContractResponse,
-  CallContractTransaction,
   CompiledContract,
+  DeployContractPayload,
+  Endpoints,
   GetBlockResponse,
   GetCodeResponse,
   GetContractAddressesResponse,
   GetTransactionResponse,
   GetTransactionStatusResponse,
-  Signature,
-  Transaction,
+  Invocation,
+  TransactionReceipt,
 } from '../types';
+import { getSelectorFromName } from '../utils/hash';
 import { parse, stringify } from '../utils/json';
-import { BigNumberish, toBN, toHex } from '../utils/number';
-import { compressProgram, formatSignature, randomAddress } from '../utils/stark';
+import { BigNumberish, bigNumberishArrayToDecimalStringArray, toBN, toHex } from '../utils/number';
+import { compressProgram, randomAddress } from '../utils/stark';
 import { ProviderInterface } from './interface';
-import { BlockIdentifier, getFormattedBlockIdentifier } from './utils';
+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));
 }
 
+function isEmptyQueryObject(obj?: Record<any, any>): obj is undefined {
+  return (
+    obj === undefined ||
+    Object.keys(obj).length === 0 ||
+    (Object.keys(obj).length === 1 &&
+      Object.entries(obj).every(([k, v]) => k === 'blockIdentifier' && v === null))
+  );
+}
+
 export class Provider implements ProviderInterface {
   public baseUrl: string;
 
@@ -67,6 +74,77 @@ export class Provider implements ProviderInterface {
     }
   }
 
+  private getFetchUrl(endpoint: keyof Endpoints) {
+    const gatewayUrlEndpoints = ['add_transaction'];
+
+    return gatewayUrlEndpoints.includes(endpoint) ? this.gatewayUrl : this.feederGatewayUrl;
+  }
+
+  private getFetchMethod(endpoint: keyof Endpoints) {
+    const postMethodEndpoints = ['add_transaction', 'call_contract'];
+
+    return postMethodEndpoints.includes(endpoint) ? 'POST' : 'GET';
+  }
+
+  private getQueryString(query?: Record<string, any>): string {
+    if (isEmptyQueryObject(query)) {
+      return '';
+    }
+    const queryString = Object.entries(query)
+      .map(([key, value]) => {
+        if (key === 'blockIdentifier') {
+          return `${getFormattedBlockIdentifier(value)}`;
+        }
+        return `${key}=${value}`;
+      })
+      .join('&');
+
+    return `?${queryString}`;
+  }
+
+  private getHeaders(method: 'POST' | 'GET'): AxiosRequestHeaders | undefined {
+    if (method === 'POST') {
+      return {
+        'Content-Type': 'application/json',
+      };
+    }
+    return undefined;
+  }
+
+  // typesafe fetch
+  protected async fetchEndpoint<T extends keyof Endpoints>(
+    endpoint: T,
+    // typescript type magiuc to create a nice fitting function interface
+    ...[query, request]: Endpoints[T]['QUERY'] extends never
+      ? Endpoints[T]['REQUEST'] extends never
+        ? [] // when no query and no request is needed, we can omit the query and request parameters
+        : [undefined, Endpoints[T]['REQUEST']]
+      : Endpoints[T]['REQUEST'] extends never
+      ? [Endpoints[T]['QUERY']] // when no request is needed, we can omit the request parameter
+      : [Endpoints[T]['QUERY'], Endpoints[T]['REQUEST']] // when both query and request are needed, we cant omit anything
+  ): Promise<Endpoints[T]['RESPONSE']> {
+    const baseUrl = this.getFetchUrl(endpoint);
+    const method = this.getFetchMethod(endpoint);
+    const queryString = this.getQueryString(query);
+    const headers = this.getHeaders(method);
+
+    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;
+    }
+  }
+
   /**
    * Gets the smart contract address on the goerli testnet.
    *
@@ -74,10 +152,7 @@ export class Provider implements ProviderInterface {
    * @returns starknet smart contract addresses
    */
   public async getContractAddresses(): Promise<GetContractAddressesResponse> {
-    const { data } = await axios.get<GetContractAddressesResponse>(
-      urljoin(this.feederGatewayUrl, 'get_contract_addresses')
-    );
-    return data;
+    return this.fetchEndpoint('get_contract_addresses');
   }
 
   /**
@@ -91,20 +166,21 @@ export class Provider implements ProviderInterface {
    * @returns the result of the function on the smart contract.
    */
   public async callContract(
-    invokeTransaction: CallContractTransaction,
+    { contractAddress, entrypoint, calldata = [] }: Call,
     blockIdentifier: BlockIdentifier = null
   ): Promise<CallContractResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
-
-    const { data } = await axios.post<CallContractResponse>(
-      urljoin(this.feederGatewayUrl, 'call_contract', formattedBlockIdentifier),
+    return this.fetchEndpoint(
+      'call_contract',
+      {
+        blockIdentifier,
+      },
       {
         signature: [],
-        calldata: [],
-        ...invokeTransaction,
+        contract_address: contractAddress,
+        entry_point_selector: getSelectorFromName(entrypoint),
+        calldata,
       }
     );
-    return data;
   }
 
   /**
@@ -117,12 +193,7 @@ export class Provider implements ProviderInterface {
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
   public async getBlock(blockIdentifier: BlockIdentifier = null): Promise<GetBlockResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
-
-    const { data } = await axios.get<GetBlockResponse>(
-      urljoin(this.feederGatewayUrl, 'get_block', formattedBlockIdentifier)
-    );
-    return data;
+    return this.fetchEndpoint('get_block', { blockIdentifier });
   }
 
   /**
@@ -139,16 +210,7 @@ export class Provider implements ProviderInterface {
     contractAddress: string,
     blockIdentifier: BlockIdentifier = null
   ): Promise<GetCodeResponse> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
-
-    const { data } = await axios.get<GetCodeResponse>(
-      urljoin(
-        this.feederGatewayUrl,
-        'get_code',
-        `?contractAddress=${contractAddress}&${formattedBlockIdentifier}`
-      )
-    );
-    return data;
+    return this.fetchEndpoint('get_code', { blockIdentifier, contractAddress });
   }
 
   // TODO: add proper type
@@ -168,16 +230,7 @@ export class Provider implements ProviderInterface {
     key: number,
     blockIdentifier: BlockIdentifier = null
   ): Promise<object> {
-    const formattedBlockIdentifier = getFormattedBlockIdentifier(blockIdentifier);
-
-    const { data } = await axios.get<object>(
-      urljoin(
-        this.feederGatewayUrl,
-        'get_storage_at',
-        `?contractAddress=${contractAddress}&key=${key}&${formattedBlockIdentifier}`
-      )
-    );
-    return data;
+    return this.fetchEndpoint('get_storage_at', { blockIdentifier, contractAddress, key });
   }
 
   /**
@@ -189,57 +242,45 @@ export class Provider implements ProviderInterface {
    * @returns the transaction status object { block_number, tx_status: NOT_RECEIVED | RECEIVED | PENDING | REJECTED | ACCEPTED_ONCHAIN }
    */
   public async getTransactionStatus(txHash: BigNumberish): Promise<GetTransactionStatusResponse> {
-    const txHashBn = toBN(txHash);
-    const { data } = await axios.get<GetTransactionStatusResponse>(
-      urljoin(
-        this.feederGatewayUrl,
-        'get_transaction_status',
-        `?transactionHash=${toHex(txHashBn)}`
-      )
-    );
-    return data;
+    const txHashHex = toHex(toBN(txHash));
+    return this.fetchEndpoint('get_transaction_status', { transactionHash: txHashHex });
   }
 
   /**
-   * Gets the transaction information from a tx id.
+   * Gets the transaction receipt from a tx hash or tx id.
    *
-   * [Reference](https://github.com/starkware-libs/cairo-lang/blob/f464ec4797361b6be8989e36e02ec690e74ef285/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L54-L58)
+   * [Reference] (https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L104-L111)
    *
    * @param txHash
-   * @returns the transacton object { transaction_id, status, transaction, block_number?, block_number?, transaction_index?, transaction_failure_reason? }
+   * @param txId
+   * @returns the transaction receipt object
    */
-  public async getTransaction(txHash: BigNumberish): Promise<GetTransactionResponse> {
-    const txHashBn = toBN(txHash);
-    const { data } = await axios.get<GetTransactionResponse>(
-      urljoin(this.feederGatewayUrl, 'get_transaction', `?transactionHash=${toHex(txHashBn)}`)
+
+  public async getTransactionReceipt({
+    txHash,
+    txId,
+  }: {
+    txHash?: BigNumberish;
+    txId?: BigNumberish;
+  }): Promise<TransactionReceipt> {
+    const { data } = await axios.get<TransactionReceipt>(
+      urljoin(this.feederGatewayUrl, 'get_transaction_receipt', `?${txIdentifier(txHash, txId)}`)
     );
+
     return data;
   }
 
   /**
-   * Invoke a function on the starknet contract
+   * Gets the transaction information from a tx id.
    *
-   * [Reference](https://github.com/starkware-libs/cairo-lang/blob/f464ec4797361b6be8989e36e02ec690e74ef285/src/starkware/starknet/services/api/gateway/gateway_client.py#L13-L17)
+   * [Reference](https://github.com/starkware-libs/cairo-lang/blob/f464ec4797361b6be8989e36e02ec690e74ef285/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L54-L58)
    *
-   * @param transaction - transaction to be invoked
-   * @returns a confirmation of invoking a function on the starknet contract
+   * @param txHash
+   * @returns the transacton object { transaction_id, status, transaction, block_number?, block_number?, transaction_index?, transaction_failure_reason? }
    */
-  public async addTransaction(transaction: Transaction): Promise<AddTransactionResponse> {
-    const signature =
-      transaction.type === 'INVOKE_FUNCTION' && formatSignature(transaction.signature);
-    const contract_address_salt =
-      transaction.type === 'DEPLOY' && toHex(toBN(transaction.contract_address_salt));
-
-    const { data } = await axios.post<AddTransactionResponse>(
-      urljoin(this.gatewayUrl, 'add_transaction'),
-      stringify({
-        ...transaction, // the tx can contain BigInts, so we use our own `stringify`
-        ...(Array.isArray(signature) && { signature }), // not needed on deploy tx
-        ...(contract_address_salt && { contract_address_salt }), // not needed on invoke tx
-      }),
-      { headers: { 'Content-Type': 'application/json' } }
-    );
-    return data;
+  public async getTransaction(txHash: BigNumberish): Promise<GetTransactionResponse> {
+    const txHashHex = toHex(toBN(txHash));
+    return this.fetchEndpoint('get_transaction', { transactionHash: txHashHex });
   }
 
   /**
@@ -250,27 +291,31 @@ export class Provider implements ProviderInterface {
    * @returns a confirmation of sending a transaction on the starknet contract
    */
   public deployContract(
-    contract: CompiledContract | string,
-    constructorCalldata: string[] = [],
-    addressSalt: BigNumberish = randomAddress()
+    payload: DeployContractPayload,
+    _abi?: Abi
   ): Promise<AddTransactionResponse> {
     const parsedContract =
-      typeof contract === 'string' ? (parse(contract) as CompiledContract) : contract;
+      typeof payload.contract === 'string'
+        ? (parse(payload.contract) as CompiledContract)
+        : payload.contract;
     const contractDefinition = {
       ...parsedContract,
       program: compressProgram(parsedContract.program),
     };
 
-    return this.addTransaction({
+    return this.fetchEndpoint('add_transaction', undefined, {
       type: 'DEPLOY',
-      contract_address_salt: addressSalt,
-      constructor_calldata: constructorCalldata,
+      contract_address_salt: payload.addressSalt ?? randomAddress(),
+      constructor_calldata: bigNumberishArrayToDecimalStringArray(
+        payload.constructorCalldata ?? []
+      ),
       contract_definition: contractDefinition,
     });
   }
 
   /**
    * 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
@@ -278,18 +323,13 @@ export class Provider implements ProviderInterface {
    * @param signature - (optional) signature to send along
    * @returns response from addTransaction
    */
-  public invokeFunction(
-    contractAddress: string,
-    entrypointSelector: string,
-    calldata?: string[],
-    signature?: Signature
-  ): Promise<AddTransactionResponse> {
-    return this.addTransaction({
+  public invokeFunction(invocation: Invocation, _abi?: Abi): Promise<AddTransactionResponse> {
+    return this.fetchEndpoint('add_transaction', undefined, {
       type: 'INVOKE_FUNCTION',
-      contract_address: contractAddress,
-      entry_point_selector: entrypointSelector,
-      calldata,
-      signature,
+      contract_address: invocation.contractAddress,
+      entry_point_selector: getSelectorFromName(invocation.entrypoint),
+      calldata: bigNumberishArrayToDecimalStringArray(invocation.calldata ?? []),
+      signature: bigNumberishArrayToDecimalStringArray(invocation.signature ?? []),
     });
   }
 
@@ -306,7 +346,10 @@ 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;
       }

package/src/provider/interface.ts

@@ -1,15 +1,15 @@
 import type {
   AddTransactionResponse,
+  Call,
   CallContractResponse,
-  CallContractTransaction,
-  CompiledContract,
+  DeployContractPayload,
   GetBlockResponse,
   GetCodeResponse,
   GetContractAddressesResponse,
   GetTransactionResponse,
   GetTransactionStatusResponse,
-  Signature,
-  Transaction,
+  Invocation,
+  TransactionReceipt,
 } from '../types';
 import type { BigNumberish } from '../utils/number';
 import { BlockIdentifier } from './utils';
@@ -34,12 +34,12 @@ export abstract class ProviderInterface {
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L25-L39)
    *
-   * @param invokeTransaction - transaction to be invoked
-   * @param blockIdentifier - block identifier
+   * @param invokeTransaction transaction to be invoked
+   * @param blockIdentifier block identifier
    * @returns the result of the function on the smart contract.
    */
   public abstract callContract(
-    invokeTransaction: CallContractTransaction,
+    invokeTransaction: Call,
     blockIdentifier?: BlockIdentifier
   ): Promise<CallContractResponse>;
 
@@ -48,7 +48,7 @@ export abstract class ProviderInterface {
    *
    * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L41-L53)
    *
-   * @param blockIdentifier - block identifier
+   * @param blockIdentifier block identifier
    * @returns the block object { block_number, previous_block_number, state_root, status, timestamp, transaction_receipts, transactions }
    */
   public abstract getBlock(blockIdentifier?: BlockIdentifier): Promise<GetBlockResponse>;
@@ -104,44 +104,38 @@ export abstract class ProviderInterface {
    */
   public abstract getTransaction(txHash: BigNumberish): Promise<GetTransactionResponse>;
 
-  /**
-   * Invoke a function on the starknet contract
-   *
-   * [Reference](https://github.com/starkware-libs/cairo-lang/blob/f464ec4797361b6be8989e36e02ec690e74ef285/src/starkware/starknet/services/api/gateway/gateway_client.py#L13-L17)
-   *
-   * @param transaction - transaction to be invoked
-   * @returns a confirmation of invoking a function on the starknet contract
-   */
-  public abstract addTransaction(transaction: Transaction): Promise<AddTransactionResponse>;
+  public abstract getTransactionReceipt({
+    txHash,
+    txId,
+  }: {
+    txHash?: BigNumberish;
+    txId?: BigNumberish;
+  }): Promise<TransactionReceipt>;
 
   /**
    * Deploys a given compiled contract (json) to starknet
    *
-   * @param contract - a json object containing the compiled contract
-   * @param address - (optional, defaults to a random address) the address where the contract should be deployed (alpha)
+   * @param payload payload to be deployed containing:
+   * - compiled contract code
+   * - constructor calldata
+   * - address salt
    * @returns a confirmation of sending a transaction on the starknet contract
    */
-  public abstract deployContract(
-    contract: CompiledContract | string,
-    constructorCalldata: string[],
-    addressSalt: BigNumberish
-  ): Promise<AddTransactionResponse>;
+  public abstract deployContract(payload: DeployContractPayload): Promise<AddTransactionResponse>;
 
   /**
    * Invokes a function on starknet
+   * @deprecated This method wont be supported as soon as fees are mandatory
+   *
+   * @param invocation the invocation object containing:
+   * - contractAddress - the address of the contract
+   * - entrypoint - the entrypoint of the contract
+   * - calldata - (defaults to []) the calldata
+   * - signature - (defaults to []) the signature
    *
-   * @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 abstract invokeFunction(
-    contractAddress: string,
-    entrypointSelector: string,
-    calldata?: string[],
-    signature?: Signature
-  ): Promise<AddTransactionResponse>;
+  public abstract invokeFunction(invocation: Invocation): Promise<AddTransactionResponse>;
 
   public abstract waitForTx(txHash: BigNumberish, retryInterval?: number): Promise<void>;
 }

package/src/provider/utils.ts

@@ -2,21 +2,31 @@ import type { BlockNumber } from '../types';
 import { BigNumberish, toBN, toHex } from '../utils/number';
 
 /**
- * TODO
+ *
  * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L148-L153)
  *
  * @param hashValue
  * @param hashField
  */
-export function formatHash() {}
+export function formatHash(hashValue: BigNumberish): string {
+  if (typeof hashValue === 'string') return hashValue;
+  return toHex(toBN(hashValue));
+}
 
 /**
- * TODO
+ *
  * [Reference](https://github.com/starkware-libs/cairo-lang/blob/fc97bdd8322a7df043c87c371634b26c15ed6cee/src/starkware/starknet/services/api/feeder_gateway/feeder_gateway_client.py#L156-L161)
  * @param txHash
  * @param txId
  */
-export function txIdentifier() {}
+export function txIdentifier(txHash?: BigNumberish, txId?: BigNumberish): string {
+  if (!txHash) {
+    return `transactionId=${JSON.stringify(txId)}`;
+  }
+  const hashString = formatHash(txHash);
+
+  return `transactionHash=${hashString}`;
+}
 
 // hex string and BN are detected as block hashes
 // decimal string and number are detected as block numbers
@@ -69,7 +79,7 @@ export function getFormattedBlockIdentifier(blockIdentifier: BlockIdentifier = n
     return '';
   }
   if (blockIdentifierObject.type === 'BLOCK_NUMBER') {
-    return `?blockNumber=${blockIdentifierObject.data}`;
+    return `blockNumber=${blockIdentifierObject.data}`;
   }
-  return `?blockHash=${toHex(toBN(blockIdentifierObject.data))}`;
+  return `blockHash=${toHex(toBN(blockIdentifierObject.data))}`;
 }