koilib 7.1.1 → 8.1.0

package/src/Provider.ts

@@ -7,6 +7,7 @@ import {
   TransactionJsonWait,
   BlockTopology,
   GetBlockOptions,
+  BlockReceipt,
 } from "./interface";
 // eslint-disable-next-line @typescript-eslint/ban-ts-comment
 // @ts-ignore
@@ -14,6 +15,116 @@ import { koinos } from "./protoModules/protocol-proto.js";
 import { decodeBase64url, encodeBase64url } from "./utils";
 import { Serializer } from "./Serializer";
 
+export interface ProviderInterface {
+  call: <T = unknown>(method: string, params: unknown) => Promise<T>;
+  getNonce: (
+    account: string,
+    deserialize?: boolean
+  ) => Promise<number | string>;
+  getNextNonce: (account: string) => Promise<string>;
+  getAccountRc: (account: string) => Promise<string>;
+  getTransactionsById: (transactionIds: string[]) => Promise<{
+    transactions: {
+      transaction: TransactionJson;
+      containing_blocks: string[];
+    }[];
+  }>;
+  getBlocksById: (
+    blockIds: string[],
+    opts?: GetBlockOptions
+  ) => Promise<{
+    block_items: {
+      block_id: string;
+      block_height: string;
+      block: BlockJson;
+      receipt: BlockReceipt;
+    }[];
+  }>;
+  getHeadInfo: () => Promise<{
+    head_block_time: string;
+    head_topology: BlockTopology;
+    head_state_merkle_root: string;
+    last_irreversible_block: string;
+  }>;
+  getChainId: () => Promise<string>;
+  getBlocks: (
+    height: number,
+    numBlocks?: number,
+    idRef?: string,
+    opts?: GetBlockOptions
+  ) => Promise<
+    {
+      block_id: string;
+      block_height: string;
+      block: BlockJson;
+      receipt: BlockReceipt;
+    }[]
+  >;
+  getBlock: (
+    height: number,
+    opts?: GetBlockOptions
+  ) => Promise<{
+    block_id: string;
+    block_height: string;
+    block: BlockJson;
+    receipt: BlockReceipt;
+  }>;
+  wait: (
+    txId: string,
+    type?: "byTransactionId" | "byBlock",
+    timeout?: number
+  ) => Promise<{
+    blockId: string;
+    blockNumber?: number;
+  }>;
+  sendTransaction: (
+    transaction: TransactionJson | TransactionJsonWait,
+    broadcast?: boolean
+  ) => Promise<{
+    receipt: TransactionReceipt;
+    transaction: TransactionJsonWait;
+  }>;
+  readContract: (operation: CallContractOperationJson) => Promise<{
+    result: string;
+    logs: string;
+  }>;
+  invokeSystemCall: <T = Record<string, unknown>>(
+    serializer: Serializer,
+    nameOrId: string | number,
+    args: Record<string, unknown>,
+    callerData?: { caller: string; caller_privilege: number }
+  ) => Promise<T>;
+
+  // optional functions
+  submitBlock?: (block: BlockJson) => Promise<Record<string, never>>;
+  getForkHeads?: () => Promise<{
+    last_irreversible_block: BlockTopology;
+    fork_heads: BlockTopology[];
+  }>;
+  getResourceLimits?: () => Promise<{
+    resource_limit_data: {
+      disk_storage_limit: string;
+      disk_storage_cost: string;
+      network_bandwidth_limit: string;
+      network_bandwidth_cost: string;
+      compute_bandwidth_limit: string;
+      compute_bandwidth_cost: string;
+    };
+  }>;
+  invokeGetContractMetadata?: (contractId: string) => Promise<{
+    value: {
+      hash: string;
+      system: boolean;
+      authorizes_call_contract: boolean;
+      authorizes_transaction_application: boolean;
+      authorizes_upload_contract: boolean;
+    };
+  }>;
+  invokeGetContractAddress?: (name: string) => Promise<{
+    value: { address: string };
+  }>;
+}
+
 /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
 
 async function sleep(ms: number): Promise<void> {
@@ -23,7 +134,7 @@ async function sleep(ms: number): Promise<void> {
 /**
  * Class to connect with the RPC node
  */
-export class Provider {
+export class Provider implements ProviderInterface {
   /**
    * Array of URLs of RPC nodes
    */
@@ -372,6 +483,7 @@ export class Provider {
       block_id: string;
       block_height: string;
       block: BlockJson;
+      receipt: BlockReceipt;
     }[];
   }> {
     return this.call("block_store.get_blocks_by_id", {
@@ -447,9 +559,7 @@ export class Provider {
       block_id: string;
       block_height: string;
       block: BlockJson;
-      block_receipt: {
-        [x: string]: unknown;
-      };
+      receipt: BlockReceipt;
     }[]
   > {
     let blockIdRef = idRef;
@@ -463,9 +573,7 @@ export class Provider {
           block_id: string;
           block_height: string;
           block: BlockJson;
-          block_receipt: {
-            [x: string]: unknown;
-          };
+          receipt: BlockReceipt;
         }[];
       }>("block_store.get_blocks_by_height", {
         head_block_id: blockIdRef,
@@ -555,9 +663,7 @@ export class Provider {
     block_id: string;
     block_height: string;
     block: BlockJson;
-    block_receipt: {
-      [x: string]: unknown;
-    };
+    receipt: BlockReceipt;
   }> {
     return (await this.getBlocks(height, 1, undefined, opts))[0];
   }
@@ -835,7 +941,7 @@ export class Provider {
 
   /**
    * Function to get the contract metadata of a specific contract.
-   * @param contractId contract ID
+   * @param contractId - contract ID
    *
    * @example
    * ```ts
@@ -912,10 +1018,74 @@ export class Provider {
         returnTypeName: "get_contract_metadata_result",
       }
     );
-    return this.invokeSystemCall(serializer, "get_contract_metadata", {
+    return this.invokeSystemCall<{
+      value: {
+        hash: string;
+        system: boolean;
+        authorizes_call_contract: boolean;
+        authorizes_transaction_application: boolean;
+        authorizes_upload_contract: boolean;
+      };
+    }>(serializer, "get_contract_metadata", {
       contract_id: contractId,
     });
   }
+
+  /**
+   * Function to get the address of a system contract
+   * @param name - contract name
+   *
+   * @example
+   * * ```ts
+   * const provider = new Provider("https://api.koinos.io");
+   * const result = await provider.invokeGetContractAddress("koin");
+   * console.log(result);
+   *
+   * // { value: { address: '15DJN4a8SgrbGhhGksSBASiSYjGnMU8dGL' } }
+   * ```
+   */
+  async invokeGetContractAddress(name: string) {
+    const serializer = new Serializer(
+      {
+        nested: {
+          get_address_arguments: {
+            fields: {
+              name: {
+                type: "string",
+                id: 1,
+              },
+            },
+          },
+          get_address_result: {
+            fields: {
+              value: {
+                type: "address_record",
+                id: 1,
+              },
+            },
+          },
+          address_record: {
+            fields: {
+              address: {
+                type: "bytes",
+                id: 1,
+                options: {
+                  "(koinos.btype)": "ADDRESS",
+                },
+              },
+            },
+          },
+        },
+      },
+      {
+        argumentsTypeName: "get_address_arguments",
+        returnTypeName: "get_address_result",
+      }
+    );
+    return this.invokeSystemCall<{
+      value: { address: string };
+    }>(serializer, "get_contract_address", { name });
+  }
 }
 
 export default Provider;

package/src/Signer.ts

@@ -1,8 +1,7 @@
 /* eslint-disable no-param-reassign, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 import { sha256 } from "@noble/hashes/sha256";
 import * as secp from "@noble/secp256k1";
-import { Provider } from "./Provider";
-import { Transaction } from "./Transaction";
+import { ProviderInterface } from "./Provider";
 import {
   TransactionJson,
   TransactionJsonWait,
@@ -12,7 +11,6 @@ import {
   TypeField,
   TransactionReceipt,
   SendTransactionOptions,
-  ResourceCreditsOptions,
 } from "./interface";
 import {
   bitcoinAddress,
@@ -30,7 +28,7 @@ import {
 import { koinos } from "./protoModules/protocol-proto.js";
 
 export interface SignerInterface {
-  provider?: Provider;
+  provider?: ProviderInterface;
   getAddress: (compressed?: boolean) => string;
   signHash: (hash: Uint8Array) => Promise<Uint8Array>;
   signMessage: (message: string | Uint8Array) => Promise<Uint8Array>;
@@ -144,7 +142,7 @@ export class Signer implements SignerInterface {
   /**
    * Provider to connect with the blockchain
    */
-  provider?: Provider;
+  provider?: ProviderInterface;
 
   /**
    * Options to apply when sending a transaction.
@@ -153,33 +151,6 @@ export class Signer implements SignerInterface {
    */
   sendOptions?: SendTransactionOptions;
 
-  /**
-   * Options related to the estimation of the rcLimit.
-   * By default the estimation is enabled and increased
-   * by 10%.
-   *
-   * @example
-   * This code estimates the mana by multiplying the rc_used
-   * by 2.
-   * ```ts
-   * const signer = new Signer({
-   *   privateKey,
-   *   provider,
-   *   rcOptions: {
-   *     estimateRc: true,
-   *     adjustRcLimit: (receipt) => 2 * Number(receipt.rc_used),
-   *   },
-   * });
-   *
-   * // you can also update rcOptions
-   * signer.rcOptions = {
-   *   estimateRc: true,
-   *   adjustRcLimit: (receipt) => 2 * Number(receipt.rc_used),
-   * }
-   * ```
-   */
-  rcOptions: ResourceCreditsOptions;
-
   /**
    * The constructor receives de private key as hexstring, bigint or Uint8Array.
    * See also the functions [[Signer.fromWif]] and [[Signer.fromSeed]]
@@ -189,7 +160,6 @@ export class Signer implements SignerInterface {
    * @param compressed - compressed format is true by default
    * @param provider - provider to connect with the blockchain
    * @param sendOptions - Send options
-   * @param rcOptions - options for mana estimation
    * @example
    * ```ts
    * const privateKey = "ec8601a24f81decd57f4b611b5ac6eb801cb3780bb02c0f9cdfe9d09daaddf9c";
@@ -197,46 +167,12 @@ export class Signer implements SignerInterface {
    * console.log(signer.getAddress());
    * // 1MbL6mG8ASAvSYdoMnGUfG3ZXkmQ2dpL5b
    * ```
-   *
-   * By default the mana is estimated as 110% the mana used. This
-   * estimation is computed using the "broadcast:false" option.
-   * For instance, if the transaction consumes 1 mana, the rc_limit
-   * will be set to 1.1 mana.
-   *
-   * You can also adjust the rc limit.
-   * @example
-   * ```ts
-   * const privateKey = "ec8601a24f81decd57f4b611b5ac6eb801cb3780bb02c0f9cdfe9d09daaddf9c";
-   * cons signer = new Signer({
-   *   privateKey,
-   *   provider,
-   *   rcOptions: {
-   *     estimateRc: true,
-   *     // use 2 times rc_used as rc_limit
-   *     adjustRcLimit: (r) => 2 * Number(r.rc_used),
-   *   },
-   * });
-   * ```
-   *
-   * The rpc node must be highly trusted because the transaction
-   * is signed during the estimation of the mana. You can also
-   * disable the mana estimation:
-   * @example
-   * ```ts
-   * const privateKey = "ec8601a24f81decd57f4b611b5ac6eb801cb3780bb02c0f9cdfe9d09daaddf9c";
-   * cons signer = new Signer({
-   *   privateKey,
-   *   provider,
-   *   rcOptions: { estimateRc: false },
-   * });
-   * ```
    */
   constructor(c: {
     privateKey: string | number | bigint | Uint8Array;
     compressed?: boolean;
-    provider?: Provider;
+    provider?: ProviderInterface;
     sendOptions?: SendTransactionOptions;
-    rcOptions?: ResourceCreditsOptions;
   }) {
     this.compressed = typeof c.compressed === "undefined" ? true : c.compressed;
     this.privateKey = c.privateKey;
@@ -252,16 +188,6 @@ export class Signer implements SignerInterface {
       broadcast: true,
       ...c.sendOptions,
     };
-    this.rcOptions = c.rcOptions ?? {
-      estimateRc: true,
-      adjustRcLimit: (receipt) =>
-        Promise.resolve(
-          Math.min(
-            Number(receipt.max_payer_rc),
-            Math.floor(1.1 * Number(receipt.rc_used))
-          )
-        ),
-    };
   }
 
   /**
@@ -392,18 +318,6 @@ export class Signer implements SignerInterface {
   ): Promise<TransactionJson> {
     if (!tx.id) throw new Error("Missing transaction id");
 
-    // estimation of rcLimit
-    if (
-      this.rcOptions.estimateRc &&
-      (!tx.signatures || tx.signatures.length === 0)
-    ) {
-      const receipt = await this.estimateReceipt(tx);
-      tx.header!.rc_limit = this.rcOptions.adjustRcLimit
-        ? await this.rcOptions.adjustRcLimit(receipt)
-        : receipt.rc_used;
-      tx.id = Transaction.computeTransactionId(tx.header!);
-    }
-
     // multihash 0x1220. 12: code sha2-256. 20: length (32 bytes)
     // tx id is a stringified multihash, need to extract the hash digest only
     const hash = toUint8Array(tx.id.slice(6));
@@ -466,45 +380,6 @@ export class Signer implements SignerInterface {
     return this.provider.sendTransaction(transaction, opts.broadcast);
   }
 
-  /**
-   * Estimate the receipt associated to the transaction if
-   * it sent to the blockchain. It is useful to estimate the
-   * consumption of mana.
-   * The transaction is signed during this process and sent
-   * to the rpc node with the "broadcast:false" option to
-   * just compute the transaction without broadcasting it to
-   * the network.
-   * After that, the initial signatures are restored (if any)
-   * and the ones used for the estimation will be removed.
-   */
-  async estimateReceipt(
-    tx: TransactionJson | TransactionJsonWait
-  ): Promise<TransactionReceipt> {
-    if (!tx.id) throw new Error("Missing transaction id");
-    if (!tx.signatures) tx.signatures = [];
-    const signaturesCopy = [...tx.signatures];
-
-    // sign if there are no signatures
-    if (tx.signatures.length === 0) {
-      const hash = toUint8Array(tx.id.slice(6));
-      const signature = await this.signHash(hash);
-      tx.signatures.push(encodeBase64url(signature));
-    }
-
-    try {
-      const { receipt } = await this.sendTransaction(tx, {
-        broadcast: false,
-      });
-      // restore signatures
-      tx.signatures = signaturesCopy;
-      return receipt;
-    } catch (error) {
-      // restore signatures
-      tx.signatures = signaturesCopy;
-      throw error;
-    }
-  }
-
   /**
    * Function to recover the public key from hash and signature
    * @param hash - hash sha256
@@ -596,7 +471,7 @@ export class Signer implements SignerInterface {
    *  });
    * ```
    */
-  async recoverPublicKeys(
+  static async recoverPublicKeys(
     txOrBlock: TransactionJson | BlockJson,
     opts?: RecoverPublicKeyOptions
   ): Promise<string[]> {
@@ -696,7 +571,7 @@ export class Signer implements SignerInterface {
    *  });
    * ```
    */
-  async recoverAddresses(
+  static async recoverAddresses(
     txOrBlock: TransactionJson | BlockJson,
     opts?: RecoverPublicKeyOptions
   ): Promise<string[]> {

package/src/Transaction.ts

@@ -1,7 +1,7 @@
 /* eslint-disable no-param-reassign, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment */
 import { sha256 } from "@noble/hashes/sha256";
 import { Contract } from "./Contract";
-import { Provider } from "./Provider";
+import { ProviderInterface } from "./Provider";
 import { SignerInterface } from "./Signer";
 import {
   Abi,
@@ -90,7 +90,7 @@ export class Transaction {
   /**
    * Provider to connect with the blockchain
    */
-  provider?: Provider;
+  provider?: ProviderInterface;
 
   /**
    * Transaction
@@ -109,7 +109,8 @@ export class Transaction {
 
   constructor(c?: {
     signer?: SignerInterface;
-    provider?: Provider;
+    provider?: ProviderInterface;
+    transaction?: TransactionJson;
     options?: TransactionOptions;
   }) {
     this.signer = c?.signer;
@@ -128,6 +129,7 @@ export class Transaction {
         ...(c?.options?.payee && { payee: c.options.payee }),
       },
       operations: [],
+      ...c?.transaction,
     };
   }
 
@@ -146,14 +148,17 @@ export class Transaction {
    * signer.provider = provider;
    * const tx = new Transaction({ signer });
    *
-   * // method 1
+   * // Method 1 (using 2 arguments)
+   * // note that with 2 arguments it is not necessary to
+   * // set "onlyOperation: true". For the rest of the
+   * // methods it's necessary to do that.
    * await tx.pushOperation(koin.transfer, {
    *   from: "1NRYHBYr9qxYQAeVqfdSvyjJemRQ4qD3Mt",
    *   to: "13UdKjYuzfBYbB6bGLQkUN9DJRFPCmG1mU",
    *   value: "1000",
    * });
    *
-   * // method 2
+   * // Method 2
    * await tx.pushOperation(
    *   koin.transfer({
    *     from: "1NRYHBYr9qxYQAeVqfdSvyjJemRQ4qD3Mt",
@@ -164,7 +169,7 @@ export class Transaction {
    *   })
    * );
    *
-   * // method 3
+   * // Method 3
    * await tx.pushOperation(
    *   await koin.transfer({
    *     from: "1NRYHBYr9qxYQAeVqfdSvyjJemRQ4qD3Mt",
@@ -175,7 +180,7 @@ export class Transaction {
    *   })
    * );
    *
-   * // method 4
+   * // Method 4
    * const { operation } = await koin.transfer({
    *   from: "1NRYHBYr9qxYQAeVqfdSvyjJemRQ4qD3Mt",
    *   to: "13UdKjYuzfBYbB6bGLQkUN9DJRFPCmG1mU",
@@ -240,7 +245,7 @@ export class Transaction {
    */
   static async prepareTransaction(
     tx: TransactionJson,
-    provider?: Provider,
+    provider?: ProviderInterface,
     payer?: string
   ): Promise<TransactionJson> {
     if (!tx.header) {
@@ -347,6 +352,22 @@ export class Transaction {
     return this.transaction;
   }
 
+  /**
+   * Update the rc limit with a new value and update the
+   * transaction ID accordingly. The signatures will be removed
+   * if the transaction ID changed
+   */
+  adjustRcLimit(newRcLimit: string | number): void {
+    if (!this.transaction.header)
+      throw new Error("transaction header not defined");
+    this.transaction.header.rc_limit = newRcLimit;
+    const newTxId = Transaction.computeTransactionId(this.transaction.header);
+    if (this.transaction.id !== newTxId) {
+      this.transaction.signatures = [];
+    }
+    this.transaction.id = newTxId;
+  }
+
   /**
    * Function to sign the transaction
    */

package/src/interface.ts

@@ -231,39 +231,6 @@ export interface DecodedOperationJson {
   args?: Record<string, unknown>;
 }
 
-export interface ResourceCreditsOptions {
-  /**
-   * Boolean to define if the mana should be estimated
-   * and the rcLimit be updated before signing the transaction.
-   * It is true by default
-   */
-  estimateRc?: boolean;
-
-  /**
-   * Function to adjust the rc limit after the estimation.
-   * It is useful to give an extra margin to the rc limit.
-   * By default the Signer will use a function that increases
-   * the rcLimit by 10% with respect to the estimation.
-   *
-   * @example
-   * ```ts
-   * const signer = Signer.fromWif("Kab...");
-   * signer.rcOptions = {
-   *   estimateRc: true,
-   *   adjustRcLimit: async (receipt) => {
-   *     return Math.min(
-   *       Number(receipt.max_payer_rc),
-   *       Math.floor(1.1 * Number(receipt.rc_used))
-   *     );
-   *   },
-   * }
-   * ```
-   */
-  adjustRcLimit?: (
-    receipt: TransactionReceipt
-  ) => Promise<string | number> | string | number;
-}
-
 export interface SendTransactionOptions {
   /**
    * Broadcast
@@ -821,3 +788,17 @@ export interface TransactionReceipt {
   logs: string[];
   rpc_error?: unknown;
 }
+
+export interface BlockReceipt {
+  id: string;
+  height: string;
+  disk_storage_used: string;
+  network_bandwidth_used: string;
+  compute_bandwidth_used: string;
+  disk_storage_charged: string;
+  network_bandwidth_charged: string;
+  compute_bandwidth_charged: string;
+  events: EventData[];
+  transaction_receipts: TransactionReceipt[];
+  state_delta_entries: StateDeltaEntry[];
+}