koilib 1.5.0 → 2.3.0

package/lib/Contract.d.ts

@@ -1,230 +1,153 @@
-import { Abi } from "./abi";
+import { Signer, SignerInterface } from "./Signer";
+import { Provider } from "./Provider";
+import { Serializer } from "./Serializer";
+import { CallContractOperationNested, UploadContractOperationNested, TransactionJson, Abi, TransactionOptions, DecodedOperationJson, SendTransactionResponse } from "./interface";
 /**
- * These entries definitions are used to serialize and deserialize
- * contract operations. Each entry contains a name (defined in the
- * key field), id (entry point id), inputs (abi describing the
- * serialization of the inputs), and outputs (abi describing the
- * serialization of the outputs). See [[Abi]].
- *
- * @example
- * ```ts
- * const entries = {
- *   transfer: {
- *     id: 0x62efa292,
- *     inputs: {
- *       type: [
- *         {
- *           name: "from",
- *           type: "string",
- *         },
- *         {
- *           name: "to",
- *           type: "string",
- *         },
- *         {
- *           name: "value",
- *           type: "uint64",
- *         },
- *       ],
- *     },
- *   },
- *   balance_of: {
- *     id: 0x15619248,
- *     inputs: { type: "string" },
- *     outputs: { type: "uint64" },
- *   },
- * };
- * ```
- */
-export interface Entries {
-    /** Name of the entry */
-    [x: string]: {
-        /** Entry point ID */
-        id: number;
-        /** ABI definition for input serialization */
-        inputs: Abi;
-        /** ABI definition for output serialization */
-        outputs?: Abi;
-    };
-}
-/**
- * Operation using the format for the communication with the RPC node
- *
- * @example
- * ```ts
- * const opEncoded = {
- *   type: "koinos::protocol::call_contract_operation",
- *   value: {
- *     contract_id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
- *     entry_point: 0x62efa292,
- *     args: "MBWFsaWNlA2JvYgAAAAAAAAPo",
- *   }
- * }
- * ```
- */
-export interface EncodedOperation {
-    /** It should be "koinos::protocol::call_contract_operation" */
-    type: string;
-    /** Value of call contract operation */
-    value: {
-        /** Contract ID */
-        contract_id: string;
-        /** Entry point ID */
-        entry_point: number;
-        /** Arguments serialized and encoded in base64 */
-        args?: string;
-    };
-}
-/**
- * Human readable format operation
- *
- * @example
- * ```ts
- * const opDecoded = {
- *   name: "transfer",
- *   args: {
- *     from: "1Krs7v1rtpgRyfwEZncuKMQQnY5JhqXVSx",
- *     to: "1BqtgWBcqm9cSZ97avLGZGJdgso7wx6pCA",
- *     value: 1000,
- *   },
- * };
- * ```
- */
-export interface DecodedOperation {
-    /** Operation name */
-    name: string;
-    /** Arguments decoded. See [[Abi]] */
-    args: unknown;
-}
-/**
- * The contract class contains the contract ID and contrac entries
+ * The contract class contains the contract ID and contract entries
  * definition needed to encode/decode operations during the
  * interaction with the user and the communication with the RPC node.
  *
- * Operations are encoded to communicate with the RPC node. However,
- * this format is not human readable as the data is serialized and
- * encoded in Base64 format. When decoding operations, they can be
- * read by the user (see [[EncodedOperation]] and [[DecodedOperation]]).
- *
  * @example
  *
  * ```ts
- * const contract = new Contract({
- *   id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
- *   entries: {
- *     transfer: {
- *       id: 0x62efa292,
- *       inputs: {
- *         type: [
- *           {
- *             name: "from",
- *             type: "string",
- *           },
- *           {
- *             name: "to",
- *             type: "string",
- *           },
- *           {
- *             name: "value",
- *             type: "uint64",
- *           },
- *         ],
- *       },
- *     },
- *     balance_of: {
- *       id: 0x15619248,
- *       inputs: { type: "string" },
- *       outputs: { type: "uint64" },
- *     },
- *   },
+ * const { Contract, Provider, Signer, utils } = require("koilib");
+ * const rpcNodes = ["http://api.koinos.io:8080"];
+ * const privateKey = "f186a5de49797bfd52dc42505c33d75a46822ed5b60046e09d7c336242e20200";
+ * const provider = new Provider(rpcNodes);
+ * const signer = new Signer({ privateKey, provider });
+ * const koinContract = new Contract({
+ *   id: "19JntSm8pSNETT9aHTwAUHC5RMoaSmgZPJ",
+ *   abi: utils.Krc20Abi,
+ *   provider,
+ *   signer,
  * });
+ * const koin = koinContract.functions;
  *
- * const opEncoded = contract.encodeOperation({
- *   name: "transfer",
- *   args: {
- *     from: "alice",
- *     to: "bob",
- *     value: BigInt(1000),
- *   },
+ * // optional: preformat input/output
+ * koinContract.abi.methods.balanceOf.preformatInput = (owner) =>
+ *   ({ owner });
+ * koinContract.abi.methods.balanceOf.preformatOutput = (res) =>
+ *   utils.formatUnits(res.value, 8);
+ * koinContract.abi.methods.transfer.preformatInput = (input) => ({
+ *   from: signer.getAddress(),
+ *   to: input.to,
+ *   value: utils.parseUnits(input.value, 8),
  * });
  *
- * console.log(opEncoded);
- * // {
- * //   type: "koinos::protocol::call_contract_operation",
- * //   value: {
- * //     contract_id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
- * //     entry_point: 0x62efa292,
- * //     args: "MBWFsaWNlA2JvYgAAAAAAAAPo",
- * //   }
- * // }
+ * async funtion main() {
+ *   // Get balance
+ *   const { result } = await koin.balanceOf("12fN2CQnuJM8cMnWZ1hPtM4knjLME8E4PD");
+ *   console.log(result)
  *
- * const opDecoded = contract.decodeOperation(opEncoded);
- * console.log(opDecoded);
- * // {
- * //   name: "transfer",
- * //   args: {
- * //     from: "alice",
- * //     to: "bob",
- * //     value: 1000n,
- * //   },
- * // }
+ *   // Transfer
+ *   const { transaction, transactionResponse } = await koin.transfer({
+ *     to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
+ *     value: "10.0001",
+ *   });
+ *   console.log(`Transaction id ${transaction.id} submitted`);
  *
- * const resultDecoded = contract.decodeResult("MAAsZnAzyD0E=", "balance_of");
- * console.log(resultDecoded)
- * // 3124382766600001n
+ *   // wait to be mined
+ *   const blockId = await transactionResponse.wait();
+ *   console.log(`Transaction mined. Block id: ${blockId}`);
+ * }
+ *
+ * main();
  * ```
  */
 export declare class Contract {
     /**
      * Contract ID
      */
-    id: string;
-    /**
-     * Contract entries. See [[Entries]]
-     */
-    entries: Entries;
+    id?: Uint8Array;
     /**
-     * The constructor receives the contract ID and
-     * contract entries definition
-     * @param c - Object with contract id and contract entries
+     * Set of functions to interact with the smart
+     * contract. These functions are automatically generated
+     * in the constructor of the class
      *
      * @example
      * ```ts
-     * const contract = new Contract({
-     *   id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
-     *   entries: {
-     *     transfer: {
-     *       id: 0x62efa292,
-     *       inputs: {
-     *         type: [
-     *           {
-     *             name: "from",
-     *             type: "string",
-     *           },
-     *           {
-     *             name: "to",
-     *             type: "string",
-     *           },
-     *           {
-     *             name: "value",
-     *             type: "uint64",
-     *           },
-     *         ],
-     *       },
-     *     },
-     *     balance_of: {
-     *       id: 0x15619248,
-     *       inputs: { type: "string" },
-     *       outputs: { type: "uint64" },
-     *     },
-     *   },
-     * });
+     * const owner = "1Gvqdo9if6v6tFomEuTuMWP1D7H7U9yksb";
+     * await koinContract.functions.balanceOf({ owner });
      * ```
      */
+    functions: {
+        [x: string]: <T = Record<string, unknown>>(args?: unknown, opts?: TransactionOptions) => Promise<{
+            operation: CallContractOperationNested;
+            transaction?: TransactionJson;
+            transactionResponse?: SendTransactionResponse;
+            result?: T;
+        }>;
+    };
+    /**
+     * Application Binary Interface
+     */
+    abi?: Abi;
+    /**
+     * Signer interacting with the smart contract
+     */
+    signer?: SignerInterface;
+    /**
+     * Provider to connect with the blockchain
+     */
+    provider?: Provider;
+    /**
+     * Serializer to serialize/deserialize data types
+     */
+    serializer?: Serializer;
+    /**
+     * Bytecode. Needed to deploy the smart contract.
+     */
+    bytecode?: Uint8Array;
+    /**
+     * Options to apply when creating transactions.
+     * By default it set rc_limit to 1e8, sendTransaction true,
+     * sendAbis true, and nonce undefined (to get it from the blockchain)
+     */
+    options: TransactionOptions;
     constructor(c: {
-        id: string;
-        entries: Entries;
+        id?: string;
+        abi?: Abi;
+        bytecode?: Uint8Array;
+        options?: TransactionOptions;
+        signer?: Signer;
+        provider?: Provider;
+        /**
+         * Set this option if you can not use _eval_ functions
+         * in the current environment. In such cases, the
+         * serializer must come from an environment where it
+         * is able to use those functions.
+         */
+        serializer?: Serializer;
     });
+    /**
+     * Compute contract Id
+     */
+    static computeContractId(address: string): Uint8Array;
+    /**
+     * Get contract Id
+     */
+    getId(): string;
+    /**
+     * Function to deploy a new smart contract.
+     * The Bytecode must be defined in the constructor of the class
+     * @example
+     * ```ts
+     * const privateKey = "f186a5de49797bfd52dc42505c33d75a46822ed5b60046e09d7c336242e20200";
+     * const provider = new Provider(["http://api.koinos.io:8080"]);
+     * const signer = new Signer({ privateKey, provider });
+     * const bytecode = new Uint8Array([1, 2, 3, 4]);
+     * const contract = new Contract({ signer, provider, bytecode });
+     * const { transactionResponse } = await contract.deploy();
+     * // wait to be mined
+     * const blockId = await transactionResponse.wait();
+     * console.log(`Contract uploaded in block id ${blockId}`);
+     * ```
+     */
+    deploy(options?: TransactionOptions): Promise<{
+        operation: UploadContractOperationNested;
+        transaction?: TransactionJson;
+        transactionResponse?: SendTransactionResponse;
+    }>;
     /**
      * Encondes a contract operation using Koinos serialization
      * and taking the contract entries as reference to build it
@@ -235,32 +158,30 @@ export declare class Contract {
      * const opEncoded = contract.encodeOperation({
      *   name: "transfer",
      *   args: {
-     *     from: "alice",
-     *     to: "bob",
-     *     value: 1000,
+     *     from: "12fN2CQnuJM8cMnWZ1hPtM4knjLME8E4PD",
+     *     to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
+     *     value: "1000",
      *   }
      * });
      *
      * console.log(opEncoded);
      * // {
-     * //   type: "koinos::protocol::call_contract_operation",
-     * //   value: {
-     * //     contract_id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
+     * //   call_contract: {
+     * //     contract_id: "19JntSm8pSNETT9aHTwAUHC5RMoaSmgZPJ",
      * //     entry_point: 0x62efa292,
      * //     args: "MBWFsaWNlA2JvYgAAAAAAAAPo",
      * //   }
      * // }
      * ```
      */
-    encodeOperation(op: DecodedOperation): EncodedOperation;
+    encodeOperation(op: DecodedOperationJson): Promise<CallContractOperationNested>;
     /**
      * Decodes a contract operation to be human readable
      * @example
      * ```ts
      * const opDecoded = contract.decodeOperation({
-     *   type: "koinos::protocol::call_contract_operation",
-     *   value: {
-     *     contract_id: "Mkw96mR+Hh71IWwJoT/2lJXBDl5Q=",
+     *   call_contract: {
+     *     contract_id: "19JntSm8pSNETT9aHTwAUHC5RMoaSmgZPJ",
      *     entry_point: 0x62efa292,
      *     args: "MBWFsaWNlA2JvYgAAAAAAAAPo",
      *   }
@@ -269,29 +190,13 @@ export declare class Contract {
      * // {
      * //   name: "transfer",
      * //   args: {
-     * //     from: "alice",
-     * //     to: "bob",
-     * //     value: 1000n,
+     * //     from: "12fN2CQnuJM8cMnWZ1hPtM4knjLME8E4PD",
+     * //     to: "172AB1FgCsYrRAW5cwQ8KjadgxofvgPFd6",
+     * //     value: "1000",
      * //   },
      * // }
      * ```
      */
-    decodeOperation(op: EncodedOperation): DecodedOperation;
-    /**
-     * Decodes a result. This function is used in conjunction with
-     * [[Provider.readContract | readContract of Provider class]] to read a
-     * contract and decode the result. "outputs" field must be defined in
-     * the abi for the operation name.
-     * @param result - Encoded result in base64
-     * @param opName - Operation name
-     * @returns Decoded result
-     * @example
-     * ```ts
-     * const resultDecoded = contract.decodeResult("MAAsZnAzyD0E=", "balance_of");
-     * console.log(resultDecoded)
-     * // 3124382766600001n
-     * ```
-     */
-    decodeResult(result: string, opName: string): unknown;
+    decodeOperation(op: CallContractOperationNested): Promise<DecodedOperationJson>;
 }
 export default Contract;