koilib 9.1.1 → 9.3.0

package/src/Multicall.ts

@@ -0,0 +1,139 @@
+import { Contract } from "./Contract";
+import { OperationJson } from "./interface";
+import { ProviderInterface } from "./Provider";
+import { Transaction } from "./Transaction";
+import { multicallAbi } from "./abis/multicallAbi";
+
+export class Multicall {
+  /**
+   * Multicall contract address
+   */
+  id: string;
+
+  transaction: Transaction;
+
+  contracts: Contract[];
+
+  /**
+   * @example
+   * ```ts
+   * const tokens = [
+   *   "19GYjDBVXU7keLbYvMLazsGQn3GTWHjHkK", // koin
+   *   "12Y5vW6gk8GceH53YfRkRre2Rrcsgw7Naq", // vhp
+   *   "12VoHz41a4HtfiyhTWbg9RXqGMRbYk6pXh", // vortex usdt
+   *   "1Tf1QKv3gVYLjq34yURSHw5ErTYbFjqTG", // vortex eth
+   * ];
+   *
+   * const provider = new Provider("https://api.koinos.io");
+   *
+   * // create an array of the different contracts
+   * // used in the multicall
+   * const contracts = [];
+   * for (const token of tokens) {
+   *   contracts.push(
+   *     new Contract({
+   *       id: token,
+   *       provider,
+   *       abi: utils.tokenAbi,
+   *     })
+   *   );
+   * }
+   *
+   * // create the multicall instance
+   * const multicall = new Multicall({
+   *   provider,
+   *   contracts
+   * });
+   *
+   * // add operations to the multicall
+   * for (const contract of contracts) {
+   *   await multicall.add(contract.functions.balanceOf, {
+   *     owner: "1MdqwaSBy6rbasPJ9vmg2pZFJSVZ29GFpZ",
+   *   });
+   * }
+   *
+   * // call the multicall
+   * const results = await multicall.call();
+   * console.log(results);
+   * ```
+   *
+   * For testnet set the id to the multicall contract address for testnet
+   * ```ts
+   * const multicall = new Multicall({
+   *   id: "1MM9ydA8SdgXvCTH3LdQ5FS8JvHijCmGSg",
+   *   provider: new Provider("https://testnet-api.koinos.io"),
+   *   contracts: [ koinContract, fogataPoolContract ],
+   * });
+   * ```
+   */
+  constructor(c: {
+    /**
+     * Multicall contract address. Leave it undefined
+     * to use the mainnet multicall contract address.
+     */
+    id?: string;
+    provider?: ProviderInterface;
+    contracts?: Contract[];
+  }) {
+    if (c.id) this.id = c.id;
+    else this.id = "18dVCqPG3gwgL7DWQAciKYNuXfzEg5LW7"; // multicontract address mainnet
+    this.transaction = new Transaction({ provider: c.provider });
+    this.contracts = c.contracts || [];
+  }
+
+  async add(
+    input:
+      | OperationJson
+      | { operation: OperationJson }
+      | Promise<{ operation: OperationJson }>
+      | Contract["functions"]["x"],
+    args?: unknown
+  ): Promise<void> {
+    await this.transaction.pushOperation(input, args);
+  }
+
+  async call<T = Record<string, unknown>>(): Promise<(T | Error)[]> {
+    const multicallContract = new Contract({
+      id: this.id,
+      provider: this.transaction.provider,
+      abi: multicallAbi,
+    });
+
+    const calls = this.transaction.transaction.operations!.map(
+      (op) => op.call_contract!
+    );
+    const { result: multicallResult } = await multicallContract.functions.get({
+      calls,
+    });
+
+    const results: (T | Error)[] = [];
+
+    for (let i = 0; i < calls.length; i += 1) {
+      const contract = this.contracts.find(
+        (c) => c.getId() === calls[i].contract_id
+      );
+      if (contract && contract.abi) {
+        const method = Object.values(contract.abi.methods).find((method) => {
+          return method.entry_point === calls[i].entry_point;
+        });
+        if (method) {
+          const decoded = (await contract!.serializer!.deserialize(
+            multicallResult!.results[i]!.res.object,
+            method.return
+          )) as T;
+          results.push(decoded as T);
+        } else {
+          results.push(
+            new Error(
+              `Method ${calls[i].entry_point} not found in contract ${calls[i].contract_id}`
+            )
+          );
+        }
+      } else {
+        results.push(new Error(`Contract ${calls[i].contract_id} not found`));
+      }
+    }
+
+    return results;
+  }
+}

package/src/Provider.ts

