koilib 5.3.1 → 5.5.0

package/lib/browser/interface.d.ts

@@ -3,11 +3,15 @@ import { Serializer } from "./Serializer";
 /**
  * Application Binary Interface (ABI)
  *
- * ABIs are composed of 2 elements: methods and types.
+ * ABIs are composed of 3 elements: methods, events, and types.
  * - The methods define the names of the entries of the smart contract,
  * the corresponding endpoints and the name of the types used.
- * - The types all the description to serialize and deserialize
- * using proto buffers.
+ * - The events define possible events triggered by the smart contract
+ * and the name of the types used.
+ * - The types contain the description to serialize and deserialize
+ * data using proto buffers. It is used to encode/decode the methods
+ * and events. These types can be provided in binary format or json
+ * format (koilib_types)
  *
  * To generate the types is necessary to use the dependency
  * protobufjs. The following example shows how to generate the
@@ -49,7 +53,12 @@ import { Serializer } from "./Serializer";
  *       return: "mint_result",
  *     },
  *   },
- *   types: tokenJson,
+ *   events: {
+ *     'koinos.contracts.token.mint_event': {
+ *       argument: "mint"
+ *     },
+ *   },
+ *   koilib_types: tokenJson,
  * };
  * ```
  *
@@ -58,6 +67,95 @@ import { Serializer } from "./Serializer";
  * empty response (for instance when there are no balance records
  * for a specific address) and you require a default output in
  * such cases.
+ *
+ * **Definition of events**
+ *
+ * There are 2 ways to define events in koinos:
+ * - Event names as protobuffer names
+ * - Custom event names
+ *
+ * 1. Event names as protobuffer names: The name of the event links
+ * with the protobuffer definition. In this case there is no need
+ * to define the event in the ABI.
+ *
+ * Example:
+ *
+ * Proto definition
+ * ```
+ * package koinos.contracts.token;
+ *
+ * message transfer_arguments {
+ *    bytes from = 1 [(btype) = ADDRESS];
+ *    bytes to = 2 [(btype) = ADDRESS];
+ *    uint64 value = 3 [jstype = JS_STRING];
+ * }
+ *
+ * message transfer_event {
+ *    bytes from = 1 [(btype) = ADDRESS];
+ *    bytes to = 2 [(btype) = ADDRESS];
+ *    uint64 value = 3 [jstype = JS_STRING];
+ * }
+ * ```
+ *
+ * Contract
+ * ```ts
+ * // token-contract.ts
+ * transfer(args: token.transfer_arguments): token.transfer_result {
+ *   ...
+ *   System.event("koinos.contracts.token.transfer_event", Protobuf.encode(event, token.transfer_event.encode), impacted);
+ * }
+ * ```
+ *
+ * 2. Custom event names: The previous definition has a limitation. It's
+ * necessary to define a proto message for each event and argument, and they can
+ * not be reused. In this second solution, the event names are defined
+ * in the ABI and they are linked with the corresponding protobuffer definitions.
+ * In this sense, they can be reused.
+ *
+ * Example
+ *
+ * Proto definition
+ * ```
+ * package koinos.contracts.token;
+ *
+ * // only 1 message
+ * message transfer {
+ *    bytes from = 1 [(btype) = ADDRESS];
+ *    bytes to = 2 [(btype) = ADDRESS];
+ *    uint64 value = 3 [jstype = JS_STRING];
+ * }
+ * ```
+ *
+ * Contract
+ * ```ts
+ * // token-contract.ts
+ *
+ * // Transfer of tokens
+ * // @event transfer_event token.transfer
+ * transfer(args: token.transfer): void {
+ *   ...
+ *   System.event("transfer_event", Protobuf.encode(event, token.transfer.encode), impacted);
+ * }
+ * ```
+ *
+ * ABI
+ * ```ts
+ * const abiToken = {
+ *   methods: {
+ *     transfer: {
+ *       entry_point: 0x62efa292,
+ *       argument: "transfer",
+ *       return: "",
+ *     },
+ *   },
+ *   events: {
+ *     'transfer_event': {
+ *       argument: "transfer"
+ *     },
+ *   },
+ *   koilib_types: tokenJson,
+ * };
+ * ```
  */
 export interface Abi {
     methods: {
@@ -84,11 +182,26 @@ export interface Abi {
             description?: string;
         };
     };
+    /**
+     * Protobuffers descriptor in binary format encoded in base64url.
+     */
+    types?: string;
     /**
      * Protobuffers descriptor in JSON format.
      * See https://www.npmjs.com/package/protobufjs#using-json-descriptors
      */
-    koilib_types: INamespace;
+    koilib_types?: INamespace;
+    /**
+     * Definition of events
+     */
+    events?: {
+        [x: string]: {
+            /** Protobuffer type for argument */
+            argument?: string;
+            /** Description of the event */
+            description?: string;
+        };
+    };
 }
 /**
  * Human readable format operation
@@ -111,7 +224,61 @@ export interface DecodedOperationJson {
     /** Arguments decoded. See [[Abi]] */
     args?: Record<string, unknown>;
 }
