@defillama/sdk 5.0.235 → 5.0.238

package/build/chains/icp.d.ts

@@ -0,0 +1,235 @@
+import { Endpoints } from "./rpc";
+export declare const CHAIN = "icp";
+export declare const DEFAULT_ENDPOINTS: string[];
+/** ICP ledger canister */
+export declare const ICP_LEDGER = "ryjl3-tyaaa-aaaaa-aaaba-cai";
+/** Candid encoding of an empty argument list: "DIDL" + 0 types + 0 args */
+export declare const EMPTY_ARGS: Uint8Array;
+/** anonymous principal (0x04) */
+export declare const ANONYMOUS_SENDER: Uint8Array;
+type Cursor = {
+    i: number;
+};
+/** Encode a CBOR item head: major type (0-7) + unsigned argument. */
+export declare function encodeCborHead(major: number, value: number | bigint): Buffer;
+/**
+ * Encode a JS value as CBOR. Supports null, booleans, integers (number / bigint, negative too),
+ * byte strings (Buffer / Uint8Array), text, arrays and plain objects (keys encoded as text, in
+ * insertion order). Floats are rejected: the IC request format never needs them.
+ */
+export declare function encodeCbor(value: any): Buffer;
+/**
+ * Decode one CBOR item starting at `state.i` (default: the start of `bytes`).
+ * Integers within the safe range decode to `number`, larger ones to `bigint`; byte strings to
+ * `Uint8Array`; maps to plain objects. Tags are skipped (the IC self-describe tag 55799 included).
+ */
+export declare function decodeCbor(bytes: Uint8Array, state?: Cursor): any;
+/** Read an unsigned LEB128 integer at `state.i`, advancing the cursor. */
+export declare function decodeUleb128(bytes: Uint8Array, state: Cursor): bigint;
+/** Read a signed LEB128 integer at `state.i`, advancing the cursor. */
+export declare function decodeSleb128(bytes: Uint8Array, state: Cursor): bigint;
+/** Encode a non-negative integer as unsigned LEB128. */
+export declare function encodeUleb128(value: number | bigint | string): Buffer;
+/** Encode an integer as signed LEB128. */
+export declare function encodeSleb128(value: number | bigint | string): Buffer;
+/** Candid type opcodes (negative sleb128 in the type table) */
+export declare const CANDID_TYPE: {
+    readonly null: -1;
+    readonly bool: -2;
+    readonly nat: -3;
+    readonly int: -4;
+    readonly nat8: -5;
+    readonly nat16: -6;
+    readonly nat32: -7;
+    readonly nat64: -8;
+    readonly int8: -9;
+    readonly int16: -10;
+    readonly int32: -11;
+    readonly int64: -12;
+    readonly float32: -13;
+    readonly float64: -14;
+    readonly text: -15;
+    readonly reserved: -16;
+    readonly empty: -17;
+    readonly opt: -18;
+    readonly vec: -19;
+    readonly record: -20;
+    readonly variant: -21;
+    readonly func: -22;
+    readonly service: -23;
+    readonly principal: -24;
+};
+export type CandidPrimitive = 'null' | 'bool' | 'nat' | 'int' | 'nat8' | 'nat16' | 'nat32' | 'nat64' | 'int8' | 'int16' | 'int32' | 'int64' | 'float32' | 'float64' | 'text' | 'reserved' | 'empty' | 'principal'
+/** shorthand for `vec nat8`, value may be Uint8Array / number[] / hex string */
+ | 'blob';
+/**
+ * Type descriptor for {@link encodeCandid}. Record / variant field names are hashed with
+ * {@link hashCandidLabel}; a purely numeric name (`'0'`, `'1'`) is used as the field id directly
+ * (Candid tuple fields).
+ */
+export type CandidType = CandidPrimitive | {
+    opt: CandidType;
+} | {
+    vec: CandidType;
+} | {
+    record: Record<string, CandidType>;
+} | {
+    variant: Record<string, CandidType>;
+};
+export interface CandidValue {
+    type: CandidType;
+    value: any;
+}
+/**
+ * Candid identifies a record field by a hash of its name rather than the name itself, so a decoded
+ * record comes back keyed by number. Build a `{ [hash]: name }` map with this (or with
+ * {@link buildLabelHashMap}) to get readable keys. `hash = fold(h * 223 + byte) mod 2^32`.
+ */
+export declare function hashCandidLabel(label: string): number;
+/** `['owner', 'subaccount']` -> `{ 947296307: 'owner', 1349681965: 'subaccount' }` */
+export declare function buildLabelHashMap(labels?: string[]): Record<number, string>;
+/**
+ * Decode a Candid-encoded reply. Candid is self-describing, so the concrete shape is only known at
+ * runtime and values are returned as `any`; narrow them at the call site.
+ * - `nat`, `int`, `nat64`, `int64` -> `bigint`; `nat8/16/32`, `int8/16/32`, floats -> `number`
+ * - `text`, `principal` -> `string`; `opt` -> 0- or 1-element array; `vec` -> array (`vec nat8` too)
+ * - `record` -> object keyed by label (via `labelHashMap`) or by field hash as a string
+ * - `variant` -> single-key object
+ * @param bytes the raw `DIDL...` payload returned by {@link queryCanister}
+ * @param labelHashMap `{ [hash]: name }` from {@link hashCandidLabel}; unmapped fields keep their hash
+ * @returns one entry per value in the reply tuple
+ */
+export declare function decodeCandid(bytes: Uint8Array, labelHashMap?: Record<number, string>): any[];
+/**
+ * Minimal Candid encoder: `DIDL` + type table + arg types + values.
+ *
+ * Value conventions (mirroring what {@link decodeCandid} produces):
+ * - `nat` / `int` / fixed-width ints accept number, bigint or decimal string
+ * - `text` string; `bool` boolean; `null` / `reserved` anything (nothing is written)
+ * - `principal` textual principal or raw bytes
+ * - `blob` (`vec nat8`) Uint8Array / Buffer / number[] / hex string
+ * - `opt` `null` / `undefined` / `[]` -> none, `[x]` -> some(x), any other value -> some(value)
+ * - `vec` array (or Uint8Array when the element type is `nat8`)
+ * - `record` object keyed by field name; a missing `opt` field is encoded as none
+ * - `variant` single-key object `{ Tag: value }`, or a string `'Tag'` for unit variants
+ */
+export declare function encodeCandid(args?: CandidValue[]): Buffer;
+/** Uint8Array / Buffer / number[] / hex string (0x optional) -> Uint8Array */
+export declare function toBytes(value: any, what?: string): Uint8Array;
+/** CRC-32 (IEEE) as used by principal text and account identifiers */
+export declare function crc32(bytes: Uint8Array): number;
+/** RFC 4648 base32 without padding, lowercase alphabet by default (as principals use). */
+export declare function bytesToBase32(bytes: Uint8Array, alphabet?: string): string;
+/** Inverse of {@link bytesToBase32}: case-insensitive, ignores `-` separators and `=` padding. */
+export declare function base32ToBytes(text: string): Uint8Array;
+/** Raw principal bytes -> textual principal (`crc32 || bytes`, base32, dashed every 5 chars). */
+export declare function principalBytesToText(principalBytes: Uint8Array): string;
+/** Textual principal -> raw bytes. Verifies the CRC-32 prefix and throws on mismatch. */
+export declare function principalTextToBytes(principalText: string): Uint8Array;
+/** True when `str` is a well formed textual principal (valid base32, checksum and grouping). */
+export declare function isPrincipal(str: any): boolean;
+/**
+ * ICP ledger account identifier (hex, 32 bytes):
+ * `crc32(h) || h` where `h = sha224("\x0Aaccount-id" || principal || subaccount)`.
+ * `subaccount` defaults to 32 zero bytes; accepts Uint8Array / number[] / hex, right-padded to 32 bytes.
+ */
+export declare function accountIdentifierFromPrincipal(principal: string | Uint8Array, subaccount?: Uint8Array | number[] | string | null): string;
+/** Boundary node list: `ICP_RPC` (comma separated) or {@link DEFAULT_ENDPOINTS}. */
+export declare function getEndpoints(): string[];
+/** Thrown when the replica answers a query with a reject (canister error, missing method, dead canister). */
+export declare class IcpRejectError extends Error {
+    canisterId: string;
+    method: string;
+    status?: string;
+    rejectCode?: number;
+    rejectMessage?: string;
+    errorCode?: string;
+    constructor(canisterId: string, method: string, decoded: any);
+}
+export interface QueryCanisterParams {
+    canisterId: string;
+    /** canister method name */
+    method?: string;
+    /** alias of `method` (DefiLlama-Adapters / dimension-adapters naming) */
+    methodName?: string;
+    /** Candid encoded argument, default: empty args (`DIDL\0\0`) */
+    arg?: Uint8Array;
+    /** explicit boundary node(s); overrides `ICP_RPC` and the defaults */
+    host?: Endpoints;
+    /** http timeout in ms, default 30s */
+    timeout?: number;
+    /** total transport attempts across hosts, default max(3, hosts) */
+    retries?: number;
+}
+export interface QueryDecodedParams extends QueryCanisterParams {
+    /** `{ [hash]: name }` map for record / variant labels (see {@link hashCandidLabel}) */
+    labelHashMap?: Record<number, string>;
+    /** label names, merged into `labelHashMap` via {@link buildLabelHashMap} */
+    labels?: string[];
+}
+export interface CallCandidParams extends QueryDecodedParams {
+    /** typed arguments `{ type, value }`; or raw values when `argTypes` is given */
+    args?: CandidValue[] | any[];
+    /** types for `args` when they are raw values */
+    argTypes?: CandidType[];
+}
+/**
+ * Anonymous query call against a canister (`/api/v2/canister/<id>/query`).
+ * Rotates over the configured boundary nodes and retries transport errors; canister rejects are
+ * thrown as {@link IcpRejectError} without retry.
+ * @returns the raw Candid reply (`DIDL...` bytes), to be passed to {@link decodeCandid}
+ */
+export declare function queryCanister(params: QueryCanisterParams): Promise<Uint8Array>;
+/**
+ * Query a method and decode its reply in one step.
+ * Accepts either `{ canisterId, method, arg?, labelHashMap?, labels? }` or the dimension-adapters
+ * positional form `(canisterId, methodName, labels?)`.
+ * @returns the first value of the reply tuple (`any`, see {@link decodeCandid})
+ */
+export declare function queryCanisterDecoded(params: QueryDecodedParams): Promise<any>;
+export declare function queryCanisterDecoded(canisterId: string, method: string, labels?: string[]): Promise<any>;
+/**
+ * Encode `args` with {@link encodeCandid}, query `method` and decode the reply.
+ * `args` is either `CandidValue[]` (`{ type, value }`) or raw values paired with `argTypes`.
+ * @returns the first value of the reply tuple
+ */
+export declare function callCandid(params: CallCandidParams): Promise<any>;
+export interface LedgerParams {
+    /** ledger canister id */
+    ledger: string;
+    host?: Endpoints;
+    timeout?: number;
+}
+export type IcrcMetadataValue = string | Uint8Array;
+/**
+ * `icrc1_metadata` as `{ 'icrc1:symbol': 'ckBTC', 'icrc1:decimals': '8', ... }`.
+ * `Nat` / `Int` values are returned as decimal strings, `Text` as string, `Blob` as Uint8Array.
+ */
+export declare function getIcrcMetadata({ ledger, host, timeout }: LedgerParams): Promise<Record<string, IcrcMetadataValue>>;
+/** `icrc1_decimals` (nat8) */
+export declare function getIcrcDecimals({ ledger, host, timeout }: LedgerParams): Promise<number>;
+/** `icrc1_symbol` */
+export declare function getIcrcSymbol({ ledger, host, timeout }: LedgerParams): Promise<string>;
+/** `icrc1_name` */
+export declare function getIcrcName({ ledger, host, timeout }: LedgerParams): Promise<string>;
+/** `icrc1_total_supply` as a decimal string in base units */
+export declare function getIcrcTotalSupply({ ledger, host, timeout }: LedgerParams): Promise<string>;
+/**
+ * `icrc1_balance_of(record { owner: principal; subaccount: opt blob })` as a decimal string in base units.
+ * `subaccount` accepts Uint8Array / number[] / hex; omit it for the default subaccount.
+ */
+export declare function getIcrcBalance({ ledger, owner, subaccount, host, timeout }: LedgerParams & {
+    owner: string;
+    subaccount?: Uint8Array | number[] | string | null;
+}): Promise<string>;
+/**
+ * ICP ledger `account_balance(record { account: blob })` -> `e8s` as a decimal string.
+ * `accountIdentifierHex` is the 32 byte account identifier (see {@link accountIdentifierFromPrincipal}).
+ */
+export declare function getIcpAccountBalance({ accountIdentifierHex, ledger, host, timeout }: {
+    accountIdentifierHex: string;
+    ledger?: string;
+    host?: Endpoints;
+    timeout?: number;
+}): Promise<string>;
+export {};