@bestinslot/wallet-kit 0.13.8 → 0.14.1

package/dist/types/api/brc20.d.ts

@@ -1,4 +1,5 @@
 import { Brc20SendQuote, SendAsBrc20Args, SendAsBrc20ProgArgs, SendAsBrc20ProgResult, SendAsBrc20Result } from '../core/brc20-send';
+import { FrBtcResult, UnwrapBtcFromBrc20ProgArgs, WrapBtcToBrc20ProgArgs } from '../core/frbtc';
 import { BISWalletPurpose, PaymentOpts } from '../types/common';
 export type { Brc20AmountOptions, Brc20DeployOptions, Brc20PredeployOptions, Brc20PredeployResult, } from '../core/brc20-inscriptions';
 export { computeBrc20PredeployHash, deployBrc20Inscription, generateBrc20Salt, mintBrc20Inscription, predeployInscriptions, transferBrc20Inscription, } from '../core/brc20-inscriptions';
@@ -43,6 +44,48 @@ export declare function sendAsBrc20Prog(args: SendAsBrc20ProgArgs & {
     dryRun: false;
 }): Promise<SendAsBrc20ProgResult>;
 export declare function sendAsBrc20Prog(args: SendAsBrc20ProgArgs): Promise<Brc20SendQuote | SendAsBrc20ProgResult>;
+export type { FrBtcResult, UnwrapBtcFromBrc20ProgArgs, WrapBtcToBrc20ProgArgs } from '../core/frbtc';
+export { getFrBtcAddress } from '../core/frbtc';
+/**
+ * Wraps BTC into frBTC held by the wallet's own BRC2.0 address, with no smart wallet involved. One
+ * call inscription runs `wrap()` on Subfrost's frBTC contract; its send transaction pays `amount`
+ * sats to the frBTC signer, and the contract mints frBTC, less its `premium()` fee, to the ordinals
+ * address's BRC2.0 address.
+ *
+ * With `dryRun: true` nothing is signed or broadcast and the result is a fee quote whose
+ * `paymentSats` is the wrapped amount. `onSignRequest` is called before each wallet prompt with
+ * `{ step, total }`; `total` is 2.
+ *
+ * @param args - `amount` (bigint sats, at least 546), `feeRate` (sats/vB), `dryRun`, and optional `onSignRequest`.
+ * @returns The quote for a dry run; otherwise the call's transaction ids plus every txid in chain order.
+ */
+export declare function wrapBtcToBrc20Prog(args: WrapBtcToBrc20ProgArgs & {
+    dryRun: true;
+}): Promise<Brc20SendQuote>;
+export declare function wrapBtcToBrc20Prog(args: WrapBtcToBrc20ProgArgs & {
+    dryRun: false;
+}): Promise<FrBtcResult>;
+export declare function wrapBtcToBrc20Prog(args: WrapBtcToBrc20ProgArgs): Promise<Brc20SendQuote | FrBtcResult>;
+/**
+ * Unwraps frBTC held by the wallet's own BRC2.0 address into BTC paid to `recipient`, with no smart
+ * wallet involved. One call inscription runs `unwrap2` on Subfrost's frBTC contract, which burns the
+ * frBTC and queues the payment; its send transaction pays a 546-sat marker to the frBTC signer, which
+ * pays the BTC out in a later Bitcoin transaction.
+ *
+ * With `dryRun: true` nothing is signed or broadcast and the result is a fee quote. `onSignRequest` is
+ * called before each wallet prompt with `{ step, total }`; `total` is 2.
+ *
+ * @param args - `amount` (bigint sats), `recipient` (Bitcoin address), `feeRate` (sats/vB), `dryRun`, and optional `onSignRequest`.
+ * @returns The quote for a dry run; otherwise the call's transaction ids plus every txid in chain order.
+ * @throws {Error} When the BRC2.0 frBTC balance is below `amount`, before anything is signed.
+ */
+export declare function unwrapBtcFromBrc20Prog(args: UnwrapBtcFromBrc20ProgArgs & {
+    dryRun: true;
+}): Promise<Brc20SendQuote>;
+export declare function unwrapBtcFromBrc20Prog(args: UnwrapBtcFromBrc20ProgArgs & {
+    dryRun: false;
+}): Promise<FrBtcResult>;
+export declare function unwrapBtcFromBrc20Prog(args: UnwrapBtcFromBrc20ProgArgs): Promise<Brc20SendQuote | FrBtcResult>;
 /**
  * Interface representing the result of an inscription and send to OP_RETURN operation, including transaction IDs, signed transaction hexes, inscription ID, postage, and secret used in the minting process. This interface is used to encapsulate the details of the deploy, call and deposit operations in the BRC2.0 programmable module.
  *

package/dist/types/api/helpers.d.ts

@@ -1,3 +1,4 @@
+export { BackendError } from '../core/backend-error';
 export { getEvmAddressFromBitcoinAddress, getEvmAddressFromPkScript } from '../core/brc20';
 export { delegateInscription, jsonInscription, textInscription } from '../types/inscription';
 export { addressWalletInfo, opReturnWalletInfo } from '../types/wallet';

package/dist/types/core/backend-error.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Thrown when a backend request fails: the request did not complete, the response had a 4xx/5xx
+ * status, or a 2xx body carried an `error` field.
+ *
+ * Branch on `code`, the backend's stable machine-readable code (e.g. `WALLET_KEY_MISMATCH`,
+ * `FEES_INSUFFICIENT`, `SEQUENCER_HALTED`), and fall back to `status`. `detail` is the backend's
+ * own English text; `message` is that text prefixed with `API Request Failed: `. `ref` is the
+ * backend's ID for the failed request, which its logs carry too.
+ */
+export declare class BackendError extends Error {
+    readonly detail: string;
+    readonly status: number | undefined;
+    readonly code: string | undefined;
+    readonly url: string;
+    readonly ref?: string | undefined;
+    /**
+     * @param detail The backend's error text, or a description of the transport failure.
+     * @param status The HTTP status, or `undefined` when no response arrived.
+     * @param code The backend's error code, when its body carried one.
+     * @param url The requested URL.
+     * @param ref The backend's request ID, when its body carried one.
+     */
+    constructor(detail: string, status: number | undefined, code: string | undefined, url: string, ref?: string | undefined);
+}
+/** The error built from a JSON body with an `error` field, carrying its `code` and `ref`. */
+export declare function backendErrorFromBody(body: any, status: number, url: string): BackendError;
+/**
+ * Reads an error response body: a JSON `{ error, code, ref }` object, any other JSON value, or
+ * plain text. An empty body falls back to the status line.
+ */
+export declare function backendErrorFromResponse(response: Response, url: string): Promise<BackendError>;

