@metamask/keyring-api 10.1.0 → 11.1.0

package/dist/api/transaction.d.mts

@@ -0,0 +1,773 @@
+import type { Infer } from "@metamask/superstruct";
+import type { InferEquals } from "../superstruct.mjs";
+import type { Paginated } from "../utils/index.mjs";
+/**
+ * Fee types.
+ */
+export declare enum FeeType {
+    /**
+     * Base fee. It is the minimum fee required to include a transaction in the
+     * blockchain.
+     *
+     * For non-confirmed transactions, it must be the maximum base fee. For
+     * confirmed transactions, it must be the actual base fee paid.
+     */
+    Base = "base",
+    /**
+     * Priority fee. It is an optional fee used to prioritize the transaction.
+     *
+     * For non-confirmed transactions, it must be the maximum priority fee. For
+     * confirmed transactions, it must be the actual priority fee paid.
+     */
+    Priority = "priority"
+}
+/**
+ * Transaction statuses.
+ */
+export declare enum TransactionStatus {
+    /**
+     * The transaction has been submitted but is not yet in the
+     * blockchain. For example, it can be in the mempool.
+     */
+    Submitted = "submitted",
+    /**
+     * The transaction is in the blockchain but has not been
+     * confirmed yet.
+     */
+    Unconfirmed = "unconfirmed",
+    /**
+     * The transaction has been confirmed.
+     */
+    Confirmed = "confirmed",
+    /**
+     * The transaction has failed. For example, it has been reverted.
+     */
+    Failed = "failed"
+}
+/**
+ * Transaction types.
+ */
+export declare enum TransactionType {
+    /**
+     * The transaction was originated by the account. If the transaction
+     * has a change output that goes back to the same account, it must be tagged
+     * as a send transaction.
+     */
+    Send = "send",
+    /**
+     * The transaction was received by the account, but originated by
+     * another account.
+     */
+    Receive = "receive"
+}
+/**
+ * This struct represents a transaction event.
+ */
+export declare const TransactionEventStruct: import("@metamask/superstruct").Struct<{
+    status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+    timestamp: number | null;
+}, {
+    /**
+     * New status of the transaction.
+     */
+    status: import("@metamask/superstruct").Struct<"submitted" | "unconfirmed" | "confirmed" | "failed", {
+        submitted: "submitted";
+        unconfirmed: "unconfirmed";
+        confirmed: "confirmed";
+        failed: "failed";
+    }>;
+    /**
+     * UNIX timestamp of when the event occurred.
+     */
+    timestamp: import("@metamask/superstruct").Struct<number | null, null>;
+}>;
+/**
+ * This struct represents a blockchain transaction.
+ *
+ * @example
+ * ```ts
+ * const tx = {
+ *   id: 'f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6',
+ *   chain: 'bip122:000000000019d6689c085ae165831e93',
+ *   account: 'b9beb861-9761-4b97-89ce-d992be5f34da',
+ *   status: 'confirmed',
+ *   timestamp: 1716367781,
+ *   type: 'send',
+ *   from: [
+ *     {
+ *       address: 'bc1qrp0yzgkf8rawkuvdlhnjfj2fnjwm0m8727kgah',
+ *       asset: {
+ *         fungible: true,
+ *         type: 'bip122:000000000019d6689c085ae165831e93/slip44:0',
+ *         unit: 'BTC',
+ *         amount: '0.1',
+ *       },
+ *     },
+ *   ],
+ *   to: [
+ *     {
+ *       address: 'bc1qrp0yzgkf8rawkuvdlhnjfj2fnjwm0m8727kgah',
+ *       asset: {
+ *         fungible: true,
+ *         type: 'bip122:000000000019d6689c085ae165831e93/slip44:0',
+ *         unit: 'BTC',
+ *         amount: '0.1',
+ *       },
+ *     },
+ *     {
+ *       address: 'bc1qwl8399fz829uqvqly9tcatgrgtwp3udnhxfq4k',
+ *       asset: {
+ *         fungible: true,
+ *         type: 'bip122:000000000019d6689c085ae165831e93/slip44:0',
+ *         unit: 'BTC',
+ *         amount: '0.1',
+ *       },
+ *     },
+ *   ],
+ *   fees: [
+ *     {
+ *       type: 'priority',
+ *       asset: {
+ *         fungible: true,
+ *         type: 'bip122:000000000019d6689c085ae165831e93/slip44:0',
+ *         unit: 'BTC',
+ *         amount: '0.1',
+ *       },
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export declare const TransactionStruct: import("@metamask/superstruct").Struct<{
+    type: "send" | "receive";
+    id: string;
+    account: string;
+    status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+    timestamp: number | null;
+    chain: `${string}:${string}`;
+    from: {
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }[];
+    to: {
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }[];
+    fees: {
+        type: "base" | "priority";
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        };
+    }[];
+    events: {
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+    }[];
+}, {
+    /**
+     * Chain-specific transaction ID.
+     */
+    id: import("@metamask/superstruct").Struct<string, null>;
+    /**
+     * Chain ID (CAIP-2).
+     */
+    chain: import("@metamask/superstruct").Struct<`${string}:${string}`, null>;
+    /**
+     * Account ID (UUIDv4).
+     */
+    account: import("@metamask/superstruct").Struct<string, null>;
+    /**
+     * Transaction status {@see TransactionStatus}.
+     */
+    status: import("@metamask/superstruct").Struct<"submitted" | "unconfirmed" | "confirmed" | "failed", {
+        submitted: "submitted";
+        unconfirmed: "unconfirmed";
+        confirmed: "confirmed";
+        failed: "failed";
+    }>;
+    /**
+     * UNIX timestamp of when the transaction was added to the blockchain. The
+     * timestamp can be null if the transaction has not been included in the
+     * blockchain yet.
+     */
+    timestamp: import("@metamask/superstruct").Struct<number | null, null>;
+    /**
+     * Transaction type {@see TransactionType}. This will be used by MetaMask to enrich the transaction
+     * details on the UI.
+     */
+    type: import("@metamask/superstruct").Struct<"send" | "receive", {
+        send: "send";
+        receive: "receive";
+    }>;
+    /**
+     * Transaction sender addresses and amounts.
+     */
+    from: import("@metamask/superstruct").Struct<{
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }[], import("@metamask/superstruct").Struct<{
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }, {
+        /**
+         * Participant address.
+         */
+        address: import("@metamask/superstruct").Struct<string, null>;
+        /**
+         * Asset being transferred.
+         */
+        asset: import("@metamask/superstruct").Struct<{
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null, null>;
+    }>>;
+    /**
+     * Transaction receiver addresses and amounts.
+     */
+    to: import("@metamask/superstruct").Struct<{
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }[], import("@metamask/superstruct").Struct<{
+        address: string;
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null;
+    }, {
+        /**
+         * Participant address.
+         */
+        address: import("@metamask/superstruct").Struct<string, null>;
+        /**
+         * Asset being transferred.
+         */
+        asset: import("@metamask/superstruct").Struct<{
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        } | null, null>;
+    }>>;
+    /**
+     * Total transaction fee.
+     */
+    fees: import("@metamask/superstruct").Struct<{
+        type: "base" | "priority";
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        };
+    }[], import("@metamask/superstruct").Struct<{
+        type: "base" | "priority";
+        asset: {
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        };
+    }, {
+        /**
+         * Fee type {@see FeeType}.
+         */
+        type: import("@metamask/superstruct").Struct<"base" | "priority", {
+            base: "base";
+            priority: "priority";
+        }>;
+        /**
+         * Asset used to pay for the fee.
+         */
+        asset: import("@metamask/superstruct").Struct<{
+            type: `${string}:${string}/${string}:${string}`;
+            fungible: true;
+            unit: string;
+            amount: string;
+        } | {
+            id: `${string}:${string}/${string}:${string}/${string}`;
+            fungible: false;
+        }, null>;
+    }>>;
+    /**
+     * List of events related to the transaction {@see TransactionEventStruct}.
+     *
+     * The events are tracked in a best-effort basis and may not be available for
+     * all transactions.
+     */
+    events: import("@metamask/superstruct").Struct<{
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+    }[], import("@metamask/superstruct").Struct<{
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+    }, {
+        /**
+         * New status of the transaction.
+         */
+        status: import("@metamask/superstruct").Struct<"submitted" | "unconfirmed" | "confirmed" | "failed", {
+            submitted: "submitted";
+            unconfirmed: "unconfirmed";
+            confirmed: "confirmed";
+            failed: "failed";
+        }>;
+        /**
+         * UNIX timestamp of when the event occurred.
+         */
+        timestamp: import("@metamask/superstruct").Struct<number | null, null>;
+    }>>;
+}>;
+/**
+ * Transaction object.
+ *
+ * See {@link TransactionStruct}.
+ */
+export type Transaction = Infer<typeof TransactionStruct>;
+/**
+ * This struct represents a page of transactions.
+ *
+ * @example
+ * ```ts
+ * {
+ *   data: [
+ *     {
+ *       // Transaction object
+ *     }
+ *   ],
+ *   next: 'c3y1Q6QtqtstbxKX+oqVdEW6',
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * {
+ *   data: [
+ *     {
+ *       // Transaction object
+ *     }
+ *   ],
+ *   next: null, // No more results
+ * }**
+ * ```
+ */
+export declare const TransactionsPageStruct: import("@metamask/superstruct").Struct<{
+    next: string | null;
+    data: {
+        type: "send" | "receive";
+        id: string;
+        account: string;
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+        chain: `${string}:${string}`;
+        from: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        to: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        fees: {
+            type: "base" | "priority";
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            };
+        }[];
+        events: {
+            status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+            timestamp: number | null;
+        }[];
+    }[];
+}, {
+    /**
+     * List of transactions.
+     */
+    data: import("@metamask/superstruct").Struct<{
+        type: "send" | "receive";
+        id: string;
+        account: string;
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+        chain: `${string}:${string}`;
+        from: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        to: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        fees: {
+            type: "base" | "priority";
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            };
+        }[];
+        events: {
+            status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+            timestamp: number | null;
+        }[];
+    }[], import("@metamask/superstruct").Struct<{
+        type: "send" | "receive";
+        id: string;
+        account: string;
+        status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+        timestamp: number | null;
+        chain: `${string}:${string}`;
+        from: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        to: {
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[];
+        fees: {
+            type: "base" | "priority";
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            };
+        }[];
+        events: {
+            status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+            timestamp: number | null;
+        }[];
+    }, {
+        /**
+         * Chain-specific transaction ID.
+         */
+        id: import("@metamask/superstruct").Struct<string, null>;
+        /**
+         * Chain ID (CAIP-2).
+         */
+        chain: import("@metamask/superstruct").Struct<`${string}:${string}`, null>;
+        /**
+         * Account ID (UUIDv4).
+         */
+        account: import("@metamask/superstruct").Struct<string, null>;
+        /**
+         * Transaction status {@see TransactionStatus}.
+         */
+        status: import("@metamask/superstruct").Struct<"submitted" | "unconfirmed" | "confirmed" | "failed", {
+            submitted: "submitted";
+            unconfirmed: "unconfirmed";
+            confirmed: "confirmed";
+            failed: "failed";
+        }>;
+        /**
+         * UNIX timestamp of when the transaction was added to the blockchain. The
+         * timestamp can be null if the transaction has not been included in the
+         * blockchain yet.
+         */
+        timestamp: import("@metamask/superstruct").Struct<number | null, null>;
+        /**
+         * Transaction type {@see TransactionType}. This will be used by MetaMask to enrich the transaction
+         * details on the UI.
+         */
+        type: import("@metamask/superstruct").Struct<"send" | "receive", {
+            send: "send";
+            receive: "receive";
+        }>;
+        /**
+         * Transaction sender addresses and amounts.
+         */
+        from: import("@metamask/superstruct").Struct<{
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[], import("@metamask/superstruct").Struct<{
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }, {
+            /**
+             * Participant address.
+             */
+            address: import("@metamask/superstruct").Struct<string, null>;
+            /**
+             * Asset being transferred.
+             */
+            asset: import("@metamask/superstruct").Struct<{
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null, null>;
+        }>>;
+        /**
+         * Transaction receiver addresses and amounts.
+         */
+        to: import("@metamask/superstruct").Struct<{
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }[], import("@metamask/superstruct").Struct<{
+            address: string;
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null;
+        }, {
+            /**
+             * Participant address.
+             */
+            address: import("@metamask/superstruct").Struct<string, null>;
+            /**
+             * Asset being transferred.
+             */
+            asset: import("@metamask/superstruct").Struct<{
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            } | null, null>;
+        }>>;
+        /**
+         * Total transaction fee.
+         */
+        fees: import("@metamask/superstruct").Struct<{
+            type: "base" | "priority";
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            };
+        }[], import("@metamask/superstruct").Struct<{
+            type: "base" | "priority";
+            asset: {
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            };
+        }, {
+            /**
+             * Fee type {@see FeeType}.
+             */
+            type: import("@metamask/superstruct").Struct<"base" | "priority", {
+                base: "base";
+                priority: "priority";
+            }>;
+            /**
+             * Asset used to pay for the fee.
+             */
+            asset: import("@metamask/superstruct").Struct<{
+                type: `${string}:${string}/${string}:${string}`;
+                fungible: true;
+                unit: string;
+                amount: string;
+            } | {
+                id: `${string}:${string}/${string}:${string}/${string}`;
+                fungible: false;
+            }, null>;
+        }>>;
+        /**
+         * List of events related to the transaction {@see TransactionEventStruct}.
+         *
+         * The events are tracked in a best-effort basis and may not be available for
+         * all transactions.
+         */
+        events: import("@metamask/superstruct").Struct<{
+            status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+            timestamp: number | null;
+        }[], import("@metamask/superstruct").Struct<{
+            status: "submitted" | "unconfirmed" | "confirmed" | "failed";
+            timestamp: number | null;
+        }, {
+            /**
+             * New status of the transaction.
+             */
+            status: import("@metamask/superstruct").Struct<"submitted" | "unconfirmed" | "confirmed" | "failed", {
+                submitted: "submitted";
+                unconfirmed: "unconfirmed";
+                confirmed: "confirmed";
+                failed: "failed";
+            }>;
+            /**
+             * UNIX timestamp of when the event occurred.
+             */
+            timestamp: import("@metamask/superstruct").Struct<number | null, null>;
+        }>>;
+    }>>;
+    /**
+     * Next cursor to iterate over the results. If null, there are no more
+     * results.
+     */
+    next: import("@metamask/superstruct").Struct<string | null, null>;
+}>;
+/**
+ * Transactions page object.
+ *
+ * See {@link TransactionsPageStruct}.
+ */
+export type TransactionsPage = InferEquals<typeof TransactionsPageStruct, Paginated<Transaction>>;
+//# sourceMappingURL=transaction.d.mts.map