-export interface BaseTransactionOptions {
+export interface SendTransactionOptions {
+    /**
+     * Broadcast
+     *
+     * Boolean to define if the transaction should be broadcasted
+     * to the different nodes in the network. By default it is true.
+     *
+     * Set it to false if you want to interact with a contract for
+     * testing purposes and check the possible events triggered.
+     */
+    broadcast?: boolean;
+    /**
+     * Collection of Abis so that the receiver can parse the
+     * operations in the transaction
+     */
+    abis?: Record<string, Abi>;
+    /**
+     * Send abis
+     *
+     * Boolean to define if the abis should be shared with
+     * the signer so it will be able to decode the operations.
+     * By default it is true.
+     */
+    sendAbis?: boolean;
+    /**
+     * Function to be called before sending a transaction to the
+     * blockchain. It is useful to apply multisignatures to
+     * the transaction.
+     *
+     * @example
+     * ```ts
+     * const signer2 = Signer.fromSeed("signer2");
+     * const signer3 = Signer.fromSeed("signer3");
+     *
+     * const addMoreSignatures = async (tx, opts) => {
+     *   await signer2.signTransaction(tx);
+     *   await signer3.signTransaction(tx);
+     * };
+     *
+     * const { transaction } = await koin.transfer(
+     *   {
+     *     from: "16MT1VQFgsVxEfJrSGinrA5buiqBsN5ViJ",
+     *     to: "1Gvqdo9if6v6tFomEuTuMWP1D7H7U9yksb",
+     *     value: "1000000",
+     *   },
+     *   {
+     *     payer: signer2.getAddress(),
+     *     beforeSend: addMoreSignatures,
+     *   }
+     * );
+     * ```
+     */
+    beforeSend?: (tx: TransactionJson, options?: SendTransactionOptions) => Promise<void>;
+}
+export interface TransactionOptions extends SendTransactionOptions {
     /**
      * Chain ID
      *
@@ -160,6 +327,8 @@ export interface BaseTransactionOptions {
      * not set the blockchain will increase the payer's nonce.
      */
     payee?: string;
+}
+export interface ContractTransactionOptions extends TransactionOptions {
     /**
      * Only operation
      *
@@ -195,34 +364,9 @@ export interface BaseTransactionOptions {
      * true.
      */
     sendTransaction?: boolean;
-    /**
-     * Broadcast
-     *
-     * Boolean to define if the transaction should be broadcasted
-     * to the different nodes in the network. By default it is true.
-     *
-     * Set it to false if you want to interact with a contract for
-     * testing purposes and check the possible events triggered.
-     */
-    broadcast?: boolean;
-    /**
-     * Function to be called before sending a transaction to the
-     * blockchain. It is useful to apply multisignatures to
-     * the transaction
-     */
-    beforeSend?: (tx: TransactionJson, options?: SendTransactionOptions) => Promise<void>;
-}
-export interface TransactionOptions extends BaseTransactionOptions {
-    /**
-     * Send abis
-     *
-     * Boolean to define if the abis should be shared with
-     * the signer so it will be able to decode the operations.
-     * By default it is true.
-     */
-    sendAbis?: boolean;
 }
-export interface DeployOptions extends BaseTransactionOptions {
+export declare type CallContractOptions = ContractTransactionOptions;
+export interface DeployOptions extends ContractTransactionOptions {
     /**
      * ABI
      *
@@ -255,52 +399,6 @@ export interface DeployOptions extends BaseTransactionOptions {
      */
     authorizesUploadContract?: boolean;
 }
-export interface SendTransactionOptions {
-    /**
-     * Broadcast
-     *
-     * Boolean to define if the transaction should be broadcasted
-     * to the different nodes in the network. By default it is true.
-     *
-     * Set it to false if you want to interact with a contract for
-     * testing purposes and check the possible events triggered.
-     */
-    broadcast?: boolean;
-    /**
-     * Collection of Abis so that the receiver can parse the
-     * operations in the transaction
-     */
-    abis?: Record<string, Abi>;
-    /**
-     * Function to be called before sending a transaction to the
-     * blockchain. It is useful to apply multisignatures to
-     * the transaction.
-     *
-     * @example
-     * ```ts
-     * const signer2 = Signer.fromSeed("signer2");
-     * const signer3 = Signer.fromSeed("signer3");
-     *
-     * const addMoreSignatures = async (tx, opts) => {
-     *   await signer2.signTransaction(tx);
-     *   await signer3.signTransaction(tx);
-     * };
-     *
-     * const { transaction } = await koin.transfer(
-     *   {
-     *     from: "16MT1VQFgsVxEfJrSGinrA5buiqBsN5ViJ",
-     *     to: "1Gvqdo9if6v6tFomEuTuMWP1D7H7U9yksb",
-     *     value: "1000000",
-     *   },
-     *   {
-     *     payer: signer2.getAddress(),
-     *     beforeSend: addMoreSignatures,
-     *   }
-     * );
-     * ```
-     */
-    beforeSend?: (tx: TransactionJson, options?: SendTransactionOptions) => Promise<void>;
-}
 export interface RecoverPublicKeyOptions {
     /**
      * Boolean to define if the public key should
@@ -539,6 +637,16 @@ export interface ValueType {
     uint64_value?: string;
     [x: string]: unknown;
 }
+export interface EventData {
+    sequence: number;
+    source: string;
+    name: string;
+    data: string;
+    impacted: string[];
+}
+export interface DecodedEventData extends EventData {
+    args: Record<string, unknown>;
+}
 export interface TransactionReceipt {
     id: string;
     payer: string;
@@ -549,12 +657,6 @@ export interface TransactionReceipt {
     network_bandwidth_used: string;
     compute_bandwidth_used: string;
     reverted: boolean;
-    events: {
-        sequence: number;
-        source: string;
-        name: string;
-        data: string;
-        impacted: string[];
-    }[];
+    events: EventData[];
     logs: string[];
 }

package/lib/index.d.ts

@@ -4,4 +4,5 @@ export * as interfaces from "./interface";
 export * from "./Contract";
 export * from "./Signer";
 export * from "./Provider";
+export * from "./Transaction";
 export * from "./Serializer";

package/lib/index.js

@@ -34,5 +34,6 @@ exports.interfaces = __importStar(require("./interface"));
 __exportStar(require("./Contract"), exports);
 __exportStar(require("./Signer"), exports);
 __exportStar(require("./Provider"), exports);
+__exportStar(require("./Transaction"), exports);
 __exportStar(require("./Serializer"), exports);
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wEAAwE;AACxE,iCAAiC;AACjC,sDAAsC;AACtC,0DAA0C;AAC1C,6CAA2B;AAC3B,2CAAyB;AACzB,6CAA2B;AAC3B,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,wEAAwE;AACxE,iCAAiC;AACjC,sDAAsC;AACtC,0DAA0C;AAC1C,6CAA2B;AAC3B,2CAAyB;AACzB,6CAA2B;AAC3B,gDAA8B;AAC9B,+CAA6B"}

package/lib/index2.js

@@ -28,10 +28,12 @@ const utils = __importStar(require("./utils"));
 const Contract_1 = require("./Contract");
 const Signer_1 = require("./Signer");
 const Provider_1 = require("./Provider");
+const Transaction_1 = require("./Transaction");
 const Serializer_1 = require("./Serializer");
 window.utils = utils;
 window.Contract = Contract_1.Contract;
 window.Signer = Signer_1.Signer;
 window.Provider = Provider_1.Provider;
+window.Transaction = Transaction_1.Transaction;
 window.Serializer = Serializer_1.Serializer;
 //# sourceMappingURL=index2.js.map

package/lib/index2.js.map

@@ -1 +1 @@
-{"version":3,"file":"index2.js","sourceRoot":"","sources":["../src/index2.ts"],"names":[],"mappings":";AAAA,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;AAExE,+CAAiC;AACjC,yCAAsC;AACtC,qCAAkC;AAClC,yCAAsC;AACtC,6CAA0C;AAI1C,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;AACrB,MAAM,CAAC,QAAQ,GAAG,mBAAQ,CAAC;AAC3B,MAAM,CAAC,MAAM,GAAG,eAAM,CAAC;AACvB,MAAM,CAAC,QAAQ,GAAG,mBAAQ,CAAC;AAC3B,MAAM,CAAC,UAAU,GAAG,uBAAU,CAAC"}
+{"version":3,"file":"index2.js","sourceRoot":"","sources":["../src/index2.ts"],"names":[],"mappings":";AAAA,wEAAwE;;;;;;;;;;;;;;;;;;;;;;;;;AAExE,+CAAiC;AACjC,yCAAsC;AACtC,qCAAkC;AAClC,yCAAsC;AACtC,+CAA4C;AAC5C,6CAA0C;AAI1C,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;AACrB,MAAM,CAAC,QAAQ,GAAG,mBAAQ,CAAC;AAC3B,MAAM,CAAC,MAAM,GAAG,eAAM,CAAC;AACvB,MAAM,CAAC,QAAQ,GAAG,mBAAQ,CAAC;AAC3B,MAAM,CAAC,WAAW,GAAG,yBAAW,CAAC;AACjC,MAAM,CAAC,UAAU,GAAG,uBAAU,CAAC"}