@sats-connect/core 0.0.2-7d8cb11 → 0.0.3

package/README.md

@@ -2,7 +2,6 @@
 
 Sats connect is a simple javascript library that connects apps to Bitcoin wallets like Xverse to retrieve user wallet addresses and sign transactions (PSBTs).
 
-
 # Building the `@sats-connect/core` package
 
 To build the `@sats-connect/core` package, run

package/dist/index.d.mts

@@ -0,0 +1,609 @@
+interface GetCapabilitiesPayload extends RequestPayload {
+}
+type GetCapabilitiesResponse = Capability[];
+type GetCapabilitiesOptions = RequestOptions<GetCapabilitiesPayload, GetCapabilitiesResponse>;
+
+declare const getCapabilities: (options: GetCapabilitiesOptions) => Promise<void>;
+
+interface CreateInscriptionPayload extends RequestPayload {
+    contentType: string;
+    content: string;
+    payloadType: 'PLAIN_TEXT' | 'BASE_64';
+    appFee?: number;
+    appFeeAddress?: string;
+    suggestedMinerFeeRate?: number;
+    token?: string;
+}
+interface CreateRepeatInscriptionsPayload extends CreateInscriptionPayload {
+    repeat: number;
+}
+type CreateInscriptionResponse = {
+    txId: string;
+};
+type CreateRepeatInscriptionsResponse = {
+    txId: string;
+};
+type CreateInscriptionOptions = RequestOptions<CreateInscriptionPayload, CreateInscriptionResponse>;
+type CreateRepeatInscriptionsOptions = RequestOptions<CreateRepeatInscriptionsPayload, CreateRepeatInscriptionsResponse>;
+
+declare const createInscription: (options: CreateInscriptionOptions) => Promise<void>;
+
+declare const createRepeatInscriptions: (options: CreateRepeatInscriptionsOptions) => Promise<void>;
+
+interface SignMessagePayload extends RequestPayload {
+    address: string;
+    message: string;
+}
+type SignMessageResponse = string;
+type SignMessageOptions = RequestOptions<SignMessagePayload, SignMessageResponse>;
+
+declare const signMessage: (options: SignMessageOptions) => Promise<void>;
+
+interface Recipient$2 {
+    address: string;
+    amountSats: bigint;
+}
+type SerializedRecipient = Omit<Recipient$2, 'amountSats'> & {
+    amountSats: string;
+};
+interface SendBtcTransactionPayload extends RequestPayload {
+    recipients: Recipient$2[];
+    senderAddress: string;
+    message?: string;
+}
+type SerializedSendBtcTransactionPayload = Omit<SendBtcTransactionPayload, 'recipients'> & {
+    recipients: SerializedRecipient[];
+};
+type SendBtcTransactionResponse = string;
+type SendBtcTransactionOptions = RequestOptions<SendBtcTransactionPayload, SendBtcTransactionResponse>;
+interface InputToSign {
+    address: string;
+    signingIndexes: number[];
+    sigHash?: number;
+}
+type PsbtPayload = {
+    psbtBase64: string;
+    inputsToSign: InputToSign[];
+    broadcast?: boolean;
+};
+type SignMultiplePsbtPayload = {
+    psbtBase64: string;
+    inputsToSign: InputToSign[];
+};
+interface SignTransactionPayload extends RequestPayload, PsbtPayload {
+    message: string;
+}
+interface SignTransactionResponse {
+    psbtBase64: string;
+    txId?: string;
+}
+type SignTransactionOptions = RequestOptions<SignTransactionPayload, SignTransactionResponse>;
+interface SignMultipleTransactionsPayload extends RequestPayload {
+    message: string;
+    psbts: SignMultiplePsbtPayload[];
+}
+type SignMultipleTransactionsResponse = SignTransactionResponse[];
+type SignMultipleTransactionOptions = RequestOptions<SignMultipleTransactionsPayload, SignMultipleTransactionsResponse>;
+
+declare const sendBtcTransaction: (options: SendBtcTransactionOptions) => Promise<void>;
+
+declare const signTransaction: (options: SignTransactionOptions) => Promise<void>;
+
+declare const signMultipleTransactions: (options: SignMultipleTransactionOptions) => Promise<void>;
+
+interface BaseBitcoinProvider {
+    request: <Method extends keyof Requests>(method: Method, options: Params<Method>, providerId?: string) => Promise<RpcResponse<Method>>;
+    connect: (request: string) => Promise<GetAddressResponse>;
+    signMessage: (request: string) => Promise<SignMessageResponse>;
+    signTransaction: (request: string) => Promise<SignTransactionResponse>;
+    sendBtcTransaction: (request: string) => Promise<SendBtcTransactionResponse>;
+    createInscription: (request: string) => Promise<CreateInscriptionResponse>;
+    createRepeatInscriptions: (request: string) => Promise<CreateRepeatInscriptionsResponse>;
+    signMultipleTransactions: (request: string) => Promise<SignMultipleTransactionsResponse>;
+}
+type Capability = keyof BaseBitcoinProvider;
+interface BitcoinProvider extends BaseBitcoinProvider {
+    getCapabilities?: (request: string) => Promise<GetCapabilitiesResponse>;
+}
+interface Provider {
+    id: string;
+    name: string;
+    icon: string;
+    webUrl?: string;
+    chromeWebStoreUrl?: string;
+    mozillaAddOnsUrl?: string;
+    googlePlayStoreUrl?: string;
+    iOSAppStoreUrl?: string;
+    methods?: (StxRequestMethod | BtcRequestMethod)[];
+}
+interface SupportedWallet extends Provider {
+    isInstalled: boolean;
+}
+declare global {
+    interface XverseProviders {
+        BitcoinProvider?: BitcoinProvider;
+    }
+    interface Window {
+        BitcoinProvider?: BitcoinProvider;
+        XverseProviders?: XverseProviders;
+        btc_providers?: Provider[];
+    }
+}
+
+declare function getProviderOrThrow(getProvider?: () => Promise<BitcoinProvider | undefined>): Promise<BitcoinProvider>;
+declare function getProviders(): Provider[];
+declare function getProviderById(providerId: string): any;
+declare function isProviderInstalled(providerId: string): boolean;
+declare function setDefaultProvider(providerId: string): void;
+declare function getDefaultProvider(): string | null;
+declare function removeDefaultProvider(): void;
+declare function getSupportedWallets(): SupportedWallet[];
+
+declare enum BitcoinNetworkType {
+    Mainnet = "Mainnet",
+    Testnet = "Testnet"
+}
+interface BitcoinNetwork {
+    type: BitcoinNetworkType;
+    address?: string;
+}
+interface RequestPayload {
+    network: BitcoinNetwork;
+}
+interface RequestOptions<Payload extends RequestPayload, Response> {
+    onFinish: (response: Response) => void;
+    onCancel: () => void;
+    payload: Payload;
+    getProvider?: () => Promise<BitcoinProvider | undefined>;
+}
+type RpcId = string | null;
+interface RpcBase {
+    jsonrpc: '2.0';
+    id: RpcId;
+}
+interface RpcRequest<T extends string, U> extends RpcBase {
+    method: T;
+    params: U;
+}
+interface MethodParamsAndResult<TParams, TResult> {
+    params: TParams;
+    result: TResult;
+}
+/**
+ * @enum {number} RpcErrorCode
+ * @description JSON-RPC error codes
+ * @see https://www.jsonrpc.org/specification#error_object
+ */
+declare enum RpcErrorCode {
+    /**
+     * Parse error Invalid JSON
+     **/
+    PARSE_ERROR = -32700,
+    /**
+     * The JSON sent is not a valid Request object.
+     **/
+    INVALID_REQUEST = -32600,
+    /**
+     * The method does not exist/is not available.
+     **/
+    METHOD_NOT_FOUND = -32601,
+    /**
+     * Invalid method parameter(s).
+     */
+    INVALID_PARAMS = -32602,
+    /**
+     * Internal JSON-RPC error.
+     * This is a generic error, used when the server encounters an error in performing the request.
+     **/
+    INTERNAL_ERROR = -32603,
+    /**
+     * user rejected/canceled the request
+     */
+    USER_REJECTION = -32000,
+    /**
+     * method is not supported for the address provided
+     */
+    METHOD_NOT_SUPPORTED = -32001
+}
+interface RpcError {
+    code: number | RpcErrorCode;
+    message: string;
+    data?: any;
+}
+interface RpcErrorResponse<TError extends RpcError = RpcError> extends RpcBase {
+    error: TError;
+}
+interface RpcSuccessResponse<Method extends keyof Requests> extends RpcBase {
+    result: Return<Method>;
+}
+type RpcResponse<Method extends keyof Requests> = RpcSuccessResponse<Method> | RpcErrorResponse;
+type RpcResult<Method extends keyof Requests> = {
+    result: RpcSuccessResponse<Method>['result'];
+    status: 'success';
+} | {
+    error: RpcErrorResponse['error'];
+    status: 'error';
+};
+
+declare enum AddressPurpose {
+    Ordinals = "ordinals",
+    Payment = "payment",
+    Stacks = "stacks"
+}
+interface GetAddressPayload extends RequestPayload {
+    purposes: AddressPurpose[];
+    message: string;
+}
+declare enum AddressType {
+    p2pkh = "p2pkh",
+    p2sh = "p2sh",
+    p2wpkh = "p2wpkh",
+    p2wsh = "p2wsh",
+    p2tr = "p2tr",
+    stacks = "stacks"
+}
+interface Address$1 {
+    address: string;
+    publicKey: string;
+    purpose?: AddressPurpose;
+    addressType?: AddressType;
+}
+interface GetAddressResponse {
+    addresses: Address$1[];
+}
+type GetAddressOptions = RequestOptions<GetAddressPayload, GetAddressResponse>;
+
+declare const getAddress: (options: GetAddressOptions) => Promise<void>;
+
+/**
+ * Represents the types and interfaces related to BTC methods.
+ */
+
+type GetInfoResult = {
+    version: number | string;
+    methods?: Array<string>;
+    supports?: Array<string>;
+};
+type GetInfo = MethodParamsAndResult<null, GetInfoResult>;
+type GetAddressesParams$1 = {
+    /**
+     * The purposes for which to generate addresses.
+     * possible values are "payment", "ordinals", ...
+     */
+    purposes: Array<AddressPurpose>;
+    /**
+     * a message to be displayed to the user in the request prompt.
+     */
+    message?: string;
+};
+/**
+ * The addresses generated for the given purposes.
+ */
+type GetAddressesResult$1 = {
+    addresses: Array<Address$1>;
+};
+type GetAddresses = MethodParamsAndResult<GetAddressesParams$1, GetAddressesResult$1>;
+type SignMessageParams = {
+    /**
+     * The address used for signing.
+     **/
+    address: string;
+    /**
+     * The message to sign.
+     **/
+    message: string;
+};
+type SignMessageResult = {
+    /**
+     * The signature of the message.
+     */
+    signature: string;
+    /**
+     * hash of the message.
+     */
+    messageHash: string;
+    /**
+     * The address used for signing.
+     */
+    address: string;
+};
+type SignMessage = MethodParamsAndResult<SignMessageParams, SignMessageResult>;
+type Recipient$1 = {
+    /**
+     * The recipient's address.
+     **/
+    address: string;
+    /**
+     * The amount to send to the recipient in satoshis.
+     */
+    amount: number;
+};
+type SendTransferParams = {
+    /**
+     * Array of recipients to send to.
+     * The amount to send to each recipient is in satoshis.
+     */
+    recipients: Array<Recipient$1>;
+};
+type SendTransferResult = {
+    /**
+     * The transaction id as a hex-encoded string.
+     */
+    txid: string;
+};
+type SendTransfer = MethodParamsAndResult<SendTransferParams, SendTransferResult>;
+type SignPsbtParams = {
+    /**
+     * The base64 encoded PSBT to sign.
+     */
+    psbt: string;
+    /**
+     * The inputs to sign.
+     * The key is the address and the value is an array of indexes of the inputs to sign.
+     */
+    signInputs: Record<string, number[]>;
+    /**
+     * the sigHash type to use for signing.
+     * will default to the sighash type of the input if not provided.
+     **/
+    allowedSignHash?: number;
+    /**
+     * Whether to broadcast the transaction after signing.
+     **/
+    broadcast?: boolean;
+};
+type SignPsbtResult = {
+    /**
+     * The base64 encoded PSBT after signing.
+     */
+    psbt: string;
+    /**
+     * The transaction id as a hex-encoded string.
+     * This is only returned if the transaction was broadcast.
+     **/
+    txid?: string;
+};
+type SignPsbt = MethodParamsAndResult<SignPsbtParams, SignPsbtResult>;
+type GetAccountsParams = {
+    /**
+     * The purposes for which to generate addresses.
+     * possible values are "payment", "ordinals", ...
+     */
+    purposes: Array<AddressPurpose>;
+    /**
+     * a message to be displayed to the user in the request prompt.
+     */
+    /**
+     * a message to be displayed to the user in the request prompt.
+     */
+    message?: string;
+};
+type GetAccountResult = Address$1[];
+type GetAccounts = MethodParamsAndResult<GetAccountsParams, GetAccountResult>;
+
+interface Pubkey {
+    /**
+     * When sending a transfer STX request to a wallet, users can generally
+     * choose from which accout they want to send the STX tokens from. In
+     * cases where applications want the transfer to be made from a specific
+     * account, they can provide the `pubkey` of the address they'd like the
+     * transfer to be made from. It is up to wallet providers to handle this
+     * field as they see fit.
+     */
+    pubkey: string;
+}
+interface Address {
+    /**
+     * A Crockford base-32 encoded Stacks address.
+     */
+    address: string;
+}
+interface PostConditions {
+    /**
+     * A hex-encoded string representing the post conditions.
+     *
+     * A post condition may be converted to it's hex representation using the `serializePostCondition` helper from the `@stacks/transactions` package,
+     *
+     * ```js
+     * import { serializePostCondition } from '@stacks/transactions';
+     *
+     * const postCondition = somePostCondition;
+     * const hexPostCondition = serializePostCondition(postCondition).toString('hex');
+     * ```
+     */
+    postConditions: Array<string>;
+}
+interface PostConditionMode {
+    /**
+     * The mode of the post conditions.
+     */
+    postConditionMode: number;
+}
+interface ParameterFormatVersion {
+    /**
+     * Version of parameter format.
+     */
+    version: string;
+}
+interface Recipient {
+    /**
+     * The recipeint's Crockford base-32 encoded Stacks address.
+     */
+    recipient: string;
+}
+interface Amount {
+    /**
+     * Amount of STX tokens to transfer in microstacks as a string. Anything
+     * parseable by `BigInt` is acceptable.
+     *
+     * Example,
+     *
+     * ```js
+     * const amount1 = 1234;
+     * const amount2 = 1234n;
+     * const amount3 = '1234';
+     * ```
+     */
+    amount: number | string;
+}
+interface Memo {
+    /**
+     * A string representing the memo.
+     */
+    memo: string;
+}
+interface TxId {
+    /**
+     * The ID of the transaction.
+     */
+    txid: string;
+}
+interface Transaction {
+    /**
+     * A Stacks transaction as a hex-encoded string.
+     */
+    transaction: string;
+}
+interface Message {
+    /**
+     * Message payload to be signed.
+     */
+    message: string;
+}
+interface Signature {
+    /**
+     * Signature of the message.
+     */
+    signature: string;
+}
+interface PublicKey {
+    /**
+     * Public key as hex-encoded string.
+     */
+    publicKey: string;
+}
+interface Domain {
+    /**
+     * The domain to be signed.
+     */
+    domain: string;
+}
+interface CallContractParams {
+    /**
+     * The contract's Crockford base-32 encoded Stacks address and name.
+     *
+     * E.g. `"SPKE...GD5C.my-contract"`
+     */
+    contract: string;
+    /**
+     * The name of the function to call.
+     *
+     * Note: spec changes ongoing,
+     * https://github.com/stacksgov/sips/pull/166#pullrequestreview-1914236999
+     */
+    functionName: string;
+    /**
+     * The function's arguments. The arguments are expected to be hex-encoded
+     * strings of Clarity values.
+     *
+     * To convert Clarity values to their hex representation, the `cvToString`
+     * helper from the `@stacks/transactions` package may be helpful.
+     *
+     * ```js
+     * import { cvToString } from '@stacks/transactions';
+     *
+     * const functionArgs = [someClarityValue1, someClarityValue2];
+     * const hexArgs = functionArgs.map(cvToString);
+     * ```
+     */
+    arguments?: Array<string>;
+}
+type CallContractResult = TxId & Transaction;
+type StxCallContract = MethodParamsAndResult<CallContractParams, CallContractResult>;
+type TransferStxParams = Amount & Recipient & Partial<Memo> & Partial<ParameterFormatVersion> & Partial<PostConditionMode> & Partial<PostConditions> & Partial<Pubkey>;
+type TransferStxResult = TxId & Transaction;
+type StxTransferStx = MethodParamsAndResult<TransferStxParams, TransferStxResult>;
+type SignStxMessageParams = Message & Partial<Pubkey> & Partial<ParameterFormatVersion>;
+type SignStxMessageResult = Signature & PublicKey;
+type StxSignStxMessage = MethodParamsAndResult<SignStxMessageParams, SignStxMessageResult>;
+type SignStructuredMessageParams = Domain & Message & Partial<ParameterFormatVersion> & Partial<Pubkey>;
+type SignStructuredMessageResult = Signature & PublicKey;
+type StxSignStructuredMessage = MethodParamsAndResult<SignStructuredMessageParams, SignStructuredMessageResult>;
+interface DeployContractParams {
+    /**
+     * Name of the contract.
+     */
+    name: string;
+    /**
+     * The code of the Clarity contract.
+     */
+    clarityCode: string;
+    /**
+     * The version of the Clarity contract.
+     */
+    clarityVersion?: string;
+}
+type DeployContractResult = TxId & Transaction;
+type StxDeployContract = MethodParamsAndResult<DeployContractParams, DeployContractResult>;
+type GetAccountsResult = {
+    addresses: Array<Address & PublicKey & {
+        gaiaHubUrl: string;
+        gaiaAppKey: string;
+    }>;
+};
+type StxGetAccounts = MethodParamsAndResult<{}, GetAccountsResult>;
+type GetAddressesParams = undefined | null;
+type GetAddressesResult = {
+    addresses: Array<Address & PublicKey>;
+};
+type StxGetAddresses = MethodParamsAndResult<GetAddressesParams, GetAddressesResult>;
+type SignTransactionParams = Transaction & Partial<Pubkey>;
+type SignTransactionResult = Transaction;
+type StxSignTransaction = MethodParamsAndResult<SignTransactionParams, SignTransactionResult>;
+
+interface StxRequests {
+    stx_callContract: StxCallContract;
+    stx_deployContract: StxDeployContract;
+    stx_getAccounts: StxGetAccounts;
+    stx_getAddresses: StxGetAddresses;
+    stx_signMessage: StxSignStxMessage;
+    stx_signStructuredMessage: StxSignStructuredMessage;
+    stx_signTransaction: StxSignTransaction;
+    stx_transferStx: StxTransferStx;
+}
+type StxRequestMethod = keyof StxRequests;
+interface BtcRequests {
+    getInfo: GetInfo;
+    getAddresses: GetAddresses;
+    getAccounts: GetAccounts;
+    signMessage: SignMessage;
+    sendTransfer: SendTransfer;
+    signPsbt: SignPsbt;
+}
+type BtcRequestMethod = keyof BtcRequests;
+type Requests = BtcRequests & StxRequests;
+type Return<Method> = Method extends keyof Requests ? Requests[Method]['result'] : never;
+type Params<Method> = Method extends keyof Requests ? Requests[Method]['params'] : never;
+
+declare const request: <Method extends keyof BtcRequests | keyof StxRequests>(method: Method, params: Params<Method>, providerId?: string) => Promise<RpcResult<Method>>;
+
+declare abstract class SatsConnectAdapter {
+    abstract readonly id: string;
+    abstract request<Method extends keyof Requests>(method: Method, params: Params<Method>): Promise<RpcResult<Method> | undefined>;
+}
+
+declare class BaseAdapter extends SatsConnectAdapter {
+    id: string;
+    constructor(providerId: string);
+    request: <Method extends keyof BtcRequests | keyof StxRequests>(method: Method, params: Params<Method>) => Promise<RpcResult<Method> | undefined>;
+}
+
+declare const DefaultAdaptersInfo: Record<string, Provider>;
+declare const defaultAdapters: Record<string, new () => SatsConnectAdapter>;
+
+interface Config {
+    providers: SupportedWallet[];
+}
+declare function createDefaultConfig(providers: SupportedWallet[]): Config;
+
+export { type Address$1 as Address, AddressPurpose, AddressType, BaseAdapter, type BitcoinNetwork, BitcoinNetworkType, type BitcoinProvider, type BtcRequestMethod, type BtcRequests, type CallContractParams, type CallContractResult, type Capability, type Config, type CreateInscriptionOptions, type CreateInscriptionPayload, type CreateInscriptionResponse, type CreateRepeatInscriptionsOptions, type CreateRepeatInscriptionsPayload, type CreateRepeatInscriptionsResponse, DefaultAdaptersInfo, type DeployContractParams, type DeployContractResult, type GetAccountResult, type GetAccounts, type GetAccountsParams, type GetAccountsResult, type GetAddressOptions, type GetAddressPayload, type GetAddressResponse, type GetAddresses, type GetAddressesParams, type GetAddressesResult, type GetCapabilitiesOptions, type GetCapabilitiesPayload, type GetCapabilitiesResponse, type GetInfo, type InputToSign, type MethodParamsAndResult, type Params, type Provider, type PsbtPayload, type Recipient$2 as Recipient, type RequestOptions, type RequestPayload, type Requests, type Return, type RpcBase, type RpcError, RpcErrorCode, type RpcErrorResponse, type RpcId, type RpcRequest, type RpcResponse, type RpcResult, type RpcSuccessResponse, SatsConnectAdapter, type SendBtcTransactionOptions, type SendBtcTransactionPayload, type SendBtcTransactionResponse, type SendTransfer, type SendTransferParams, type SerializedRecipient, type SerializedSendBtcTransactionPayload, type SignMessage, type SignMessageOptions, type SignMessageParams, type SignMessagePayload, type SignMessageResponse, type SignMultiplePsbtPayload, type SignMultipleTransactionOptions, type SignMultipleTransactionsPayload, type SignMultipleTransactionsResponse, type SignPsbt, type SignPsbtParams, type SignPsbtResult, type SignStructuredMessageResult, type SignStxMessageParams, type SignStxMessageResult, type SignTransactionOptions, type SignTransactionParams, type SignTransactionPayload, type SignTransactionResponse, type SignTransactionResult, type StxCallContract, type StxDeployContract, type StxGetAccounts, type StxGetAddresses, type StxRequestMethod, type StxRequests, type StxSignStructuredMessage, type StxSignStxMessage, type StxSignTransaction, type StxTransferStx, type SupportedWallet, type TransferStxParams, type TransferStxResult, createDefaultConfig, createInscription, createRepeatInscriptions, defaultAdapters, getAddress, getCapabilities, getDefaultProvider, getProviderById, getProviderOrThrow, getProviders, getSupportedWallets, isProviderInstalled, removeDefaultProvider, request, sendBtcTransaction, setDefaultProvider, signMessage, signMultipleTransactions, signTransaction };