@getomnichain/omnichain 0.6.3 → 0.7.0

package/dist/esm/ton/ton_chain.d.ts

@@ -0,0 +1,205 @@
+import { type BroadcastOpts, Chain, type CreateTransferRequest, type GetTransactionStatusOpts, type VerifyMessageSignatureRequest } from '../chain.base.ts';
+import { ChainType } from '../chain_type.ts';
+import type { AbstractSignedMessage } from '../wallet.base.ts';
+import { TonAsset } from './ton_asset.ts';
+import { type TonJettonMetadata, type TonMetadataFetcher } from './ton_jetton_metadata.ts';
+import { type TonAccountState, type TonProvider, type TonTrace } from './ton_provider.ts';
+import { type TonTraceSummary, TonTransactionStatus } from './ton_transaction_status.ts';
+import { TonSignedTransaction, TonUnsignedTransaction } from './ton_transactions.ts';
+/** TON a jetton transfer carries to the sender's jetton wallet; the excess returns to `responseDestination`. */
+export declare const DEFAULT_JETTON_TRANSFER_ATTACHED_NANOTON = 50000000n;
+/** TON forwarded to the jetton recipient with the transfer notification. */
+export declare const DEFAULT_JETTON_FORWARD_NANOTON = 1n;
+/**
+ * How far past a request's `validUntil` the masterchain must be before the
+ * request counts as expired; shard blocks and the provider's state can trail
+ * the masterchain head by a few seconds.
+ */
+export declare const REQUEST_EXPIRY_MARGIN_SECONDS = 60;
+/** Where a signed request stands; see `TonChain.getRequestState`. */
+export type TonRequestState = 'live' | 'expired' | 'consumed';
+export interface TonProviderEndpoint {
+    url: string;
+    /**
+     * Required: the family never calls a provider without a key. When absent it
+     * is read at first use from `TONCENTER_API_KEY` / `TONAPI_API_KEY`.
+     */
+    apiKey?: string | null;
+    timeoutMs?: number;
+}
+export interface TonChainInit {
+    chainId: number;
+    name: string;
+    explorerUrl: string;
+    /** The main provider, TON Center v3. */
+    toncenter: TonProviderEndpoint;
+    /** The fallback, TonAPI; without a key there is no fallback. */
+    tonapi?: TonProviderEndpoint | null;
+    /** Replaces both, e.g. in tests. */
+    provider?: TonProvider;
+    /** Fetches a jetton's off-chain metadata JSON (https); replaceable, e.g. in tests. */
+    fetchMetadata?: TonMetadataFetcher;
+}
+/** A transfer, with TON's own options; see `TonChain.createTransferUnsignedTransaction`. */
+export interface TonTransferOptions extends CreateTransferRequest {
+    /** Overrides the message's bounce flag. */
+    bounce?: boolean;
+    /** Overrides the send mode. */
+    sendMode?: number;
+    /** Jetton transfers: TON attached to the sender's jetton wallet. */
+    jettonAttachedNanoton?: bigint;
+    /** Jetton transfers: TON forwarded to the recipient with the transfer notification. */
+    forwardTonAmountNanoton?: bigint;
+}
+export interface TonGetTransactionStatusOpts extends GetTransactionStatusOpts {
+    /** Masterchain blocks required after the trace is final. 0 by default: TON finality needs none. */
+    minMasterchainDepth?: number;
+}
+export interface TonEmulationResult extends TonTraceSummary {
+    trace: TonTrace;
+}
+/**
+ * A TON chain, read through TON Center v3 with TonAPI as the fallback.
+ *
+ * Transaction ids are normalized external-message hashes (lowercase hex), and
+ * a transaction's status covers its whole trace.
+ */
+export declare class TonChain extends Chain {
+    #private;
+    private readonly _nativeAsset;
+    constructor(init: TonChainInit);
+    /** The configured provider, built on first use so a chain without keys can still be constructed. */
+    get provider(): TonProvider;
+    get chainType(): ChainType;
+    get nativeToken(): TonAsset;
+    get nativeAsset(): TonAsset;
+    getWalletExplorerUrl(address: string): string;
+    /** A jetton master is a contract, so its link uses the bounceable (`EQ…`) form. */
+    getTokenExplorerUrl(tokenIdentifier?: string): string;
+    /** `null` for native TON. */
+    getAssetExplorerUrl(asset: TonAsset): string | null;
+    getTransactionExplorerUrl(txHash: string): string;
+    validateAddress(raw: string): boolean;
+    validateTokenIdentifier(raw: string | undefined): boolean;
+    getAccountState(address: string): Promise<TonAccountState>;
+    /**
+     * The wallet's seqno, read live from its get-method rather than from the
+     * indexed account state, which can trail a deploy; 0 while it has no code.
+     */
+    getSeqno(address: string): Promise<number>;
+    /**
+     * Native TON for no identifier; otherwise the jetton whose master
+     * `identifier` names, its symbol and decimals read from its TEP-64
+     * metadata ({@link getJettonMetadata}). Resolved jettons are kept for the
+     * chain's lifetime.
+     */
+    resolveAsset(identifier: string | null | undefined): Promise<TonAsset>;
+    /**
+     * A jetton's TEP-64 metadata: the master's `get_jetton_data` content, and the
+     * off-chain JSON its URI names (https) for what the content lacks. Throws
+     * `InvalidTokenIdentifier` for anything that is not a jetton master, and
+     * (retryably) when the decimals cannot be read.
+     */
+    getJettonMetadata(jettonMaster: string): Promise<TonJettonMetadata>;
+    createAsset(symbol: string, identifier: string | null | undefined, decimals: number): TonAsset;
+    getJettonAsset(symbol: string, jettonMaster: string, decimals: number): TonAsset;
+    /** The jetton wallet `owner` has (or will have) for `jettonMaster`, raw. */
+    getJettonWalletAddress(jettonMaster: string, owner: string): Promise<string>;
+    /** Nanotons, or the jetton's smallest unit when `tokenIdentifier` is a jetton master. */
+    getBalance(owner: string, tokenIdentifier?: string): Promise<bigint>;
+    /**
+     * A transfer from `from`: native TON (with `memo` as a text comment), or a
+     * jetton through the sender's jetton wallet, the excess returned to the
+     * sender. `amountHr` takes the jetton's decimals from its metadata.
+     *
+     * - `isFullBalance`: native TON sends everything the wallet holds (send mode
+     *   128 + 2, value 0); a jetton sends the jetton wallet's whole balance.
+     * - Native `bounce`, unless given: only to a bounceable (`EQ…`) address
+     *   that is deployed — a contract that fails then returns the TON, and a
+     *   wallet not deployed yet still receives it, as TON wallets send.
+     * - Jetton transfers are always bounceable unless `bounce` says otherwise,
+     *   carry {@link DEFAULT_JETTON_TRANSFER_ATTACHED_NANOTON} and forward
+     *   {@link DEFAULT_JETTON_FORWARD_NANOTON}; `jettonAttachedNanoton`,
+     *   `forwardTonAmountNanoton` and `sendMode` override.
+     */
+    createTransferUnsignedTransaction(req: TonTransferOptions): Promise<TonUnsignedTransaction>;
+    /**
+     * Emulates the whole trace of an external message (signature ignored): what
+     * it would cost, and whether every transaction would succeed with nothing
+     * bounced. Throws `SimulationFailed` when the message would be refused
+     * outright.
+     */
+    emulate(boc: string): Promise<TonEmulationResult>;
+    /**
+     * Sends an external message (base64 BOC or bytes) and returns its normalized
+     * hash. Throws `TonBroadcastUncertainError` when the message may have reached
+     * the network anyway; re-signing then can pay twice.
+     */
+    broadcast(signed: string | Uint8Array, opts?: BroadcastOpts): Promise<string>;
+    broadcastSignedTransaction(signed: TonSignedTransaction): Promise<string>;
+    getTransactionStatus(txHash: string, opts?: TonGetTransactionStatusOpts): Promise<TonTransactionStatus>;
+    getTransactionStatus(txHashes: string[], opts?: TonGetTransactionStatusOpts): Promise<TonTransactionStatus[]>;
+    /** The masterchain's latest block. */
+    getChainTipHeight(): Promise<number>;
+    /**
+     * Where a signed request stands, so it is never replaced while it can still
+     * execute — the one check to make before signing a replacement, after a
+     * `Failed` relayed request or an uncertain broadcast:
+     * - `consumed`: the wallet's seqno has moved past the request's, or (given
+     *   `hash`, for an external request) the request has a trace. It executed —
+     *   or another request signed with the same seqno did. Do not re-sign it;
+     *   read its status (`getTransactionStatus(hash)`, or the relay's).
+     * - `expired`: the chain's own time (not this machine's) is past
+     *   `validUntil` by {@link REQUEST_EXPIRY_MARGIN_SECONDS}, with the seqno
+     *   not moved past it and no trace. It can never execute; replacing it is
+     *   safe.
+     * - `live`: neither yet. It can still execute — a relayed request that
+     *   failed included: W5 keeps an internal request's seqno only when the
+     *   transaction succeeds, so anyone can deliver it again from the trace
+     *   until `validUntil`.
+     *
+     * `wallet` is the wallet that signed it: the sender of an external request,
+     * the target of a relayed one (pass no `hash` for a relayed request; a
+     * relay's own hash is the relayer's request). All reads come from one
+     * provider.
+     */
+    getRequestState(args: {
+        wallet: string;
+        seqno: number;
+        validUntil: number;
+        hash?: string;
+    }): Promise<TonRequestState>;
+    /** Native TON bounces only to a bounceable (`EQ…`) address that is deployed. */
+    private bouncesByDefault;
+    private assertTxHash;
+    private onOneProvider;
+    /**
+     * Whether `signedMessage` is `publicKey`'s signature of `message`
+     * (`TonWallet.signMessage`: ed25519 over {@link tonMessageHash}). Needs only
+     * the public key — 32 bytes, or 64 hex characters — as Tron's and
+     * Stellar's do. A signature must be exactly 128 hex characters.
+     */
+    static verifySignature(publicKey: Uint8Array | string, message: string, signedMessage: AbstractSignedMessage): boolean;
+    /**
+     * TON addresses do not reveal their key, so a signature cannot be checked
+     * against an address alone: use `TonChain.verifySignature` with the
+     * signer's public key (its W5 address is `WalletContractV5R1.create({
+     * publicKey, workchain: 0 }).address`).
+     */
+    verifyMessageSignature(_req: VerifyMessageSignatureRequest): Promise<boolean>;
+    private statusOf;
+    /**
+     * Adds the jetton balance changes of the trace's wallet-to-wallet jetton
+     * transfers (TEP-74 \`transfer\` → \`internal_transfer\`) to
+     * \`balanceChanges\`: the sending owner loses the amount and the recipient
+     * gains it, in the jetton's asset ({@link resolveAsset}).
+     *
+     * A transfer counts only once its master vouches for both jetton wallets:
+     * the sender's must be the master's wallet for the owner it reports, and
+     * the receiving one the master's wallet for the recipient the transfer
+     * named. Anything else — a contract posing as a jetton wallet, a mint or a
+     * burn — moves no balance here.
+     */
+    private addJettonBalanceChanges;
+}
+//# sourceMappingURL=ton_chain.d.ts.map

