blockstack
Version:
The Blockstack Javascript library for authentication, identity, and storage.
411 lines (410 loc) • 17.4 kB
TypeScript
import { networks, Network } from 'bitcoinjs-lib';
import * as BN from 'bn.js';
export interface UTXO {
value?: number;
confirmations?: number;
tx_hash: string;
tx_output_n: number;
}
export interface PriceInfo {
units: string;
amount: BN;
}
export interface AccountTokens {
tokens: string[];
}
export interface TransactionInfo {
block_height: number;
[key: string]: any;
}
/**
* @private
* @ignore
*/
export declare class BitcoinNetwork {
broadcastTransaction(transaction: string): Promise<any>;
getBlockHeight(): Promise<number>;
getTransactionInfo(txid: string): Promise<TransactionInfo>;
getNetworkedUTXOs(address: string): Promise<UTXO[]>;
}
/**
* Use the methods in class to build third-party wallets or in DApps that register names.
*/
export declare class BlockstackNetwork {
blockstackAPIUrl: string;
broadcastServiceUrl: string;
/**
* @ignore
*/
layer1: Network;
DUST_MINIMUM: number;
includeUtxoMap: {
[address: string]: UTXO[];
};
excludeUtxoSet: UTXO[];
btc: BitcoinNetwork;
MAGIC_BYTES: string;
constructor(apiUrl: string, broadcastServiceUrl: string, bitcoinAPI: BitcoinNetwork, network?: networks.Network);
/**
* @ignore
*/
coerceAddress(address: string): string;
/**
* This is intended for use in third-party wallets or in DApps that register names.
*/
getDefaultBurnAddress(): string;
/**
* Get the price of a name via the legacy /v1/prices API endpoint. This is
* intended for use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName the name to query
* @return a promise to an Object with { units: String, amount: BigInteger }
* @private
*/
getNamePriceV1(fullyQualifiedName: string): Promise<PriceInfo>;
/**
* Get the price of a namespace via the legacy /v1/prices API endpoint. This is intended for
* use in third-party wallets or in DApps that register names.
* @param namespaceID the namespace to query
* @return a promise to an Object with { units: String, amount: BigInteger }
* @private
*/
getNamespacePriceV1(namespaceID: string): Promise<PriceInfo>;
/**
* Get the price of a name via the /v2/prices API endpoint. This is intended
* for use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName the name to query
* @return a promise to an Object with { units: String, amount: BigInteger }
* @private
*/
getNamePriceV2(fullyQualifiedName: string): Promise<PriceInfo>;
/**
* Get the price of a namespace via the /v2/prices API endpoint.
* This is intended for use in third-party wallets or in DApps that register names.
* @param namespaceID the namespace to query
* @return a promise to an Object with { units: String, amount: BigInteger }
* @private
*/
getNamespacePriceV2(namespaceID: string): Promise<PriceInfo>;
/**
* Get the price of a name. This is intended for
* use in third-party wallets or in DApps that register names.
* This is intended for use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName the name to query
* @return a promise to an Object with { units: String, amount: BigInteger }, where
* .units encodes the cryptocurrency units to pay (e.g. BTC, STACKS), and
* .amount encodes the number of units, in the smallest denominiated amount
* (e.g. if .units is BTC, .amount will be satoshis; if .units is STACKS,
* .amount will be microStacks)
*/
getNamePrice(fullyQualifiedName: string): Promise<PriceInfo>;
/**
* Get the price of a namespace. This is intended for use in third-party
* wallets or in DApps that register names.
* @param namespaceID the namespace to query
* @return a promise to an Object with { units: String, amount: BigInteger }, where
* .units encodes the cryptocurrency units to pay (e.g. BTC, STACKS), and
* .amount encodes the number of units, in the smallest denominiated amount
* (e.g. if .units is BTC, .amount will be satoshis; if .units is STACKS,
* .amount will be microStacks)
*/
getNamespacePrice(namespaceID: string): Promise<PriceInfo>;
/**
* How many blocks can pass between a name expiring and the name being able to be
* re-registered by a different owner. This is intended for
* use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName unused
* @return a promise to the number of blocks
*/
getGracePeriod(_fullyQualifiedName?: string): Promise<number>;
/**
* Get the names -- both on-chain and off-chain -- owned by an address. This is intended for
* use in third-party wallets or in DApps that register names.
* @param address the blockchain address (the hash of the owner public key)
* @return a promise that resolves to a list of names (Strings)
*/
getNamesOwned(address: string): Promise<string[]>;
/**
* Get the blockchain address to which a name's registration fee must be sent
* (the address will depend on the namespace in which it is registered.)
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param namespace the namespace ID
* @return a promise that resolves to an address (String)
*/
getNamespaceBurnAddress(namespace: string): Promise<string>;
/**
* Get WHOIS-like information for a name, including the address that owns it,
* the block at which it expires, and the zone file anchored to it (if available).
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName the name to query. Can be on-chain of off-chain.
* @return a promise that resolves to the WHOIS-like information
*/
getNameInfo(fullyQualifiedName: string): Promise<any>;
/**
* Get the pricing parameters and creation history of a namespace. This is intended for
* use in third-party wallets or in DApps that register names.
* @param namespaceID the namespace to query
* @return a promise that resolves to the namespace information.
*/
getNamespaceInfo(namespaceID: string): Promise<any>;
/**
* Get a zone file, given its hash. Throws an exception if the zone file
* obtained does not match the hash.
*
* This is intended for use in third-party wallets or in DApps that register names.
*
* @param zonefileHash the ripemd160(sha256) hash of the zone file
* @return a promise that resolves to the zone file's text
*/
getZonefile(zonefileHash: string): Promise<string>;
/**
* Get the status of an account for a particular token holding. This includes its total number of
* expenditures and credits, lockup times, last `txid`, and so on.
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param address the account
* @param tokenType the token type to query
* @return a promise that resolves to an object representing the state of the account
* for this token
*/
getAccountStatus(address: string, tokenType: string): Promise<any>;
/**
* Get a page of an account's transaction history. This is intended for use in
* third-party wallets or in DApps that register names.
* @param address the account's address
* @param page the page number. Page 0 is the most recent transactions
* @return a promise that resolves to an Array of Objects, where each Object encodes
* states of the account at various block heights (e.g. prior balances, txids, etc)
*/
getAccountHistoryPage(address: string, page: number): Promise<any[]>;
/**
* Get the state(s) of an account at a particular block height. This includes the state of the
* account beginning with this block's transactions, as well as all of the states the account
* passed through when this block was processed (if any).
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param address the account's address
* @param blockHeight the block to query
* @return a promise that resolves to an Array of Objects, where each Object encodes
* states of the account at this block.
*/
getAccountAt(address: string, blockHeight: number): Promise<any[]>;
/**
* Get the set of token types that this account owns. This is intended for use
* in third-party wallets or in DApps that register names.
* @param address the account's address
* @return a promise that resolves to an Array of Strings, where each item encodes the
* type of token this account holds (excluding the underlying blockchain's tokens)
*/
getAccountTokens(address: string): Promise<AccountTokens>;
/**
* Get the number of tokens owned by an account. If the account does not exist or has no
* tokens of this type, then 0 will be returned.
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param address the account's address
* @param tokenType the type of token to query.
* @return a promise that resolves to a BigInteger that encodes the number of tokens
* held by this account.
*/
getAccountBalance(address: string, tokenType: string): Promise<BN>;
/**
* Performs a POST request to the given URL. This is intended for
* use in third-party wallets or in DApps that register names.
* @param endpoint the name of
* @param body [description]
* @return Returns a `Promise` that resolves to the object requested.
* In the event of an error, it rejects with:
* * a `RemoteServiceError` if there is a problem
* with the transaction broadcast service
* * `MissingParameterError` if you call the function without a required
* parameter
*
* @private
*/
broadcastServiceFetchHelper(endpoint: string, body: any): Promise<any | Error>;
/**
* Broadcasts a signed bitcoin transaction to the network optionally waiting to broadcast the
* transaction until a second transaction has a certain number of confirmations.
*
* This is intended for use in third-party wallets or in DApps that register names.
*
* @param transaction the hex-encoded transaction to broadcast
* @param transactionToWatch the hex transaction id of the transaction to watch for
* the specified number of confirmations before broadcasting the `transaction`
* @param confirmations the number of confirmations `transactionToWatch` must have
* before broadcasting `transaction`.
* @return Returns a Promise that resolves to an object with a
* `transaction_hash` key containing the transaction hash of the broadcasted transaction.
*
* In the event of an error, it rejects with:
* * a `RemoteServiceError` if there is a problem
* with the transaction broadcast service
* * `MissingParameterError` if you call the function without a required
* parameter
* @private
*/
broadcastTransaction(transaction: string, transactionToWatch?: string, confirmations?: number): Promise<any>;
/**
* Broadcasts a zone file to the Atlas network via the transaction broadcast service.
* This is intended for use in third-party wallets or in DApps that register names.
*
* @param zoneFile the zone file to be broadcast to the Atlas network
* @param transactionToWatch the hex transaction id of the transaction
* to watch for confirmation before broadcasting the zone file to the Atlas network
* @return Returns a Promise that resolves to an object with a
* `transaction_hash` key containing the transaction hash of the broadcasted transaction.
*
* In the event of an error, it rejects with:
* * a `RemoteServiceError` if there is a problem
* with the transaction broadcast service
* * `MissingParameterError` if you call the function without a required
* parameter
* @private
*/
broadcastZoneFile(zoneFile?: string, transactionToWatch?: string): Promise<any>;
/**
* Sends the preorder and registration transactions and zone file
* for a Blockstack name registration along with the to the transaction
* broadcast service.
*
* The transaction broadcast:
*
* * immediately broadcasts the preorder transaction
* * broadcasts the register transactions after the preorder transaction
* has an appropriate number of confirmations
* * broadcasts the zone file to the Atlas network after the register transaction
* has an appropriate number of confirmations
*
* This is intended for use in third-party wallets or in DApps that register names.
*
* @param preorderTransaction the hex-encoded, signed preorder transaction generated
* using the `makePreorder` function
* @param registerTransaction the hex-encoded, signed register transaction generated
* using the `makeRegister` function
* @param zoneFile the zone file to be broadcast to the Atlas network
* @return Returns a Promise that resolves to an object with a
* `transaction_hash` key containing the transaction hash of the broadcasted transaction.
*
* In the event of an error, it rejects with:
* * a `RemoteServiceError` if there is a problem
* with the transaction broadcast service
* * `MissingParameterError` if you call the function without a required
* parameter
* @private
*/
broadcastNameRegistration(preorderTransaction: string, registerTransaction: string, zoneFile: string): Promise<any>;
/**
* @ignore
*/
getFeeRate(): Promise<number>;
/**
* @ignore
*/
countDustOutputs(): void;
/**
* @ignore
*/
getUTXOs(address: string): Promise<UTXO[]>;
/**
* This will modify the network's utxo set to include UTXOs
* from the given transaction and exclude UTXOs *spent* in
* that transaction.
*
* This is intended for use in third-party wallets or in DApps that register names.
* @param txHex - the hex-encoded transaction to use
* @return no return value, this modifies the UTXO config state
* @private
* @ignore
*/
modifyUTXOSetFrom(txHex: string): void;
/**
* @ignore
*/
resetUTXOs(address: string): void;
/**
* @ignore
*/
getConsensusHash(): Promise<any>;
getTransactionInfo(txHash: string): Promise<TransactionInfo>;
/**
* @ignore
*/
getBlockHeight(): Promise<number>;
getNetworkedUTXOs(address: string): Promise<UTXO[]>;
}
/**
* @ignore
*/
export declare class LocalRegtest extends BlockstackNetwork {
constructor(apiUrl: string, broadcastServiceUrl: string, bitcoinAPI: BitcoinNetwork);
getFeeRate(): Promise<number>;
}
/**
* @ignore
*/
export declare class BitcoindAPI extends BitcoinNetwork {
bitcoindUrl: string;
bitcoindCredentials: {
username: string;
password: string;
};
importedBefore: any;
constructor(bitcoindUrl: string, bitcoindCredentials: {
username: string;
password: string;
});
broadcastTransaction(transaction: string): Promise<any>;
getBlockHeight(): Promise<any>;
getTransactionInfo(txHash: string): Promise<TransactionInfo>;
getNetworkedUTXOs(address: string): Promise<UTXO[]>;
}
/**
* @ignore
*/
export declare class InsightClient extends BitcoinNetwork {
apiUrl: string;
constructor(insightUrl?: string);
broadcastTransaction(transaction: string): Promise<any>;
getBlockHeight(): Promise<any>;
getTransactionInfo(txHash: string): Promise<TransactionInfo>;
getNetworkedUTXOs(address: string): Promise<UTXO[]>;
}
/**
* @ignore
*/
export declare class BlockchainInfoApi extends BitcoinNetwork {
utxoProviderUrl: string;
constructor(blockchainInfoUrl?: string);
getBlockHeight(): Promise<any>;
getNetworkedUTXOs(address: string): Promise<UTXO[]>;
getTransactionInfo(txHash: string): Promise<TransactionInfo>;
broadcastTransaction(transaction: string): Promise<string>;
}
/**
* Instance of [[BlockstackNetwork]] set to the default endpoints.
*/
export declare const MAINNET_DEFAULT: BlockstackNetwork;
/**
* Get WHOIS-like information for a name, including the address that owns it,
* the block at which it expires, and the zone file anchored to it (if available).
* This is intended for use in third-party wallets or in DApps that register names.
* @param fullyQualifiedName the name to query. Can be on-chain of off-chain.
* @return a promise that resolves to the WHOIS-like information
*/
export declare function getNameInfo(fullyQualifiedName: string): Promise<any>;
/**
* @ignore
*/
export declare const network: {
BlockstackNetwork: typeof BlockstackNetwork;
LocalRegtest: typeof LocalRegtest;
BlockchainInfoApi: typeof BlockchainInfoApi;
BitcoindAPI: typeof BitcoindAPI;
InsightClient: typeof InsightClient;
defaults: {
LOCAL_REGTEST: LocalRegtest;
MAINNET_DEFAULT: BlockstackNetwork;
};
};