micro-stacks/connect.d.ts

Tiny libraries for building Stacks apps.

import { StacksTransaction, PostConditionMode, PostCondition } from 'micro-stacks/transactions';
import { StacksNetwork, ChainID } from 'micro-stacks/network';
import { ClarityValue as ClarityValue$1, ClarityAbi } from 'micro-stacks/clarity';
import { GaiaHubConfig } from 'micro-stacks/storage';
import { StacksNetworkVersion } from 'micro-stacks/crypto';
import { ChainID as ChainID$1 } from 'micro-stacks/common';
import { Signature } from '@noble/secp256k1';

declare const IS_BROWSER: boolean;
declare enum PersistedDataKeys {
    SessionStorageKey = "stacks-session",
    NetworkStorageKey = "stacks-network"
}

interface BaseRequestPayload {
    appDetails: {
        name: string;
        icon: string;
    };
    authOrigin?: string;
    stxAddress?: string | null;
    privateKey?: string;
    publicKey?: string | null;
    network?: StacksNetwork;
}

declare enum SignatureHash {
    DEFAULT = 0,
    ALL = 1,
    NONE = 2,
    SINGLE = 3,
    ANYONECANPAY = 128
}
interface PsbtData {
    hex: string;
}
declare type PSBTOptionsWithOnHandlers<T> = T & {
    onCancel?: () => void;
    onFinish?: (data: PsbtData) => void;
};
interface PsbtPayload extends BaseRequestPayload {
    allowedSighash?: SignatureHash[];
    hex: string;
    signAtIndex?: number | number[];
}

interface FinishedTxData {
    stacksTransaction: StacksTransaction;
    txRaw: string;
    txId: string;
}
declare const openTransactionPopup: (options: {
    token: string;
    onFinish?: ((payload: FinishedTxData) => void) | undefined;
    onCancel?: ((errorMessage?: string | undefined) => void) | undefined;
}) => Promise<void>;
interface SignatureData {
    signature: string;
    publicKey: string;
}
declare const openSignMessagePopup: (options: {
    token: string;
    onFinish?: ((payload: SignatureData) => void) | undefined;
    onCancel?: ((errorMessage?: string | undefined) => void) | undefined;
}) => Promise<void>;
declare const openSignStructuredDataPopup: (options: {
    token: string;
    onFinish?: ((payload: SignatureData) => void) | undefined;
    onCancel?: ((errorMessage?: string | undefined) => void) | undefined;
}) => Promise<void>;
declare const openPSBTPopup: (options: {
    token: string;
    onFinish?: ((payload: PsbtData) => void) | undefined;
    onCancel?: ((errorMessage?: string | undefined) => void) | undefined;
}) => Promise<void>;

interface StacksProvider {
    transactionRequest(payload: string): Promise<FinishedTxData>;
    profileUpdateRequest(payload: string): Promise<string>;
    authenticationRequest(payload: string): Promise<string>;
    signatureRequest(payload: string): Promise<SignatureData>;
    structuredDataSignatureRequest(payload: string): Promise<SignatureData>;
    psbtRequest(payload: string): Promise<PsbtData>;
    getProductInfo: undefined | (() => {
        version: string;
        name: string;
        meta?: {
            tag?: string;
            commit?: string;
            [key: string]: any;
        };
        [key: string]: any;
    });
}

declare type Unsubscribe = () => void;
interface StorageAdapter<Value> {
    setItem(key: string, value: Value): void;
    getItem(key: string): Value | null | undefined;
    removeItem(key: string): void;
    subscribe?: (key: string, callback: (value: Value) => void) => Unsubscribe;
}
interface AsyncStorageAdapter<Value> {
    setItem(key: string, value: Value): Promise<void>;
    getItem(key: string): Promise<Value | null | undefined>;
    removeItem(key: string): Promise<void>;
    subscribe?: (key: string, callback: (value: Value) => void) => Unsubscribe;
}
declare const defaultStorageAdapter: StorageAdapter<string>;
declare const safeGetPublicKey: (privateKey?: string) => string | null;

