micro-stacks/api.d.ts

Tiny libraries for building Stacks apps.

import { AddressBalanceResponse, AddressStxBalanceResponse, AddressTransactionsListResponse, AddressTransactionWithTransfers, AddressTransactionsWithTransfersListResponse, AddressNonces, AddressAssetsListResponse, AddressStxInboundListResponse, AddressNftListResponse, AccountDataResponse, MempoolTransactionListResponse, BlockListResponse, Block, BurnchainRewardSlotHolderListResponse, BurnchainRewardListResponse, BurnchainRewardsTotal, BnsGetNamespacePriceResponse, BnsGetNamePriceResponse, BnsGetAllNamespacesResponse, BnsGetNameInfoResponse, BnsFetchHistoricalZoneFileResponse, BnsError, BnsFetchFileZoneResponse, BnsNamesOwnByAddressResponse, BnsGetSubdomainAtTx, AbstractTransaction, TransactionEventSmartContractLog, TransactionEventStxLock, TransactionEventStxAsset, TransactionEventFungibleAsset, TransactionEventNonFungibleAsset, ContractInterfaceResponse, MapEntryResponse, ContractSourceResponse, SearchErrorResult, SearchSuccessResult, FungibleTokensMetadataList, NonFungibleTokensMetadataList, NonFungibleTokenMetadata, FungibleTokenMetadata, TransactionType, TransactionResults, MempoolTransaction, Transaction, CoreNodeInfoResponse, ServerStatusResponse, NetworkBlockTimesResponse, NetworkBlockTimeResponse, GetStxSupplyResponse, GetStxSupplyLegacyFormatResponse, CoreNodePoxResponse, RunFaucetResponse, FeeRate, MicroblockListResponse, Microblock, UnanchoredTransactionListResponse } from '@stacks/stacks-blockchain-api-types';
import { ClarityValue } from 'micro-stacks/clarity';
import { StacksNetwork } from 'micro-stacks/network';

interface AccountBase {
    url: string;
    principal: string;
    unanchored?: boolean;
}
interface ListEndpointBase {
    limit?: number;
    offset?: number;
}
declare type AccountListOptions = AccountBase & ListEndpointBase;
declare type PrincipalListWithNetwork = [principal: string, limit: number, networkUrl: string];
declare type PrincipalListHeightWithNetwork = [
    principal: string,
    params: {
        limit: number;
        height?: number;
    },
    networkUrl: string
];
declare type PrincipalWithNetwork = [principal: string, networkUrl: string];

declare type WithHeight$1<T> = T & {
    height?: number;
};
declare function fetchAccountBalances({ url, principal }: AccountBase): Promise<AddressBalanceResponse>;
declare function fetchAccountStxBalance({ url, principal }: AccountBase): Promise<AddressStxBalanceResponse>;
declare function fetchAccountTransactions({ url, principal, limit, offset, height, unanchored, }: WithHeight$1<AccountListOptions>): Promise<AddressTransactionsListResponse>;
declare function fetchAccountTransactionWithTransfers({ url, principal, tx_id, limit, offset, height, unanchored, }: {
    tx_id: string;
} & WithHeight$1<AccountListOptions>): Promise<AddressTransactionWithTransfers>;
declare function fetchAccountTransactionsWithTransfers({ url, principal, limit, offset, height, unanchored, }: WithHeight$1<AccountListOptions>): Promise<AddressTransactionsWithTransfersListResponse>;
declare function fetchAccountNonces({ url, principal }: AccountBase): Promise<AddressNonces>;
declare function fetchAccountAssets({ url, principal, limit, offset, unanchored, }: AccountListOptions): Promise<AddressAssetsListResponse>;
declare function fetchAccountStxInbound({ url, principal }: AccountBase): Promise<AddressStxInboundListResponse>;
declare function fetchAccountNftEvents({ url, principal }: AccountBase): Promise<AddressNftListResponse>;
declare function fetchAccountInfo({ url, principal }: AccountBase): Promise<AccountDataResponse>;
declare function fetchAccountMempoolTransactions({ url, principal, limit, offset, }: AccountListOptions): Promise<MempoolTransactionListResponse>;