package/dist/types/core/brc20-send.d.ts

@@ -1,4 +1,6 @@
 import { SignProgressOptions } from './sign-progress';
+import { InscriptionDetails } from '../types/inscription';
+import { WalletInfo } from '../types/wallet';
 /** The transactions of one inscribe-and-send step. */
 export interface Brc20SendPart {
     commitTxId: string;
@@ -14,21 +16,47 @@ export interface Brc20SendStepQuote {
     minerFeeSats: number;
     /** Sats the send leaves on its target output (the recipient's postage, or 1 sat on OP_RETURN). */
     postageSats: number;
+    /** Sats the send pays to its extra outputs, such as the BTC an frBTC wrap sends to the signer. */
+    paymentSats: number;
     /** Wallet prompts this step raises. */
     walletPrompts: number;
 }
 /** What a composite send costs, built without signing or broadcasting. */
 export interface Brc20SendQuote {
-    /** Sats the wallet spends in all: miner fees plus postage. */
+    /** Sats the wallet spends in all: miner fees, postage and payments. */
     totalSats: number;
     minerFeeSats: number;
     postageSats: number;
+    paymentSats: number;
     /** Wallet prompts the real send raises; `onSignRequest` reports each of them. */
     walletPrompts: number;
     feeRate: number;
     steps: Brc20SendStepQuote[];
 }
-export type Brc20SendStepName = 'brc20Transfer' | 'progWithdraw' | 'progDeposit' | 'progTransfer';
+export type Brc20SendStepName = 'brc20Transfer' | 'progWithdraw' | 'progDeposit' | 'progTransfer' | 'frBtcWrap' | 'frBtcUnwrap';
+/** An output the send transaction carries right after the target, at vout 1, 2, …. */
+export interface ChainExtraOutput {
+    wallet: WalletInfo;
+    value: number;
+}
+export interface ChainStep {
+    name: Brc20SendStepName;
+    inscription: InscriptionDetails;
+    target: WalletInfo;
+    extraOutputs?: ChainExtraOutput[];
+    /** Most inputs the send may spend; the chain is refused before broadcast when it spends more. */
+    maxSendInputs?: number;
+}
+export interface ChainResult {
+    parts: Record<string, Brc20SendPart>;
+    txIds: string[];
+}
+export declare function opReturnTarget(): WalletInfo;
+/**
+ * Builds a `brc20-prog` call inscription. BRC2.0 grants `content bytes × GAS_PER_BYTE` gas, so the
+ * content is padded with spaces when its bytes alone fall short of `gasCeiling`.
+ */
+export declare function callInscription(contractAddress: string, calldata: string, gasCeiling: number): Promise<InscriptionDetails>;
 /**
  * Parses a BRC-20 decimal amount string into an 18-decimal bigint.
  *
@@ -36,6 +64,9 @@ export type Brc20SendStepName = 'brc20Transfer' | 'progWithdraw' | 'progDeposit'
  * @param label - The argument name used in error messages.
  */
 export declare function parseBrc20Amount(value: string, label: string): bigint;
+export declare function assertRecipient(recipient: string): void;
+export declare function assertFeeRate(feeRate: number): void;
+export declare function runChain(steps: ChainStep[], feeRate: number, dryRun: boolean, options: SignProgressOptions): Promise<Brc20SendQuote | ChainResult>;
 export interface SendAsBrc20Args extends SignProgressOptions {
     tick: string;
     /** Amount taken from the sender's base BRC-20 balance, as a decimal string; `"0"` skips it. */

package/dist/types/core/frbtc.d.ts

@@ -0,0 +1,58 @@
+import { Brc20SendPart, Brc20SendQuote } from './brc20-send';
+import { SignProgressOptions } from './sign-progress';
+import { Buffer } from 'node:buffer';
+/**
+ * Value of the marker output an unwrap pays the frBTC signer, and the smallest wrap: the dust limit
+ * of every standard output type.
+ */
+export declare const FRBTC_SIGNER_DUST_SATS = 546;
+/**
+ * Returns the frBTC contract address on the selected network, lowercased.
+ *
+ * @throws {Error} On a network without frBTC (testnet).
+ */
+export declare function getFrBtcAddress(): string;
+/** Reads the output script of the frBTC signer, which receives wrapped BTC and unwrap markers. */
+export declare function getFrBtcSignerScript(): Promise<Buffer>;
+/**
+ * Reads the frBTC balance held by a Bitcoin address's BRC2.0 (EVM) address.
+ *
+ * @param bitcoinAddress - The Bitcoin address whose BRC2.0 balance to read; the ordinals address for a connected wallet.
+ * @returns The balance in sats (frBTC has 8 decimals).
+ */
+export declare function getFrBtcBalanceOfAddress(bitcoinAddress: string): Promise<bigint>;
+export interface WrapBtcToBrc20ProgArgs extends SignProgressOptions {
+    /** BTC to wrap, in sats. The wallet's BRC2.0 address receives the frBTC. */
+    amount: bigint;
+    feeRate: number;
+    dryRun: boolean;
+}
+export interface UnwrapBtcFromBrc20ProgArgs extends SignProgressOptions {
+    /** frBTC to unwrap, in sats, taken from the wallet's BRC2.0 balance. */
+    amount: bigint;
+    /** Bitcoin address the signer pays the BTC to. */
+    recipient: string;
+    feeRate: number;
+    dryRun: boolean;
+}
+export interface FrBtcResult {
+    /** The call inscription's commit, reveal and send transactions. */
+    call: Brc20SendPart;
+    /** Every broadcast transaction id, in chain order. */
+    txIds: string[];
+}
+/**
+ * Wraps BTC into frBTC held by the wallet's own BRC2.0 address. One call inscription runs `wrap()` on
+ * the frBTC contract, and its send transaction pays `amount` sats to the frBTC signer at vout 1; the
+ * contract mints frBTC, less its `premium()` fee, to the inscription's owner, the ordinals address.
+ */
+export declare function wrapBtcToBrc20Prog(args: WrapBtcToBrc20ProgArgs): Promise<Brc20SendQuote | FrBtcResult>;
+/**
+ * Unwraps frBTC held by the wallet's own BRC2.0 address into BTC paid to `recipient`. One call
+ * inscription runs `unwrap2(amount, 1, recipientScript)` on the frBTC contract, and its send
+ * transaction pays a 546-sat marker to the frBTC signer at vout 1. The contract burns the frBTC and
+ * queues the payment; the signer pays it out in a later Bitcoin transaction.
+ *
+ * @throws {Error} When the BRC2.0 frBTC balance is below `amount`, before anything is signed.
+ */
+export declare function unwrapBtcFromBrc20Prog(args: UnwrapBtcFromBrc20ProgArgs): Promise<Brc20SendQuote | FrBtcResult>;

package/dist/types/core/helpers.d.ts

@@ -220,15 +220,13 @@ export declare function verifySignature(message: string, signatureHex: string, a
  */
 export declare function verifySignatureLocal(message: string, signatureHex: string, address: string): boolean;
 /**
- * A generic helper function to handle fetch requests with consistent error handling.
- * It automatically checks for non-ok HTTP responses and for an 'error' field
- * in the JSON response body, throwing a descriptive error in either case.
+ * Fetches a backend JSON route.
  *
  * @param url The URL to fetch.
  * @param options The standard RequestInit options for the fetch call.
  * @returns A promise that resolves with the parsed JSON data of type T.
- * @throws {Error} Throws an error if the network request fails, the HTTP
- * status is not ok, or the response body contains an error field.
+ * @throws {BackendError} When the request does not complete, the HTTP status is not ok, the body
+ * is not JSON, or the body carries an `error` field. It holds the status and the backend's `code`.
  */
 export declare function fetchWithErrors<T>(url: string, options: RequestInit): Promise<T>;
 /**

package/dist/vue.js

@@ -1,5 +1,5 @@
 import { ref as s, onScopeDispose as u, watch as i } from "vue";
-import { e as r, T as c, k as a } from "./mint-CHlWPuov.js";
+import { e as r, U as c, k as a } from "./mint-CSk_3TfL.js";
 function n() {
   const o = s(r()), t = c((e) => {
     o.value !== e && (o.value = e);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bestinslot/wallet-kit",
   "type": "module",
-  "version": "0.13.8",
+  "version": "0.14.1",
   "private": false,
   "description": "A lightweight JavaScript library for connecting Bitcoin wallets with a unified API.",
   "license": "MIT",