koilib 5.7.0 → 7.0.0

package/src/Signer.ts

@@ -2,6 +2,7 @@
 import { sha256 } from "@noble/hashes/sha256";
 import * as secp from "@noble/secp256k1";
 import { Provider } from "./Provider";
+import { Transaction } from "./Transaction";
 import {
   TransactionJson,
   TransactionJsonWait,
@@ -11,6 +12,7 @@ import {
   TypeField,
   TransactionReceipt,
   SendTransactionOptions,
+  ResourceCreditsOptions,
 } from "./interface";
 import {
   bitcoinAddress,
@@ -139,11 +141,6 @@ export class Signer implements SignerInterface {
    */
   address: string;
 
-  /**
-   * Chain id
-   */
-  chainId = "";
-
   /**
    * Provider to connect with the blockchain
    */
@@ -156,6 +153,33 @@ 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]]
@@ -164,6 +188,8 @@ export class Signer implements SignerInterface {
    * @param privateKey - Private key as hexstring, bigint or Uint8Array
    * @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";
@@ -171,13 +197,46 @@ 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;
-    chainId?: string;
     provider?: Provider;
     sendOptions?: SendTransactionOptions;
+    rcOptions?: ResourceCreditsOptions;
   }) {
     this.compressed = typeof c.compressed === "undefined" ? true : c.compressed;
     this.privateKey = c.privateKey;
@@ -189,11 +248,20 @@ export class Signer implements SignerInterface {
       this.publicKey = secp.getPublicKey(c.privateKey, this.compressed);
       this.address = bitcoinAddress(this.publicKey);
     }
-    if (c.chainId) this.chainId = c.chainId;
     this.sendOptions = {
       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))
+          )
+        ),
+    };
   }
 
   /**
@@ -324,6 +392,18 @@ 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));
@@ -386,6 +466,45 @@ 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

package/src/Transaction.ts

@@ -7,6 +7,7 @@ import {
   Abi,
   OperationJson,
   SendTransactionOptions,
+  TransactionHeaderJson,
   TransactionJson,
   TransactionOptions,
   TransactionReceipt,
@@ -137,7 +138,7 @@ export class Transaction {
    * @example
    * ```ts
    * const koin = new Contract({
-   *   id: "19JntSm8pSNETT9aHTwAUHC5RMoaSmgZPJ",
+   *   id: "15DJN4a8SgrbGhhGksSBASiSYjGnMU8dGL",
    *   abi: utils.tokenAbi,
    * }).functions;
    * const signer = Signer.fromSeed("my seed");
@@ -216,6 +217,19 @@ export class Transaction {
     this.transaction.operations.push(operation);
   }
 
+  static computeTransactionId(txHeader: TransactionHeaderJson): string {
+    const headerDecoded = btypeDecode(txHeader, btypeTransactionHeader!, false);
+    const message = koinos.protocol.transaction_header.create(headerDecoded);
+    const headerBytes = koinos.protocol.transaction_header
+      .encode(message)
+      .finish() as Uint8Array;
+
+    const hash = sha256(headerBytes);
+
+    // multihash 0x1220. 12: code sha2-256. 20: length (32 bytes)
+    return `0x1220${toHexString(hash)}`;
+  }
+
   /**
    * Function to prepare a transaction
    * @param tx - Do not set the nonce to get it from the blockchain
@@ -303,25 +317,12 @@ export class Transaction {
       // TODO: Option to resolve names (payer, payee)
     };
 
-    const headerDecoded = btypeDecode(
-      tx.header,
-      btypeTransactionHeader!,
-      false
-    );
-    const message = koinos.protocol.transaction_header.create(headerDecoded);
-    const headerBytes = koinos.protocol.transaction_header
-      .encode(message)
-      .finish() as Uint8Array;
-
-    const hash = sha256(headerBytes);
-
-    // multihash 0x1220. 12: code sha2-256. 20: length (32 bytes)
-    tx.id = `0x1220${toHexString(hash)}`;
+    tx.id = Transaction.computeTransactionId(tx.header);
     return tx;
   }
 
   /**
-   * Functon to prepare the transaction (set headers, merkle
+   * Function to prepare the transaction (set headers, merkle
    * root, etc)
    */
   async prepare(options?: TransactionOptions): Promise<TransactionJson> {

package/src/interface.ts

@@ -231,6 +231,39 @@ 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
@@ -472,6 +505,11 @@ export type WaitFunction = (
   blockNumber?: number;
 }>;
 
+export interface GetBlockOptions {
+  returnBlock?: boolean;
+  returnReceipt?: boolean;
+}
+
 export interface GenesisDataEntryEncoded {
   space: {
     system?: boolean;