declare enum TransactionTypes {
    ContractCall = "contract_call",
    ContractDeploy = "smart_contract",
    STXTransfer = "token_transfer"
}
interface TransactionOptionsBase {
    privateKey?: string;
    appDetails: {
        name: string;
        icon: string;
    };
    postConditionMode?: PostConditionMode;
    postConditions?: (string | PostCondition)[];
    network?: StacksNetwork;
    stxAddress?: string;
    sponsored?: boolean;
    attachment?: string;
}
interface TransactionPayloadBase extends BaseRequestPayload {
    postConditionMode?: PostConditionMode;
    postConditions?: (string | PostCondition)[];
    onFinish?: (data: any) => void;
    onCancel?: (error: any) => void;
}
interface ContractDeployTxOptions extends TransactionOptionsBase {
    contractName: string;
    codeBody: string;
}
interface ContractDeployTxPayload extends TransactionPayloadBase {
    contractName: string;
    codeBody: string;
    txType: TransactionTypes.ContractDeploy;
}
interface ContractCallTxOptions extends TransactionOptionsBase {
    contractAddress: string;
    contractName: string;
    functionName: string;
    functionArgs: string[] | ClarityValue$1[];
    validateWithAbi?: boolean | ClarityAbi;
}
interface ContractCallTxPayload extends TransactionPayloadBase {
    contractAddress: string;
    contractName: string;
    functionName: string;
    functionArgs: (string | ClarityValue$1)[];
    txType: TransactionTypes.ContractCall;
}
interface StxTransferTxOptions extends TransactionOptionsBase {
    recipient: string;
    amount: bigint | string;
    memo?: string;
    onFinish?: (data: any) => void;
}
interface StxTransferTxPayload extends TransactionPayloadBase {
    recipient: string;
    amount: string;
    memo?: string;
    txType: TransactionTypes.STXTransfer;
}

declare function makeContractCallToken({ functionArgs, privateKey, ...options }: ContractCallTxOptions): Promise<string>;

declare function makeContractDeployToken({ privateKey, ...options }: ContractDeployTxOptions): Promise<string>;

declare function makeStxTransferToken({ privateKey, ...options }: StxTransferTxOptions): Promise<string>;

interface AuthResponsePayload {
    private_key?: string;
    username: string | null;
    hubUrl: string;
    associationToken: string;
    blockstackAPIUrl: string | null;
    core_token: string | null;
    email: string | null;
    exp: number;
    iat: number;
    iss: string;
    jti: string;
    version: string;
    profile: Profile;
    profile_url: string;
    public_keys: string[];
}
interface AuthRequestPayload {
    scopes: AuthScope[];
    redirect_uri: string;
    public_keys: string[];
    domain_name: string;
    appDetails: AppDetails;
}
interface Profile {
    '@context'?: 'http://schema.org';
    '@type'?: 'Person';
    account?: {
        '@type': 'Account';
        identifier: string;
        placeholder: boolean;
        proofType: 'http';
        proofUrl: string;
        service: string;
    }[];
    api?: {
        gaiaHubConfig?: Partial<GaiaHubConfig>;
        gaiaHubUrl?: string;
    };
    apps?: Record<string, string>;
    appsMeta?: Record<string, {
        storage: string;
        publicKey: string;
    }>;
    description?: string;
    image?: {
        '@type': 'ImageObject';
        contentUrl: string;
        name: 'avatar';
    }[];
    name?: string;
    stxAddress: {
        testnet: string;
        mainnet: string;
    };
}
interface StacksSessionState {
    addresses: {
        testnet: string;
        mainnet: string;
    };
    appPrivateKey?: string;
    associationToken?: string;
    hubUrl: string;
    public_keys?: string[];
    profile: Profile;
    profile_url: string;
    username: string | null;
    version?: string;
    decentralizedID?: string;
    identityAddress?: string;
}
declare type AuthScope = 'store_write' | 'publish_data';
interface AppDetails {
    name: string;
    icon: string;
}
interface AuthOptions {
    onFinish?: (payload: StacksSessionState) => void;
    onCancel?: (error?: Error) => void;
    onSignOut?: () => void;
    scopes?: AuthScope[];
    appDetails: AppDetails;
}

declare function authenticate(authOptions: AuthOptions, storageAdapter?: StorageAdapter<string>, serialize?: {
    (value: any, replacer?: ((this: any, key: string, value: any) => any) | undefined, space?: string | number | undefined): string;
    (value: any, replacer?: (string | number)[] | null | undefined, space?: string | number | undefined): string;
}): Promise<StacksSessionState | undefined>;
declare function generateAuthRequestPayload(authOptions: AuthOptions, transitPublicKey: string): AuthRequestPayload;
declare function signAuthRequest(payload: unknown, transitPrivateKey: string): Promise<string>;
declare function generateSignedAuthRequest(authOptions: AuthOptions, transitPrivateKey: string): Promise<string>;
declare function handleAuthResponse(authOptions: AuthOptions, transitPrivateKey: string): Promise<string>;
declare global {
    interface Window {
        StacksProvider?: StacksProvider;
    }
}

declare function getDIDType(decentralizedID: string): string;
declare function getAddressFromDID(decentralizedID: string): string | undefined;
declare function decodeAuthResponse(authResponseToken: string, transitPrivateKey: string): Promise<StacksSessionState>;