@@ -15,6 +15,66 @@ import { koinos } from "./protoModules/protocol-proto.js";
 import { decodeBase64url, encodeBase64url } from "./utils";
 import { Serializer } from "./Serializer";
 
+const getObjectTypes = {
+  nested: {
+    get_object_arguments: {
+      fields: {
+        space: {
+          type: "object_space",
+          id: 1,
+        },
+        key: {
+          type: "bytes",
+          id: 2,
+        },
+      },
+    },
+    get_object_result: {
+      fields: {
+        value: {
+          type: "database_object",
+          id: 1,
+        },
+      },
+    },
+    object_space: {
+      fields: {
+        system: {
+          type: "bool",
+          id: 1,
+        },
+        zone: {
+          type: "bytes",
+          id: 2,
+          options: {
+            "(koinos.btype)": "ADDRESS",
+          },
+        },
+        id: {
+          type: "uint32",
+          id: 3,
+        },
+      },
+    },
+    database_object: {
+      fields: {
+        exists: {
+          type: "bool",
+          id: 1,
+        },
+        value: {
+          type: "bytes",
+          id: 2,
+        },
+        key: {
+          type: "bytes",
+          id: 3,
+        },
+      },
+    },
+  },
+};
+
 export interface ProviderInterface {
   call: <T = unknown>(method: string, params: unknown) => Promise<T>;
   getNonce: (
@@ -129,6 +189,56 @@ export interface ProviderInterface {
       }
     | undefined
   >;
+  invokeGetObject?: (args: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) => Promise<string | undefined>;
+  invokeGetNextObject?: (args: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) => Promise<
+    | {
+        exists: boolean;
+        value: string;
+        key: string;
+      }
+    | undefined
+  >;
+  invokeGetPrevObject?: (args: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) => Promise<
+    | {
+        exists: boolean;
+        value: string;
+        key: string;
+      }
+    | undefined
+  >;
+  invokeGetManyObjects?: (args: {
+    address: string;
+    id: number;
+    key?: string;
+    limit?: number;
+    direction?: "ascending" | "descending";
+    system?: boolean;
+    zone?: string;
+  }) => Promise<
+    {
+      exists: boolean;
+      value: string;
+      key: string;
+    }[]
+  >;
 }
 
 /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
@@ -1109,6 +1219,285 @@ export class Provider implements ProviderInterface {
       value: { address: string };
     }>(serializer, "get_contract_address", { name });
   }
