@defillama/sdk 5.0.240 → 5.0.244

package/build/chains/stellar.d.ts

@@ -0,0 +1,410 @@
+export declare const DEFAULT_HORIZON = "https://horizon.stellar.org";
+export declare const DEFAULT_SOROBAN_ENDPOINTS: string[];
+export declare const PUBLIC_NETWORK_PASSPHRASE = "Public Global Stellar Network ; September 2015";
+/** Classic assets and Stellar Asset Contracts always have 7 decimals. */
+export declare const STELLAR_DECIMALS = 7;
+export declare function getHorizonEndpoints(): string[];
+export declare function getHorizonEndpoint(): string;
+export declare function getSorobanEndpoints(): string[];
+/** SCValType discriminants: https://github.com/stellar/stellar-xdr/blob/main/Stellar-contract.x */
+export declare const SC_VAL: {
+    readonly BOOL: 0;
+    readonly VOID: 1;
+    readonly ERROR: 2;
+    readonly U32: 3;
+    readonly I32: 4;
+    readonly U64: 5;
+    readonly I64: 6;
+    readonly TIMEPOINT: 7;
+    readonly DURATION: 8;
+    readonly U128: 9;
+    readonly I128: 10;
+    readonly U256: 11;
+    readonly I256: 12;
+    readonly BYTES: 13;
+    readonly STRING: 14;
+    readonly SYMBOL: 15;
+    readonly VEC: 16;
+    readonly MAP: 17;
+    readonly ADDRESS: 18;
+    readonly CONTRACT_INSTANCE: 19;
+    readonly LEDGER_KEY_CONTRACT_INSTANCE: 20;
+    readonly LEDGER_KEY_NONCE: 21;
+};
+/** SCAddressType discriminants (inside ScVal::Address / InvokeContractArgs). */
+export declare const SC_ADDR: {
+    readonly ACCOUNT: 0;
+    readonly CONTRACT: 1;
+    readonly MUXED_ACCOUNT: 2;
+    readonly CLAIMABLE_BALANCE: 3;
+    readonly LIQUIDITY_POOL: 4;
+};
+/** StrKey version bytes (SEP-23): the first base32 char of the encoded key. */
+export declare const STRKEY_VERSION: {
+    readonly ACCOUNT: number;
+    readonly MUXED_ACCOUNT: number;
+    readonly SEED: number;
+    readonly PRE_AUTH_TX: number;
+    readonly SHA256_HASH: number;
+    readonly SIGNED_PAYLOAD: number;
+    readonly CONTRACT: number;
+    readonly CLAIMABLE_BALANCE: number;
+    readonly LIQUIDITY_POOL: number;
+};
+export declare function base32Encode(data: Uint8Array, { padding }?: {
+    padding?: boolean;
+}): string;
+export declare function base32Decode(str: string): Buffer;
+export declare function crc16xmodem(data: Uint8Array): number;
+export declare function encodeStrKey(version: number, payload: Uint8Array): string;
+/** Decode a StrKey; validates the checksum and that the encoding is canonical. */
+export declare function decodeStrKey(str: string): {
+    version: number;
+    payload: Buffer;
+};
+/** Payload bytes of a StrKey, optionally asserting the version byte. */
+export declare function strKeyToBytes(str: string, expectedVersion?: number): Buffer;
+export declare function isValidStrKey(str: string, version?: number): boolean;
+/** Soroban contract id (`C...`, 56 chars). Format check only; use `isValidStrKey` for checksum validation. */
+export declare function isContractId(str: any): boolean;
+/** Classic account id (`G...`, 56 chars). Format check only. */
+export declare function isAccountId(str: any): boolean;
+export interface ClassicAsset {
+    /** asset code, `XLM` for the native asset */
+    code: string;
+    /** issuer account, undefined for the native asset */
+    issuer?: string;
+}
+export declare const NATIVE_ASSET: ClassicAsset;
+export declare function isNativeAsset(asset: ClassicAsset): boolean;
+/**
+ * Parse `native` / `XLM`, `CODE-ISSUER` (DefiLlama convention), `CODE:ISSUER`
+ * (Horizon / stellar.expert convention) or an already parsed `{ code, issuer }`.
+ */
+export declare function parseAsset(asset: string | ClassicAsset): ClassicAsset;
+/** `native` or `CODE-ISSUER` (or `CODE:ISSUER` with `separator: ':'`). */
+export declare function assetToString(asset: string | ClassicAsset, { separator }?: {
+    separator?: '-' | ':';
+}): string;
+/** Horizon 7-decimal display string -> stroops as a decimal string, using string math (no float rounding). */
+export declare function toRaw(amount: string | number, decimals?: number): string;
+/** Stroops -> display string (`"12.3456789"`), trailing zeros trimmed. */
+export declare function fromRaw(raw: string | number | bigint, decimals?: number): string;
+export declare class XdrWriter {
+    private chunks;
+    u32(value: number): this;
+    i32(value: number): this;
+    /** unsigned 64-bit, value must already be in range */
+    u64(value: bigint | number | string): this;
+    i64(value: bigint | number | string): this;
+    /** fixed length opaque, no length prefix, padded to 4 bytes */
+    bytes(data: Uint8Array): this;
+    /** variable length opaque: u32 length + data + padding */
+    opaque(data: Uint8Array): this;
+    string(value: string): this;
+    toBuffer(): Buffer;
+    toBase64(): string;
+}
+export declare class XdrReader {
+    offset: number;
+    readonly buf: Buffer;
+    constructor(input: Buffer | Uint8Array | string, offset?: number);
+    private need;
+    u32(): number;
+    i32(): number;
+    u64(): bigint;
+    i64(): bigint;
+    /** `words` big-endian u64 limbs -> unsigned bigint */
+    uintN(words: number): bigint;
+    intN(words: number): bigint;
+    bytes(n: number): Buffer;
+    opaque(): Buffer;
+    string(): string;
+    get remaining(): number;
+}
+export type ScValue = boolean | null | number | bigint | string | ScValue[] | {
+    [key: string]: ScValue;
+} | ScContractInstance | ScError;
+export interface ScError {
+    error: number;
+    code: number;
+}
+export interface ScContractInstance {
+    executable: {
+        type: 'wasm';
+        hash: string;
+    } | {
+        type: 'stellar_asset';
+    };
+    storage: {
+        [key: string]: ScValue;
+    };
+}
+/** Read one ScVal from the reader's current position. */
+export declare function readScVal(r: XdrReader): ScValue;
+/**
+ * Decode an ScVal from raw XDR bytes or a base64 string.
+ * u64/i64/u128/i128/u256/i256 -> bigint, bytes -> `0x` hex, addresses -> StrKey,
+ * vec -> array, map -> object keyed by the (stringified) key, void -> null.
+ */
+export declare function parseScVal(input: Buffer | Uint8Array | string, offset?: number): ScValue;
+export type ScArgType = 'bool' | 'void' | 'u32' | 'i32' | 'u64' | 'i64' | 'timepoint' | 'duration' | 'u128' | 'i128' | 'u256' | 'i256' | 'bytes' | 'string' | 'symbol' | 'address' | 'account' | 'vec' | 'map';
+/** Explicitly typed contract argument, e.g. `{ type: 'i128', value: '1000' }`. */
+export interface ScArg {
+    type: ScArgType;
+    value?: any;
+}
+/**
+ * Anything `callSoroban` accepts as an argument. Untyped values are mapped as:
+ * `G...` string -> address (account), `C...` string -> address (contract), number -> u32,
+ * bigint -> i128, boolean -> bool, null/undefined -> void, array -> vec of the same rules.
+ * Other strings must be tagged (`{ type: 'symbol' | 'string' | 'bytes', value }`).
+ */
+export type ScArgInput = ScArg | string | number | bigint | boolean | null | undefined | ScArgInput[];
+export declare function normalizeScArg(arg: ScArgInput): ScArg;
+/** ScVal::Symbol */
+export declare function writeSymbol(w: XdrWriter, name: string): XdrWriter;
+/** Tagged integer ScVal (u32/i32/u64/i64/u128/i128/u256/i256, timepoint/duration) with range check. */
+export declare function writeInt(w: XdrWriter, tag: number, value: bigint | number | string, bits: number, signed: boolean): XdrWriter;
+/** SCAddress (no ScVal tag) for a `G...` / `C...` StrKey. */
+export declare function writeScAddress(w: XdrWriter, address: string): XdrWriter;
+/** ScVal::Address */
+export declare function writeAddress(w: XdrWriter, address: string): XdrWriter;
+/** Append one ScVal for a (typed or untyped) argument. */
+export declare function writeScVal(w: XdrWriter, arg: ScArgInput): XdrWriter;
+/** Encode a single ScVal to bytes. */
+export declare function encodeScVal(arg: ScArgInput): Buffer;
+/** Classic `Asset` XDR (native / alphanum4 / alphanum12). */
+export declare function writeAsset(w: XdrWriter, asset: string | ClassicAsset): XdrWriter;
+export declare function getNetworkId(passphrase?: string): Buffer;
+/**
+ * Stellar Asset Contract id of a classic asset (or `native`):
+ * sha256(HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID { networkId, ContractIDPreimage::FROM_ASSET(asset) }).
+ */
+export declare function getSacContractId({ asset, networkPassphrase }: {
+    asset: string | ClassicAsset;
+    networkPassphrase?: string;
+}): string;
+/**
+ * Unsigned TransactionV1Envelope with a single InvokeHostFunction(InvokeContract)
+ * operation, as accepted by `simulateTransaction`. `source` defaults to the zero key.
+ */
+export declare function buildInvokeContractEnvelope({ contractId, method, args, source, fee }: {
+    contractId: string;
+    method: string;
+    args?: ScArgInput[];
+    source?: string;
+    fee?: number;
+}): Buffer;
+/** LedgerKey::ContractData { contract, key: LedgerKeyContractInstance, durability: PERSISTENT } */
+export declare function buildContractInstanceLedgerKey({ contractId }: {
+    contractId: string;
+}): Buffer;
+export interface HorizonBalanceRecord {
+    balance: string;
+    asset_type: 'native' | 'credit_alphanum4' | 'credit_alphanum12' | 'liquidity_pool_shares' | string;
+    asset_code?: string;
+    asset_issuer?: string;
+    liquidity_pool_id?: string;
+    limit?: string;
+    buying_liabilities?: string;
+    selling_liabilities?: string;
+    is_authorized?: boolean;
+    is_authorized_to_maintain_liabilities?: boolean;
+    is_clawback_enabled?: boolean;
+    last_modified_ledger?: number;
+}
+export interface AccountBalance {
+    /** `native`, `CODE-ISSUER` or `pool:<liquidity_pool_id>` */
+    asset: string;
+    assetType: string;
+    code?: string;
+    issuer?: string;
+    liquidityPoolId?: string;
+    /** Horizon display string (7 decimals) */
+    balance: string;
+    /** stroops (balance x 1e7) as decimal string */
+    raw: string;
+    limit?: string;
+    isAuthorized?: boolean;
+}
+export interface AssetSupply {
+    asset: string;
+    /** authorized + contracts + liquidity pools + claimable balances, stroops */
+    supply: string;
+    decimals: number;
+    authorized: string;
+    authorizedToMaintainLiabilities: string;
+    unauthorized: string;
+    contracts: string;
+    liquidityPools: string;
+    claimableBalances: string;
+    /** Horizon's own (deprecated) `amount` field, stroops; not part of `supply` */
+    amount: string;
+    numAccounts?: number;
+    numContracts?: number;
+    numClaimableBalances?: number;
+    numLiquidityPools?: number;
+}
+export interface LedgerInfo {
+    number: number;
+    /** unix seconds of `closed_at` */
+    timestamp: number;
+    closedAt: string;
+    hash: string;
+    protocolVersion?: number;
+    /** stroops */
+    totalCoins?: string;
+    successfulTransactionCount?: number;
+    failedTransactionCount?: number;
+    operationCount?: number;
+}
+/** GET `path` on Horizon with query `params`; rotates configured endpoints and retries transient failures. */
+export declare function horizonGet({ path, params }: {
+    path: string;
+    params?: Record<string, any>;
+}): Promise<any>;
+/** Raw Horizon account record (`/accounts/{id}`). Throws on unknown account. */
+export declare function getAccount({ address }: {
+    address: string;
+}): Promise<any>;
+/**
+ * All balances (native, trustlines, pool shares) of a classic account.
+ * A non-existent (never funded) account resolves to `[]`.
+ */
+export declare function getAccountBalances({ address }: {
+    address: string;
+}): Promise<AccountBalance[]>;
+/** XLM balance of an account in stroops. */
+export declare function getNativeBalance({ address }: {
+    address: string;
+}): Promise<string>;
+/**
+ * Balance of `asset` held by `address`, in stroops (7 decimals for classic assets and SACs,
+ * the token's own decimals for other Soroban tokens).
+ *  - `asset` is a `C...` contract id -> Soroban `balance(address)`
+ *  - `address` is a `C...` contract holding a classic asset -> `balance` on the asset's SAC
+ *  - otherwise the Horizon trustline balance (`0` when there is no trustline / account)
+ */
+export declare function getTokenBalance({ asset, address }: {
+    asset: string | ClassicAsset;
+    address: string;
+}): Promise<string>;
+/** Horizon `/assets` record for a classic asset, or `undefined` when Horizon does not know it. */
+export declare function getAsset({ code, issuer, asset }: {
+    code?: string;
+    issuer?: string;
+    asset?: string | ClassicAsset;
+}): Promise<any>;
+/**
+ * Circulating supply of a classic asset in stroops: authorized trustline balances plus
+ * amounts held by Soroban contracts (SAC), liquidity pools and claimable balances.
+ * `native` returns the ledger's `total_coins`.
+ */
+export declare function getAssetSupply({ asset, code, issuer }: {
+    asset?: string | ClassicAsset;
+    code?: string;
+    issuer?: string;
+}): Promise<AssetSupply>;
+/** Horizon ledger by sequence number, or the latest closed ledger. */
+export declare function getLedger({ sequence }?: {
+    sequence?: number | 'latest';
+}): Promise<LedgerInfo>;
+export declare function getLatestLedger(): Promise<LedgerInfo>;
+/**
+ * Last ledger closed at or before `timestamp` (unix seconds, ms accepted). Horizon has no
+ * time filter, so this is an interpolation search over `/ledgers/{seq}` (typically 4-8 requests).
+ */
+export declare function getLedgerAtTimestamp({ timestamp }: {
+    timestamp: number;
+}): Promise<LedgerInfo>;
+/** Raw Soroban JSON-RPC call; rotates configured endpoints and retries transport / rate-limit errors. */
+export declare function sorobanRpc(method: string, params?: any): Promise<any>;
+export declare function getLatestSorobanLedger(): Promise<{
+    number: number;
+    hash: string;
+    protocolVersion: number;
+}>;
+/**
+ * `simulateTransaction` on a base64 (or raw) TransactionEnvelope. Returns the RPC result;
+ * throws when the simulation itself failed (`result.error`).
+ */
+export declare function simulateTransaction({ transaction, resourceConfig }: {
+    transaction: string | Buffer;
+    resourceConfig?: {
+        instructionLeeway?: number;
+    };
+}): Promise<any>;
+/**
+ * Read-only contract call via `simulateTransaction`. Returns the decoded ScVal result
+ * (see `parseScVal` for the mapping). See `ScArgInput` for how untyped args are encoded.
+ */
+export declare function callSoroban({ contractId, method, args, source }: {
+    contractId: string;
+    method: string;
+    args?: ScArgInput[];
+    source?: string;
+}): Promise<ScValue>;
+export interface LedgerEntryResult {
+    key: string;
+    xdr: string;
+    lastModifiedLedgerSeq: number;
+    liveUntilLedgerSeq?: number;
+}
+/** `getLedgerEntries` for base64 (or raw) LedgerKey XDRs. Missing entries are simply absent from `entries`. */
+export declare function getLedgerEntries({ keys }: {
+    keys: (string | Buffer)[];
+}): Promise<{
+    entries: LedgerEntryResult[];
+    latestLedger: number;
+}>;
+/** Decoded SCContractInstance (executable + instance storage) of a contract. */
+export declare function getContractInstance({ contractId }: {
+    contractId: string;
+}): Promise<ScContractInstance>;
+/**
+ * Instance storage of a contract keyed by storage key (enum keys collapse to the variant
+ * name). Reads data not reachable through contract functions.
+ */
+export declare function getContractInstanceStorage({ contractId }: {
+    contractId: string;
+}): Promise<{
+    [key: string]: ScValue;
+}>;
+/** `balance(address)` as a decimal string in the token's smallest unit. */
+export declare function getSorobanTokenBalance({ contractId, address }: {
+    contractId: string;
+    address: string;
+}): Promise<string>;
+export declare function getSorobanTokenDecimals({ contractId }: {
+    contractId: string;
+}): Promise<number>;
+export declare function getSorobanTokenSymbol({ contractId }: {
+    contractId: string;
+}): Promise<string>;
+/** `name()`; a SAC returns `CODE:ISSUER` (or `native`), which is how `getSacClassicAsset` resolves it. */
+export declare function getSorobanTokenName({ contractId }: {
+    contractId: string;
+}): Promise<string>;
+/**
+ * `total_supply()` of a Soroban token as a decimal string, or `undefined` when the contract
+ * does not implement it (SACs do not; use `getAssetSupply` on the classic asset instead).
+ */
+export declare function getSorobanTokenTotalSupply({ contractId }: {
+    contractId: string;
+}): Promise<string | undefined>;
+/** Classic asset wrapped by a Stellar Asset Contract, or `undefined` for a non-SAC token. */
+export declare function getSacClassicAsset({ contractId }: {
+    contractId: string;
+}): Promise<ClassicAsset | undefined>;
+/**
+ * Total supply of any Stellar token id used by DefiLlama: `native`, `CODE-ISSUER`, or a
+ * `C...` contract (SAC -> Horizon supply of the wrapped asset, other tokens -> `total_supply()`).
+ * Resolves to `undefined` when a Soroban token exposes no `total_supply`.
+ */
+export declare function getTokenSupply({ token }: {
+    token: string | ClassicAsset;
+}): Promise<{
+    supply: string;
+    decimals: number;
+} | undefined>;