interface BaseListParams {
    limit?: number;
    offset?: number;
    url: string;
}
interface EventListParams {
    event_limit?: number;
    event_offset?: number;
    url: string;
}

declare function fetchBlocks({ url, limit, offset }: BaseListParams): Promise<BlockListResponse>;
declare function fetchBlock({ url, hash }: BaseListParams & {
    hash: string;
}): Promise<Block>;
declare function fetchBlockByHeight({ url, height }: BaseListParams & {
    height: number;
}): Promise<Block>;
declare function fetchBlockByBurnBlockHash({ url, burn_block_hash, }: BaseListParams & {
    burn_block_hash: string;
}): Promise<Block>;
declare function fetchBlockByBurnBlockHeight({ url, burn_block_height, }: BaseListParams & {
    burn_block_height: number;
}): Promise<Block>;

declare function fetchBurnchainRewardSlotHolders({ url, limit, offset }: BaseListParams): Promise<BurnchainRewardSlotHolderListResponse>;
declare function fetchBurnchainRewardSlotHoldersByAddress({ url, limit, offset, address, }: BaseListParams & {
    address: string;
}): Promise<BurnchainRewardSlotHolderListResponse>;
declare function fetchBurnchainRewards({ url, limit, offset }: BaseListParams): Promise<BurnchainRewardListResponse>;
declare function fetchBurnchainRewardsByAddress({ url, limit, offset, address, }: BaseListParams & {
    address: string;
}): Promise<BurnchainRewardListResponse>;
declare function fetchTotalBurnchainRewardsByAddress({ url, address, }: BaseListParams & {
    address: string;
}): Promise<BurnchainRewardsTotal>;

declare function fetchNamespacePrice({ url, tld }: BaseListParams & {
    tld: string;
}): Promise<BnsGetNamespacePriceResponse>;
declare function fetchNamePrice({ url, name }: BaseListParams & {
    name: string;
}): Promise<BnsGetNamePriceResponse>;
declare function fetchNamespaces({ url }: BaseListParams): Promise<BnsGetAllNamespacesResponse>;
declare function fetchNamesFromNamespaces({ url, tld }: BaseListParams & {
    tld: string;
}): Promise<string[]>;
declare function fetchNames({ url, page }: BaseListParams & {
    page: number;
}): Promise<string[]>;
declare function fetchName({ url, name }: BaseListParams & {
    name: string;
}): Promise<BnsGetNameInfoResponse>;
declare function fetchNameHistory({ url, name }: BaseListParams & {
    name: string;
}): Promise<BnsFetchHistoricalZoneFileResponse>;
declare function fetchZoneFile({ url, name }: BaseListParams & {
    name: string;
}): Promise<BnsError | BnsFetchFileZoneResponse>;
declare function fetchHistoricalZoneFile({ url, name, zoneFileHash, }: BaseListParams & {
    name: string;
    zoneFileHash: string;
}): Promise<BnsFetchHistoricalZoneFileResponse | BnsError>;
declare function fetchNamesByAddress({ url, blockchain, address, }: BaseListParams & {
    blockchain: string;
    address: string;
}): Promise<BnsError | BnsNamesOwnByAddressResponse>;
declare function fetchAllSubdomains({ url, page }: BaseListParams & {
    page: number;
}): Promise<string[] | BnsError>;
declare function fetchSubdomainAtTransaction({ url, txid, }: BaseListParams & {
    txid: string;
}): Promise<BnsError | BnsGetSubdomainAtTx>;

declare function feesSearch({ url }: BaseListParams): Promise<string>;