+
+  async invokeGetObjectGeneric({
+    systemCallIdOrName,
+    address,
+    id,
+    key = "",
+    system = false,
+    zone = address,
+  }: {
+    systemCallIdOrName: string | number;
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) {
+    const serializer = new Serializer(getObjectTypes, {
+      argumentsTypeName: "get_object_arguments",
+      returnTypeName: "get_object_result",
+    });
+    const result = await this.invokeSystemCall<{
+      value: {
+        exists: boolean;
+        value: string;
+        key: string;
+      };
+    }>(
+      serializer,
+      systemCallIdOrName,
+      {
+        space: {
+          system,
+          zone,
+          id,
+        },
+        key,
+      },
+      {
+        caller: address,
+        caller_privilege: system ? 0 : 1,
+      }
+    );
+    return result?.value;
+  }
+
+  /**
+   * Function to get an object from the database via the get_object system call.
+   * @param args - object space and key
+   * @param args.address - caller address (also used as zone when zone is omitted)
+   * @param args.id - object space id
+   * @param args.key - object key (defaults to empty)
+   * @param args.zone - object space zone (defaults to address)
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider("https://api.koinos.io");
+   * const result = await provider.invokeGetObject({
+   *   address: "1KD9Es7LBBjA1FY3ViCgQJ7e6WH1ipKbhz",
+   *   id: 0,
+   * });
+   * console.log(result);
+   *
+   * // {
+   * //   exists: true,
+   * //   value: '...',
+   * //   key: ''
+   * // }
+   * ```
+   */
+  async invokeGetObject({
+    address,
+    id,
+    key = "",
+    system = false,
+    zone = address,
+  }: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) {
+    const result = await this.invokeGetObjectGeneric({
+      systemCallIdOrName: "get_object",
+      address,
+      id,
+      key,
+      system,
+      zone,
+    });
+    if (!result || !result.exists) return undefined;
+    return result.value;
+  }
+
+  /**
+   * Function to get the next object from the database via the
+   * get_next_object system call.
+   * @param args - object space and key
+   * @param args.address - caller address (also used as zone when zone is omitted)
+   * @param args.id - object space id
+   * @param args.key - object key to seek from (defaults to empty)
+   * @param args.system - whether the space is a system space
+   * @param args.zone - object space zone (defaults to address)
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider("https://api.koinos.io");
+   * const result = await provider.invokeGetNextObject({
+   *   address: "1KD9Es7LBBjA1FY3ViCgQJ7e6WH1ipKbhz",
+   *   id: 0,
+   * });
+   * console.log(result);
+   *
+   * // {
+   * //   exists: true,
+   * //   value: '...',
+   * //   key: '...'
+   * // }
+   * ```
+   */
+  async invokeGetNextObject({
+    address,
+    id,
+    key = "",
+    system = false,
+    zone = address,
+  }: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) {
+    return this.invokeGetObjectGeneric({
+      systemCallIdOrName: "get_next_object",
+      address,
+      id,
+      key,
+      system,
+      zone,
+    });
+  }
+
+  /**
+   * Function to get the previous object from the database via the
+   * get_prev_object system call.
+   * @param args - object space and key
+   * @param args.address - caller address (also used as zone when zone is omitted)
+   * @param args.id - object space id
+   * @param args.key - object key to seek from (defaults to empty)
+   * @param args.system - whether the space is a system space
+   * @param args.zone - object space zone (defaults to address)
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider("https://api.koinos.io");
+   * const result = await provider.invokeGetPrevObject({
+   *   address: "1KD9Es7LBBjA1FY3ViCgQJ7e6WH1ipKbhz",
+   *   id: 0,
+   *   key: "...",
+   * });
+   * console.log(result);
+   *
+   * // {
+   * //   exists: true,
+   * //   value: '...',
+   * //   key: '...'
+   * // }
+   * ```
+   */
+  async invokeGetPrevObject({
+    address,
+    id,
+    key = "",
+    system = false,
+    zone = address,
+  }: {
+    address: string;
+    id: number;
+    key?: string;
+    system?: boolean;
+    zone?: string;
+  }) {
+    return this.invokeGetObjectGeneric({
+      systemCallIdOrName: "get_prev_object",
+      address,
+      id,
+      key,
+      system,
+      zone,
+    });
+  }
+
+  /**
+   * Function to get many objects from the database by repeatedly
+   * calling get_next_object or get_prev_object.
+   * @param args - object space and pagination options
+   * @param args.address - caller address (also used as zone when zone is omitted)
+   * @param args.id - object space id
+   * @param args.key - offset key to seek from (defaults to empty)
+   * @param args.limit - maximum number of objects to return
+   * @param args.direction - traversal direction ("ascending" or "descending")
+   * @param args.system - whether the space is a system space
+   * @param args.zone - object space zone (defaults to address)
+   *
+   * @example
+   * ```ts
+   * const provider = new Provider("https://api.koinos.io");
+   * const result = await provider.invokeGetManyObjects({
+   *   address: "1KD9Es7LBBjA1FY3ViCgQJ7e6WH1ipKbhz",
+   *   id: 0,
+   *   limit: 10,
+   * });
+   * console.log(result);
+   *
+   * // [
+   * //   {
+   * //     exists: true,
+   * //     value: '...',
+   * //     key: '...'
+   * //   },
+   * //   ...
+   * // ]
+   * ```
+   */
+  async invokeGetManyObjects({
+    address,
+    id,
+    key = "",
+    limit = Number.MAX_SAFE_INTEGER,
+    direction = "ascending",
+    system = false,
+    zone = address,
+  }: {
+    address: string;
+    id: number;
+    key?: string;
+    limit?: number;
+    direction?: "ascending" | "descending";
+    system?: boolean;
+    zone?: string;
+  }) {
+    const result: {
+      exists: boolean;
+      value: string;
+      key: string;
+    }[] = [];
+
+    let currentKey = key;
+    let done = false;
+
+    do {
+      const obj =
+        direction === "ascending"
+          ? await this.invokeGetNextObject({
+              address,
+              id,
+              key: currentKey,
+              system,
+              zone,
+            })
+          : await this.invokeGetPrevObject({
+              address,
+              id,
+              key: currentKey,
+              system,
+              zone,
+            });
+
+      if (obj && obj.exists) {
+        result.push(obj);
+        currentKey = obj.key;
+      }
+
+      done = !obj || !obj.exists || result.length >= limit;
+    } while (!done);
+
+    return result;
+  }
 }
 
 export default Provider;

package/src/abis/multicallAbi.ts