package/dist/esm/ton/ton_chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ton_chain.d.ts","sourceRoot":"","sources":["../../../ton/ton_chain.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,EACL,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,6BAA6B,EAEnC,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAI7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE/D,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAyB,MAAM,0BAA0B,CAAC;AASlH,OAAO,EACL,KAAK,eAAe,EAKpB,KAAK,WAAW,EAEhB,KAAK,QAAQ,EAGd,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAwB,KAAK,eAAe,EAAE,oBAAoB,EAAqB,MAAM,6BAA6B,CAAC;AAClI,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAsB,MAAM,uBAAuB,CAAC;AAEzG,gHAAgH;AAChH,eAAO,MAAM,wCAAwC,YAAc,CAAC;AACpE,4EAA4E;AAC5E,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAShD,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,gEAAgE;IAChE,MAAM,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACpC,oCAAoC;IACpC,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,sFAAsF;IACtF,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED,4FAA4F;AAC5F,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,uFAAuF;IACvF,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB;IAC3E,mGAAmG;IACnG,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,QAAS,SAAQ,KAAK;;IAIjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;gBAE5B,IAAI,EAAE,YAAY;IAO9B,oGAAoG;IACpG,IAAI,QAAQ,IAAI,WAAW,CAkB1B;IAED,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED,IAAI,WAAW,IAAI,QAAQ,CAE1B;IAED,IAAI,WAAW,IAAI,QAAQ,CAE1B;IAED,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI7C,mFAAmF;IACnF,mBAAmB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM;IAKrD,6BAA6B;IAC7B,mBAAmB,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI;IAOnD,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAIjD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IASrC,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAIzD,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAI1D;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;OAKG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAa5E;;;;;OAKG;IACG,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIzE,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAU9F,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ;IAIhF,4EAA4E;IAC5E,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5E,yFAAyF;IACnF,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1E;;;;;;;;;;;;;;OAcG;IACG,iCAAiC,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuDjG;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAOvD;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBnF,0BAA0B,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,MAAM,CAAC;IAOzE,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,CAAC;IACvG,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,2BAA2B,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;IAa7G,sCAAsC;IAChC,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAI1C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,eAAe,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAmC3H,gFAAgF;YAClE,gBAAgB;IAK9B,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;IAKrB;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,qBAAqB,GAAG,OAAO;IActH;;;;;OAKG;IACG,sBAAsB,CAAC,IAAI,EAAE,6BAA6B,GAAG,OAAO,CAAC,OAAO,CAAC;YAQrE,QAAQ;IActB;;;;;;;;;;;OAWG;YACW,uBAAuB;CA8BtC"}