declare function fetchContractById({ url, contract_id, unanchored, }: BaseListParams & {
    contract_id: string;
    unanchored: boolean;
}): Promise<AbstractTransaction>;
declare function fetchContractEventsById({ url, contract_id, limit, offset, unanchored, }: BaseListParams & {
    contract_id: string;
    unanchored: boolean;
}): Promise<(TransactionEventSmartContractLog | TransactionEventStxLock | TransactionEventStxAsset | TransactionEventFungibleAsset | TransactionEventNonFungibleAsset)[]>;
declare function fetchContractInterface({ url, contract_address, contract_name, tip, }: BaseListParams & {
    contract_address: string;
    contract_name: string;
    tip: string;
}): Promise<ContractInterfaceResponse>;
declare function fetchContractDataMapEntry({ url, contract_name, contract_address, map_name, proof, tip, lookup_key, }: BaseListParams & {
    contract_name: string;
    contract_address: string;
    map_name: string;
    proof: number;
    tip: string;
    lookup_key: string;
}): Promise<MapEntryResponse>;
declare function fetchContractSource({ url, contract_address, contract_name, proof, tip, }: BaseListParams & {
    contract_address: string;
    contract_name: string;
    proof: number;
    tip: string;
}): Promise<ContractSourceResponse>;

declare function fetchSearch({ url, id }: BaseListParams & {
    id: string;
}): Promise<SearchErrorResult | SearchSuccessResult>;

declare function fetchFtMetadataList({ url }: BaseListParams): Promise<FungibleTokensMetadataList>;
declare function fetchNftMetadataList({ url }: BaseListParams): Promise<NonFungibleTokensMetadataList>;
declare function fetchNftMetadataForContractId({ url, contractId, }: BaseListParams & {
    contractId: string;
}): Promise<NonFungibleTokenMetadata>;
declare function fetchFtMetadataForContractId({ url, contractId, }: BaseListParams & {
    contractId: string;
}): Promise<FungibleTokenMetadata>;

declare function fetchTransactionsList({ limit, offset, type, url, }: BaseListParams & {
    type?: TransactionType | TransactionType[];
}): Promise<TransactionResults>;
declare function fetchMempoolTransactionsList({ limit, offset, sender_address, recipient_address, address, url, }: BaseListParams & {
    sender_address?: string;
    recipient_address?: string;
    address?: string;
}): Promise<MempoolTransactionListResponse>;
declare function fetchDroppedMempoolTransactionsList({ limit, offset, url }: BaseListParams): Promise<MempoolTransactionListResponse>;
declare function fetchTransaction({ txid, event_offset, event_limit, url, }: EventListParams & {
    txid: string;
}): Promise<MempoolTransaction | Transaction>;
declare function fetchRawTransaction({ txid, url }: {
    txid: string;
    url: string;
}): Promise<string>;
declare function fetchTransactionsByBlockHash({ block_hash, url, limit, offset, }: BaseListParams & {
    block_hash: string;
}): Promise<TransactionResults>;
declare function fetchTransactionsByBlockHeight({ block_height, url, limit, offset, }: BaseListParams & {
    block_height: number;
}): Promise<TransactionResults>;

declare type WithHeight<T> = T & {
    height?: number;
};
declare function fetchCoreApiInfo({ url }: BaseListParams): Promise<CoreNodeInfoResponse>;
declare function fetchStatus({ url }: BaseListParams): Promise<ServerStatusResponse>;
declare function fetchNetworkBlockTimes({ url }: BaseListParams): Promise<NetworkBlockTimesResponse>;
declare function fetchNetworkBlockTime({ url, network, }: BaseListParams & {
    network: 'mainnet' | 'testnet';
}): Promise<NetworkBlockTimeResponse>;
declare function fetchStxSupply({ url }: WithHeight<BaseListParams>): Promise<GetStxSupplyResponse>;
declare function fetchStxSupplyPlain({ url }: BaseListParams): Promise<string>;
declare function fetchStxSupplyCirculatingPlain({ url }: BaseListParams): Promise<string>;
declare function fetchStxSupplyLegacyFormat({ url }: WithHeight<BaseListParams>): Promise<GetStxSupplyLegacyFormatResponse>;
declare function fetchPox({ url }: BaseListParams): Promise<CoreNodePoxResponse>;