declare function genericTransactionPopupFactory<OnFinishedPayload, ErrorMessagePayload = string>(method: keyof StacksProvider): (options: {
    token: string;
    onFinish?: ((payload: OnFinishedPayload) => void) | undefined;
    onCancel?: ((errorMessage?: ErrorMessagePayload) => void) | undefined;
}) => Promise<void>;

declare enum WALLET_INSTALL_URLS {
    Chrome = "https://chrome.google.com/webstore/detail/hiro-wallet/ldinpeekobnhjjdofggfgjlcehhmanlj",
    Firefox = "https://addons.mozilla.org/en-US/firefox/addon/hiro-wallet/",
    Mobile = "https://www.xverse.app",
    Browser = "https://www.hiro.so/wallet/install-web"
}
declare type Browsers = 'Chrome' | 'Firefox' | 'Mobile' | 'Browser';
declare function getIsMobileDevice(): boolean | undefined;
declare function getBrowser(): Browsers | null;
declare function getWalletInstallUrl(browser: Browsers | null): WALLET_INSTALL_URLS;

interface SignatureRequestOptions extends BaseRequestPayload {
    message: string;
}
interface StructuredSignatureRequestOptions extends BaseRequestPayload {
    message: string | ClarityValue$1;
    domain: {
        name: string;
        version: string;
        chainId?: ChainID;
    };
}
declare type SignedOptionsWithOnHandlers<T> = T & {
    onFinish?: (payload: SignatureData) => void;
    onCancel?: (errorMessage?: string) => void;
};

declare const generateSignMessagePayload: (options: SignatureRequestOptions) => Promise<string>;
declare const handleSignMessageRequest: (options: SignedOptionsWithOnHandlers<SignatureRequestOptions>) => Promise<void>;

declare enum ClarityType {
    Int = 0,
    UInt = 1,
    Buffer = 2,
    BoolTrue = 3,
    BoolFalse = 4,
    PrincipalStandard = 5,
    PrincipalContract = 6,
    ResponseOk = 7,
    ResponseErr = 8,
    OptionalNone = 9,
    OptionalSome = 10,
    List = 11,
    Tuple = 12,
    StringASCII = 13,
    StringUTF8 = 14
}

declare type BooleanCV = TrueCV | FalseCV;
interface TrueCV {
    type: ClarityType.BoolTrue;
}
interface FalseCV {
    type: ClarityType.BoolFalse;
}

interface BufferCV {
    readonly type: ClarityType.Buffer;
    readonly buffer: Uint8Array;
}

interface IntCV {
    readonly type: ClarityType.Int;
    readonly value: bigint;
}
interface UIntCV {
    readonly type: ClarityType.UInt;
    readonly value: bigint;
}

declare enum StacksMessageType {
    Address = 0,
    Principal = 1,
    LengthPrefixedString = 2,
    MemoString = 3,
    AssetInfo = 4,
    PostCondition = 5,
    PublicKey = 6,
    LengthPrefixedList = 7,
    Payload = 8,
    MessageSignature = 9,
    TransactionAuthField = 10
}
interface Address {
    readonly type: StacksMessageType.Address;
    readonly version: StacksNetworkVersion;
    readonly hash160: string;
}
interface LengthPrefixedString {
    readonly type: StacksMessageType.LengthPrefixedString;
    readonly content: string;
    readonly lengthPrefixBytes: number;
    readonly maxLengthBytes: number;
}

interface StandardPrincipalCV {
    readonly type: ClarityType.PrincipalStandard;
    readonly address: Address;
}
interface ContractPrincipalCV {
    readonly type: ClarityType.PrincipalContract;
    readonly address: Address;
    readonly contractName: LengthPrefixedString;
}

interface ResponseErrorCV<T extends ClarityValue = ClarityValue> {
    readonly type: ClarityType.ResponseErr;
    readonly value: T;
}
interface ResponseOkCV<T extends ClarityValue = ClarityValue> {
    readonly type: ClarityType.ResponseOk;
    readonly value: T;
}

interface NoneCV {
    readonly type: ClarityType.OptionalNone;
}
interface SomeCV<T extends ClarityValue = ClarityValue> {
    readonly type: ClarityType.OptionalSome;
    readonly value: T;
}

interface ListCV<T extends ClarityValue = ClarityValue> {
    type: ClarityType.List;
    list: T[];
}

interface StringAsciiCV {
    readonly type: ClarityType.StringASCII;
    readonly data: string;
}
interface StringUtf8CV {
    readonly type: ClarityType.StringUTF8;
    readonly data: string;
}