@@ -0,0 +1,127 @@
+import { AnyNestedObject } from "protobufjs";
+import { Abi } from "../interface";
+
+export const multicallAbi: Abi = {
+  methods: {
+    get: {
+      argument: "multicall.get_args",
+      return: "multicall.get_return",
+      description: "Get the result of a multicall",
+      entry_point: 697873187,
+      read_only: true,
+    },
+  },
+  types:
+    "CvEDCg9tdWx0aWNhbGwucHJvdG8SCW11bHRpY2FsbBoUa29pbm9zL29wdGlvbnMucHJvdG8ibAoOY2FsbF9hcmd1bWVudHMSJQoLY29udHJhY3RfaWQYASABKAxCBIC1GAVSCmNvbnRyYWN0SWQSHwoLZW50cnlfcG9pbnQYAiABKA1SCmVudHJ5UG9pbnQSEgoEYXJncxgDIAEoDFIEYXJncyJaCgZyZXN1bHQSGAoGb2JqZWN0GAEgASgMSABSBm9iamVjdBItCgVlcnJvchgCIAEoCzIVLm11bHRpY2FsbC5lcnJvcl9kYXRhSABSBWVycm9yQgcKBXZhbHVlIiYKCmVycm9yX2RhdGESGAoHbWVzc2FnZRgBIAEoCVIHbWVzc2FnZSI7CghnZXRfYXJncxIvCgVjYWxscxgBIAMoCzIZLm11bHRpY2FsbC5jYWxsX2FyZ3VtZW50c1IFY2FsbHMiRgoLY2FsbF9yZXR1cm4SEgoEY29kZRgBIAEoBVIEY29kZRIjCgNyZXMYAiABKAsyES5tdWx0aWNhbGwucmVzdWx0UgNyZXMiPgoKZ2V0X3JldHVybhIwCgdyZXN1bHRzGAEgAygLMhYubXVsdGljYWxsLmNhbGxfcmV0dXJuUgdyZXN1bHRzYgZwcm90bzM=",
+  koilib_types: {
+    nested: {
+      multicall: {
+        nested: {
+          call_arguments: {
+            fields: {
+              contract_id: {
+                type: "bytes",
+                id: 1,
+                options: {
+                  "(koinos.btype)": "CONTRACT_ID",
+                },
+              },
+              entry_point: {
+                type: "uint32",
+                id: 2,
+              },
+              args: {
+                type: "bytes",
+                id: 3,
+              },
+            },
+          },
+          result: {
+            oneofs: {
+              value: {
+                oneof: ["object", "error"],
+              },
+            },
+            fields: {
+              object: {
+                type: "bytes",
+                id: 1,
+              },
+              error: {
+                type: "error_data",
+                id: 2,
+              },
+            },
+          },
+          error_data: {
+            fields: {
+              message: {
+                type: "string",
+                id: 1,
+              },
+            },
+          },
+          get_args: {
+            fields: {
+              calls: {
+                rule: "repeated",
+                type: "call_arguments",
+                id: 1,
+              },
+            },
+          },
+          call_return: {
+            fields: {
+              code: {
+                type: "int32",
+                id: 1,
+              },
+              res: {
+                type: "result",
+                id: 2,
+              },
+            },
+          },
+          get_return: {
+            fields: {
+              results: {
+                rule: "repeated",
+                type: "call_return",
+                id: 1,
+              },
+            },
+          },
+        },
+      },
+      koinos: {
+        options: {
+          go_package: "github.com/koinos/koinos-proto-golang/koinos",
+        },
+        nested: {
+          bytes_type: {
+            values: {
+              BASE64: 0,
+              BASE58: 1,
+              HEX: 2,
+              BLOCK_ID: 3,
+              TRANSACTION_ID: 4,
+              CONTRACT_ID: 5,
+              ADDRESS: 6,
+            },
+          },
+          _btype: {
+            oneof: ["btype"],
+          } as AnyNestedObject,
+          btype: {
+            type: "bytes_type",
+            id: 50000,
+            extend: "google.protobuf.FieldOptions",
+            options: {
+              proto3_optional: true,
+            },
+          },
+        },
+      },
+    },
+  },
+};

package/src/index.ts

@@ -7,3 +7,4 @@ export * from "./Signer";
 export * from "./Provider";
 export * from "./Transaction";
 export * from "./Serializer";
+export * from "./Multicall";

package/src/index2.ts

@@ -6,6 +6,7 @@ import { Signer } from "./Signer";
 import { Provider } from "./Provider";
 import { Transaction } from "./Transaction";
 import { Serializer } from "./Serializer";
+import { Multicall } from "./Multicall";
 
 declare const window: { [x: string]: unknown };
 
@@ -15,3 +16,4 @@ window.Signer = Signer;
 window.Provider = Provider;
 window.Transaction = Transaction;
 window.Serializer = Serializer;
+window.Multicall = Multicall;