interface FetchStxTokensParams {
    address: string;
    stacking?: boolean;
}

declare function fetchGetStxTokens({ url, address, stacking, }: BaseListParams & FetchStxTokensParams): Promise<RunFaucetResponse>;
declare function fetchGetBtcTokens({ url, address }: BaseListParams & {
    address: string;
}): Promise<RunFaucetResponse>;

declare function fetchFeeRate({ url, transaction }: BaseListParams & {
    transaction: string;
}): Promise<FeeRate>;

interface FetchFeeRateParams {
    transaction: string;
}

declare function fetchMicroblocks({ url, limit, offset }: BaseListParams): Promise<MicroblockListResponse>;
declare function fetchMicroblock({ url, hash }: BaseListParams & {
    hash: string;
}): Promise<Microblock>;
declare function fetchMicroblocksUnanchoredTransactions({ url }: BaseListParams): Promise<UnanchoredTransactionListResponse>;

declare const isNumber: (value: number | string) => value is number;
declare function parseTxTypeStrings(values: string[]): TransactionType[];
declare const validateTxTypes: (typeQuery: TransactionType[] | TransactionType) => TransactionType[];
declare const generateQueryStringFromArray: <T>(key: string, values?: T[] | undefined) => string;
declare const generateUrl: (baseUrl: string, params: {
    [key: string]: string | number | boolean | string[] | undefined;
}) => string;
declare function v1Endpoint(url: string): string;
declare function v2Endpoint(url: string): string;
declare function extendedEndpoint(url: string): string;
declare function statusEndpoint(url: string): string;
declare function searchEndpoint(url: string): string;
declare function feeRateEndpoint(url: string): string;
declare function burnchainEndpoint(url: string): string;
declare function blockEndpoint(url: string): string;
declare function contractEndpoint(url: string): string;
declare function tokensEndpoint(url: string): string;
declare function contractsEndpoint(url: string): string;
declare function feesEndpoint(url: string): string;
declare function microblockEndpoint(url: string): string;
declare function stxFaucetEndpoint(url: string): string;
declare function btcFaucetEndpoint(url: string): string;
declare function stxSupplyEndpoint(url: string): string;
declare function stxSupplyPlainEndpoint(url: string): string;
declare function stxSupplyCirculatingPlainEndpoint(url: string): string;
declare function stxSupplyLegacyFormatEndpoint(url: string): string;
declare function addressEndpoint(url: string): string;
declare function txEndpoint(url: string): string;
declare function infoEndpoint(url: string): string;
declare function poxEndpoint(url: string): string;
declare function networkBlockTimesEndpoint(url: string): string;
declare function networkBlockTimeEndpoint(url: string): string;
declare function txMempoolEndpoint(url: string): string;
declare function fetchJson<T>(path: string): Promise<T>;
declare function fetchJsonPost<T>(path: string, options?: Omit<RequestInit, 'body'> & {
    body?: unknown;
}): Promise<T>;
declare function fetchText(path: string): Promise<string>;
declare function getNextPageParam(options: {
    limit: number;
    offset: number;
    total: number;
}): number | undefined;

interface ReadOnlyFunctionSuccessResponse {
    okay: true;
    result: string;
}
interface ReadOnlyFunctionErrorResponse {
    okay: false;
    cause: string;
}
declare type ReadOnlyFunctionResponse = ReadOnlyFunctionSuccessResponse | ReadOnlyFunctionErrorResponse;
interface ReadOnlyFunctionOptions {
    contractAddress: string;
    contractName: string;
    functionName: string;
    functionArgs: (string | ClarityValue)[];
    senderAddress?: string;
    network?: StacksNetwork;
    tip?: string;
}