declare type ClarityValue = BooleanCV | BufferCV | IntCV | UIntCV | StandardPrincipalCV | ContractPrincipalCV | ResponseErrorCV | ResponseOkCV | NoneCV | SomeCV | ListCV | TupleCV | StringAsciiCV | StringUtf8CV;

declare type TupleData<T extends ClarityValue = ClarityValue> = {
    [key: string]: T;
};
interface TupleCV<T extends TupleData = TupleData> {
    type: ClarityType.Tuple;
    data: T;
}

declare const makeClarityHash: (clarityValue: ClarityValue$1) => Uint8Array;
declare const makeDomainTuple: (name: string, version: string, chainId: ChainID$1) => TupleCV<{
    [key: string]: UIntCV | StringAsciiCV;
}>;
declare const makeStructuredDataHash: (domainHash: Uint8Array, structuredMessageHash: Uint8Array) => Uint8Array;
declare const getStructuredDataHashes: (options: {
    message: StructuredSignatureRequestOptions['message'];
    domain: StructuredSignatureRequestOptions['domain'];
}) => {
    message: Uint8Array;
    domain: Uint8Array;
};
declare const generateSignStructuredDataPayload: (options: StructuredSignatureRequestOptions) => string | Promise<string>;
declare const handleSignStructuredDataRequest: (options: SignedOptionsWithOnHandlers<StructuredSignatureRequestOptions>) => Promise<void>;

declare function hashMessage(message: string | Uint8Array, prefix?: Uint8Array): Uint8Array;
declare function encodeMessage(message: string | Uint8Array, prefix?: Uint8Array): Uint8Array;
declare function decodeMessage(encodedMessage: Uint8Array, prefix?: Uint8Array): Uint8Array;

declare const getPublicKeyFromSignature: ({ hash, signature, recoveryBytes, }: {
    hash: Uint8Array;
    signature: Signature;
    recoveryBytes: number | BigInt;
}) => Uint8Array;
declare const recoverSignature: (options: {
    signature: string;
    mode?: 'vrs' | 'rsv';
}) => {
    signature: Signature;
    recoveryBytes: bigint;
};
declare const verifyMessageSignature: (options: {
    message: string | Uint8Array;
    signature: string;
    publicKey?: string;
    stxAddress?: string;
    mode?: 'vrs' | 'rsv';
}) => boolean;
declare const verifyStructuredMessageSignature: (options: {
    message: StructuredSignatureRequestOptions['message'];
    domain: StructuredSignatureRequestOptions['domain'];
    signature: string;
    publicKey?: string;
    stxAddress?: string;
    mode?: 'vrs' | 'rsv';
}) => boolean;

declare const generatePSBTMessagePayload: (options: Omit<PsbtPayload, 'publicKey'>) => Promise<string>;
declare const handlePSBTRequest: (options: PSBTOptionsWithOnHandlers<Omit<PsbtPayload, 'publicKey'>>) => Promise<void>;

export { AsyncStorageAdapter, AuthOptions, AuthRequestPayload, AuthResponsePayload, AuthScope, Browsers, ContractCallTxOptions, ContractCallTxPayload, ContractDeployTxOptions, ContractDeployTxPayload, FinishedTxData, IS_BROWSER, PSBTOptionsWithOnHandlers, PersistedDataKeys, Profile, PsbtData, PsbtPayload, SignatureData, SignatureRequestOptions, SignedOptionsWithOnHandlers, StacksProvider, StacksSessionState, StorageAdapter, StructuredSignatureRequestOptions, StxTransferTxOptions, StxTransferTxPayload, TransactionOptionsBase, TransactionPayloadBase, TransactionTypes, WALLET_INSTALL_URLS, authenticate, decodeAuthResponse, decodeMessage, defaultStorageAdapter, encodeMessage, generateAuthRequestPayload, generatePSBTMessagePayload, generateSignMessagePayload, generateSignStructuredDataPayload, generateSignedAuthRequest, genericTransactionPopupFactory, getAddressFromDID, getBrowser, getDIDType, getIsMobileDevice, getPublicKeyFromSignature, getStructuredDataHashes, getWalletInstallUrl, handleAuthResponse, handlePSBTRequest, handleSignMessageRequest, handleSignStructuredDataRequest, hashMessage, makeClarityHash, makeContractCallToken, makeContractDeployToken, makeDomainTuple, makeStructuredDataHash, makeStxTransferToken, openPSBTPopup, openSignMessagePopup, openSignStructuredDataPopup, openTransactionPopup, recoverSignature, safeGetPublicKey, signAuthRequest, verifyMessageSignature, verifyStructuredMessageSignature };