Abstract Provider

[badurinantun]

This is the draft proposal of the abstract Provider class after going through the specifications for both the RPC and Starknet API specifications.

Starknet RPC API spec: https://github.com/starkware-libs/starknet-specs
Current Gateway API: https://github.com/starkware-libs/cairo-lang/tree/master/src/starkware/starknet/services/api

This proposal is incomplete and will change, I wanted to post is as soon as possible to get the ball rolling.

import BN from 'bn.js';

export type BigNumberish = string | number | BN;

type BlockNumber = 'pending' | 'latest' | null | number;

type BlockIdentifier = BlockNumber | BigNumberish;

type Status =
  | 'NOT_RECEIVED'
  | 'RECEIVED'
  | 'PENDING'
  | 'ACCEPTED_ON_L2'
  | 'ACCEPTED_ON_L1'
  | 'REJECTED';

/**
 * getBlock response object
 *
 * RPC provider has a "request_scope" param which can be either sequencer_address TXN_HASH,
 * FULL_TXNS, FULL_TXN_AND_RECEIPTS.
 * We can either defualt to to FULL_TXN_AND_RECEIPTS or use the "request_scope" param
 * to specify the scope and parse the default provider response accordingly.
 *
 * "old_root" property is missing from the default provider response.
 */

interface GetBlockResponse {
  acceptedTime: number; // "timestamp"
  blockHash: string;
  blockNumber: number;
  gasPrice: string;
  newRoot: string; // "state_root"
  oldRoot?: string; // missing
  parentHash: string; // "parent_block_hash"
  sequencer: string; // "sequencer_address"
  status: Status;
  transactions: Array<unknown>;
}

/**
 * getStateUpdate response object
 */

interface GetStateUpdateResponse {
  blockHash: string;
  newRoot: string;
  oldRoot: string;
  acceptedTime?: number; // missing on the default provider
  stateDiff: {
    storageDiffs: Array<{
      address: string;
      key: string;
      value: string;
    }>;
    deployedContracts: Array<{
      address: string;
      contractHash: string;
    }>;
    nonces?: Array<{
      contractAddress: string;
      nonce: BigNumberish;
    }>; // missing on the default provider
  };
}

/**
 * getTransaction response object
 * Responses differ here from the default provider.
 * Default parser response should be parsed to fit the RPC response.
 */
type GetTransactionResponse = InvokeTransactionResponse | DeclareTransactionResponse;

interface CommonTransactionResponse {
  transactionHash: string;
  maxFee: string;
  version: string;
  signature: Array<string>;
}

interface InvokeTransactionResponse extends CommonTransactionResponse {
  contractAddress: string;
  entryPointSelector: string;
  calldata: Array<string>;
}

/**
 * getTransactionReceipt response object
 */

interface ContractEntryPoint {
  offset: string;
  selector: string;
}

interface ContractClass {
  program: string;
  entryPointByType: {
    CONSTRUCTOR: Array<ContractEntryPoint>;
    EXTERNAL: Array<ContractEntryPoint>;
    L1_HANDLER: Array<ContractEntryPoint>;
  };
}

interface DeclareTransactionResponse extends CommonTransactionResponse {
  contractClass: ContractClass;
  senderAddress: string;
}

type GetTransactionReceiptResponse =
  | InvokeTransactionReceiptResponse
  | DeclareTransactionReceiptResponse;

interface CommonTransactionReceiptResponse {
  transactionHash: string;
  actualFee: string;
  status: Status;
  // status_data: string; // missing
}

interface MessageToL1 {
  toAddress: string;
  payload: Array<string>;
}

interface Event {
  fromAddress: string;
  keys: Array<string>;
  data: Array<string>;
}

interface MessageToL2 {
  fromAddress: string;
  payload: Array<string>;
}

export interface InvokeTransactionReceiptResponse extends CommonTransactionReceiptResponse {
  messagesSent: Array<MessageToL1>;
  events: Array<Event>;
  l1OriginMessage?: MessageToL2;
}

type DeclareTransactionReceiptResponse = CommonTransactionReceiptResponse;

/**
 * estimateFee response object
 *
 * There is a large difference between the default provider and the RPC provider.
 */

interface FeeEstimateResponse {
  // gasConsumed: BigNumberish; // missing from the default provider
  // gasPrice: BigNumberish; // missing from the default provider
  overallFee: BigNumberish; // in wei
}

interface FunctionCall {
  contractAddress: string;
  entry_point_selector: BigNumberish;
  calldata: Array<BigNumberish>;
}

interface InvokeResponse {
  transactionHash: string;
}

interface DeployResponse {
  contractAddress: string;
  transactionHash: string;
}

interface DeclareResponse {
  transactionHash: string;
  classHash: string;
}

export abstract class Provider {
  // Get block information given the block hash or number
  abstract getBlock(blockIdentifier: BlockIdentifier): Promise<GetBlockResponse>;

  // Get the information about the result of executing the requested block
  abstract getStateUpdate(blockHash: BigNumberish): Promise<GetStateUpdateResponse>;

  // Get the value of the storage at the given address and key
  abstract getStorageAt(
    contractAddress: string,
    key: BigNumberish,
    blockIdentifier: BlockIdentifier
  ): Promise<BigNumberish>;

  // Get the details of a submitted transaction
  abstract getTransaction(txHash: BigNumberish): Promise<GetTransactionResponse>;

  // Get the transaction receipt by the transaction hash
  abstract getTransactionReceipt(txHash: BigNumberish): Promise<GetTransactionReceiptResponse>;

  // Get the contract class deployed under the given class hash.
  abstract getClass(classHash: BigNumberish): Promise<ContractClass>;

  // Get the contract class deployed under the given address.
  abstract getClassAt(contractAddress: BigNumberish): Promise<ContractClass>;

  // Get the class hash deployed under the given address.
  abstract getClassHash(contractAddress: BigNumberish): Promise<string>;

  // Estimates the resources required by a transaction relative to a given state
  abstract estimateFee(
    request: FunctionCall,
    blockHash: BigNumberish
  ): Promise<FeeEstimateResponse>;

  abstract call(request: FunctionCall, blockHash: BigNumberish): Promise<Array<BigNumberish>>;

  abstract invoke(
    functionInvocation: FunctionCall,
    signature?: Array<BigNumberish>,
    maxFee?: BigNumberish,
    version?: BigNumberish
  ): Promise<InvokeResponse>;

  abstract deploy(
    contractDefinition: ContractClass,
    constructorCalldata: Array<BigNumberish>,
    salt?: BigNumberish
  ): Promise<DeployResponse>;

  abstract declare(contractClass: ContractClass, version?: BigNumberish): Promise<DeclareResponse>;
}

[bbrandtom]

Just a comment, and sorry if this is not clear, the StarkNet API is the JSON-RPC spec you are linking to. The 2nd link, https://github.com/starkware-libs/cairo-lang/tree/master/src/starkware/starknet/services/api, is our current gateway API.

The goal is to transition everything to work with the JSON-RPC spec and to deprecate the gateway API at some point.