declare function callReadOnlyFunction<T extends ClarityValue>(options: ReadOnlyFunctionOptions): Promise<T>;

declare function fetchReadOnlyFunction<T>(options: ReadOnlyFunctionOptions, strictJsonCompat?: boolean): Promise<T>;

declare function parseReadOnlyResponse<T extends ClarityValue>(response: ReadOnlyFunctionResponse): T;
declare function isMainnetAddress(contractAddress: string): boolean;

export { AccountBase, AccountListOptions, FetchFeeRateParams, FetchStxTokensParams, ListEndpointBase, PrincipalListHeightWithNetwork, PrincipalListWithNetwork, PrincipalWithNetwork, ReadOnlyFunctionErrorResponse, ReadOnlyFunctionOptions, ReadOnlyFunctionResponse, ReadOnlyFunctionSuccessResponse, addressEndpoint, blockEndpoint, btcFaucetEndpoint, burnchainEndpoint, callReadOnlyFunction, contractEndpoint, contractsEndpoint, extendedEndpoint, feeRateEndpoint, feesEndpoint, feesSearch, fetchAccountAssets, fetchAccountBalances, fetchAccountInfo, fetchAccountMempoolTransactions, fetchAccountNftEvents, fetchAccountNonces, fetchAccountStxBalance, fetchAccountStxInbound, fetchAccountTransactionWithTransfers, fetchAccountTransactions, fetchAccountTransactionsWithTransfers, fetchAllSubdomains, fetchBlock, fetchBlockByBurnBlockHash, fetchBlockByBurnBlockHeight, fetchBlockByHeight, fetchBlocks, fetchBurnchainRewardSlotHolders, fetchBurnchainRewardSlotHoldersByAddress, fetchBurnchainRewards, fetchBurnchainRewardsByAddress, fetchContractById, fetchContractDataMapEntry, fetchContractEventsById, fetchContractInterface, fetchContractSource, fetchCoreApiInfo, fetchDroppedMempoolTransactionsList, fetchFeeRate, fetchFtMetadataForContractId, fetchFtMetadataList, fetchGetBtcTokens, fetchGetStxTokens, fetchHistoricalZoneFile, fetchJson, fetchJsonPost, fetchMempoolTransactionsList, fetchMicroblock, fetchMicroblocks, fetchMicroblocksUnanchoredTransactions, fetchName, fetchNameHistory, fetchNamePrice, fetchNames, fetchNamesByAddress, fetchNamesFromNamespaces, fetchNamespacePrice, fetchNamespaces, fetchNetworkBlockTime, fetchNetworkBlockTimes, fetchNftMetadataForContractId, fetchNftMetadataList, fetchPox, fetchRawTransaction, fetchReadOnlyFunction, fetchSearch, fetchStatus, fetchStxSupply, fetchStxSupplyCirculatingPlain, fetchStxSupplyLegacyFormat, fetchStxSupplyPlain, fetchSubdomainAtTransaction, fetchText, fetchTotalBurnchainRewardsByAddress, fetchTransaction, fetchTransactionsByBlockHash, fetchTransactionsByBlockHeight, fetchTransactionsList, fetchZoneFile, generateQueryStringFromArray, generateUrl, getNextPageParam, infoEndpoint, isMainnetAddress, isNumber, microblockEndpoint, networkBlockTimeEndpoint, networkBlockTimesEndpoint, parseReadOnlyResponse, parseTxTypeStrings, poxEndpoint, searchEndpoint, statusEndpoint, stxFaucetEndpoint, stxSupplyCirculatingPlainEndpoint, stxSupplyEndpoint, stxSupplyLegacyFormatEndpoint, stxSupplyPlainEndpoint, tokensEndpoint, txEndpoint, txMempoolEndpoint, v1Endpoint, v2Endpoint, validateTxTypes };