Ir al contenido
VerifiedXVerifiedX Docs
verifiedx.io
verifiedx.io

Tipos e interfaces

Esta página enumera los tipos de TypeScript que exporta el VerifiedX Web SDK (vfx-web-sdk 9.0.3). Impórtalos con import type { … } from 'vfx-web-sdk'; los tipos de Bitcoin están en el espacio de nombres btc (btc.BtcKeypair).

// Network enumeration
enum Network {
Mainnet = 'mainnet',
Testnet = 'testnet'
}
// Transaction types the SDK builds (numeric, matching Core's TransactionType)
enum TxType {
RbxTransfer = 0, // VFX transfer (legacy identifier)
Node = 1,
NftMint = 2,
NftTx = 3,
NftBurn = 4,
NftSale = 5,
Adnr = 6,
DstShop = 7,
VoteTopic = 8,
Vote = 9,
Reserve = 10,
TokenTx = 15,
TokenDeploy = 17,
VbtcV2ContractCreate = 25,
VbtcV2Transfer = 26,
VbtcV2WithdrawalRequest = 27,
VbtcV2WithdrawalComplete = 28,
VbtcV2WithdrawalCancel = 29,
VbtcV2CoinPin = 44
}
// Second constructor argument of VfxClient (or pass a boolean dryRun)
interface VfxClientOptions {
dryRun?: boolean; // verify but do not broadcast
baseUrl?: string; // data API origin including /api
timeoutMs?: number; // per request, default 30000, 0 disables
}
interface Keypair {
privateKey: string; // Private key in hexadecimal format
publicKey: string; // Public key in hexadecimal format
address: string; // VFX address (R… on mainnet, x… on testnet)
}

Una autoridad de firma externa (HSM, servicio MPC, billetera de hardware). Se acepta en cualquier lugar donde se acepta un Keypair.

interface Signer {
address: string; // VFX address the signature is verified against
publicKey: string; // uncompressed secp256k1 public key, hex, 04 prefix optional
// Sign the 32-byte SHA-256 digest (hex). Return DER as bytes, hex, or base64.
signDigest(digestHex: string): Promise<Uint8Array | string> | Uint8Array | string;
}
type KeypairOrSigner = Keypair | Signer;

Tipos de cuenta de reserva (cuenta de bóveda)

Sección titulada «Tipos de cuenta de reserva (cuenta de bóveda)»
interface ReserveKeypair extends Keypair {
// address is the xRBX form; privateKey/publicKey are the vault's own key
recoveryPrivateKey: string;
recoveryPublicKey: string;
recoveryAddress: string; // ordinary address that can sweep the vault
restoreCode: string; // base64("<privateKey>//<recoveryPrivateKey>"), CLI/wallet compatible
}
interface ReserveSendOptions {
unlockHours?: number; // delay for a send from a vault; default 24, the network minimum
}
interface FungibleToken {
sc_identifier: string;
name: string;
ticker: string;
description: string | null;
owner_address: string;
can_mint: boolean;
can_burn: boolean;
can_vote: boolean;
created_at: string;
initial_supply: number;
circulating_supply: number;
decimal_places: number;
image_url: string | null;
is_paused: boolean;
banned_addresses: string[];
nsfw: boolean;
}
interface FungibleTokenDetail {
token: FungibleToken;
holders: Record<string, number>; // address → balance
}
interface FungibleTokenBalance {
token: FungibleToken;
balance: number;
}
interface TokenImage {
url: string; // publicly fetchable; becomes the contract's primary asset
name?: string; // defaults to the last path segment of url
extension?: string; // defaults to the extension of name
fileSize?: number;
thumbnailBase64?: string; // small inline image wallets display
}
interface DeployTokenParams {
name: string;
ticker: string; // ≤ 20 chars, stored upper-case
description?: string; // defaults to name
decimalPlaces?: number; // 1–18, default 8
initialSupply?: number; // whole tokens; must be 0 when mintable
mintable?: boolean;
burnable?: boolean;
voting?: boolean;
image?: TokenImage;
}
interface DeployTokenResult {
transactionHash: string;
scIdentifier: string;
}
interface TokenVotingTopic {
sc_identifier: string;
token: FungibleToken;
from_address: string;
topic_id: string;
name: string;
description: string;
vote_requirement: number;
created_at: string;
voting_ends_at: string;
vote_data: unknown;
}
interface VfxAddress {
address: string; // The VFX address
balance: number; // Spendable balance in VFX
balanceTotal: number; // Balance including locked amounts
balanceLocked: number; // Reserve-account sends waiting to settle
adnr: string | null; // Associated .vfx name (if any)
activated: boolean; // Reserve accounts: Register() has been sent
deactivated?: boolean; // Reserve accounts: Recover() has been sent
}

Tal como Spyglass la devuelve desde listTransactionsForAddress:

interface Transaction {
hash: string;
height: number; // Block height
type: number; // Core TransactionType
type_label: string; // e.g. "Tx", "Address"
to_address: string;
from_address: string;
total_amount: number;
total_fee: number;
data: string | null; // JSON string for contract, name and token transactions
date_crafted: string; // ISO timestamp
signature: string;
nft: unknown;
unlock_time: string | null; // Reserve-account sends
callback_details: unknown;
recovery_details: unknown;
}
interface PaginatedResponse<T> {
count: number; // Total number of items
page: number; // Current page number
num_pages: number; // Number of pages
results: T[]; // Items on this page
}
interface VbtcV2Token {
sc_identifier: string;
name: string;
description: string;
owner_address: string;
image_url: string;
deposit_address: string; // Bitcoin (Taproot) deposit address of the vault
frost_group_public_key: string;
required_threshold: number;
proof_block_height: number;
global_balance: number;
total_received: number;
total_sent: number;
tx_count: number;
is_pending_withdrawal: boolean;
is_watched?: boolean; // the chain watches this vault (Core 9.0)
addresses: Record<string, number>; // holder → balance
available_balances?: Record<string, number>; // balance minus open withdrawal requests
nft: unknown;
withdrawal_requests: VbtcWithdrawalRequest[];
created_at: string;
}
type VbtcWithdrawalStatus = 'requested' | 'pending_btc' | 'completed' | 'cancelled' | 'cancellation_requested';
interface VbtcWithdrawalRequest {
id: number;
requestor_address: string;
btc_address: string;
amount: string;
fee_rate: string;
btc_transaction_hash: string;
status: VbtcWithdrawalStatus;
request_transaction_hash: string;
completion_transaction_hash: string | null;
created_at: string;
completed_at: string | null;
}
interface VbtcTransfer {
id: number;
from_address: string;
to_address: string;
amount: string;
transaction_hash: string;
created_at: string;
}
interface CreateVbtcResult { transactionHash: string; scIdentifier: string; depositAddress: string }
interface VbtcTransferResult { transactionHash: string }
interface VbtcMultiTransferResult { transactionHash: string; inputs: Array<{ scIdentifier: string; amount: number }> }
interface VbtcCancelResult { transactionHash: string }
interface VbtcWithdrawalResult {
btcTransactionHash: string; // empty while paid is false
completionTransactionHash: string; // empty while paid is false
withdrawalRequestHash: string;
paid: boolean;
watched: VbtcWatchedWithdrawal | null;
lastError?: string;
}
interface VbtcWatchedWithdrawal {
status: string; // Completed, Awaiting_BTC_Confirmation, Awaiting_BTC_Transaction, Closed or Unknown
paid: boolean;
notMinedYet: boolean;
closed: boolean;
message: string | null;
state: string | null; // Waiting, Pinned, Settled, Released, or another closed state
summary: string | null;
feeRate: number | null; // sat/vB of the newest live Bitcoin transaction
minimumNextFeeRate: number;
canRaiseFee: boolean;
canRelease: boolean;
releasing: boolean;
canCancel: boolean;
pinnedBtcTransactionHash: string | null;
btcTransactionHash: string | null;
completionTransactionHash: string | null;
transactions: VbtcWatchedWithdrawalTransaction[];
}
interface VbtcWatchedWithdrawalTransaction {
txid: string;
kind: 'Payment' | 'Release';
feeRate: number | null;
feeSats: number | null;
superseded: boolean;
dead: boolean;
confirmed: boolean;
}
type VbtcWithdrawalShareOutcome =
'paid' | 'released' | 'cancelled' | 'closed' | 'being_paid' | 'waiting' | 'not_mined' | 'legacy';
interface VbtcWithdrawalShare {
scIdentifier: string;
amount: number;
outcome: VbtcWithdrawalShareOutcome;
watched: VbtcWatchedWithdrawal | null;
pinnedBtcTransactionHash: string | null;
btcTransactionHash: string | null;
}
interface VbtcMultiWithdrawalResult {
withdrawalRequestHash: string;
inputs: Array<{ scIdentifier: string; amount: number }>;
totalAmount: number;
btcAddress: string;
feeRate: number;
fee: number; // VFX fee the request paid
}
interface VbtcWithdrawalSharesResult {
withdrawalRequestHash: string;
shares: VbtcWithdrawalShare[];
settled: boolean;
lastError?: string;
}
type VbtcProgressPhase =
| 'ceremony_started' | 'ceremony_polling' | 'ceremony_complete'
| 'contract_preparing' | 'contract_sent'
| 'withdraw_request_sent'
| 'frost_preparing' | 'frost_polling' | 'frost_complete'
| 'btc_broadcast' | 'completion_recorded'
| 'watched_polling';
interface VbtcProgressEvent {
phase: VbtcProgressPhase;
message: string;
progress?: number;
data?: unknown;
}
// Multi-contract allocation (allocateVbtcInputs)
interface VbtcAllocationInput { scIdentifier: string; amount: number }
type VbtcAllocationFailure = 'insufficientBalance' | 'tooManyInputs';
interface VbtcAllocation { inputs: VbtcAllocationInput[]; available: number; failure?: VbtcAllocationFailure }

VbtcWithdrawalRequest usa VbtcWithdrawalStatus, pero la versión 9.0.3 no lo exporta por nombre; si lo necesitas, escribe la unión tú mismo.

// parseBtcNameAcceptanceCode() result
interface BtcNameAcceptance {
message: string;
signature: string;
timestamp: number; // Unix seconds when the receiver signed
owner: string; // VFX address that will own the name
name: string;
}

Todos se exportan desde el espacio de nombres btc, y cada uno también con un nombre con el prefijo I (IBtcKeypair, …).

interface BtcKeypair {
address: string | undefined; // Default address (bech32)
addresses: BtcAddresses;
wif: string; // Wallet Import Format
privateKey: string | undefined; // Private key in hexadecimal format
publicKey: string; // Public key in hexadecimal format
mnemonic?: string; // 24-word phrase, set by generateMnemonic()
}
interface BtcAddresses {
p2pkh: string | undefined; // Legacy (starts with 1, or m/n on testnet)
p2sh: string | undefined; // Nested SegWit (starts with 3, or 2 on testnet)
bech32: string | undefined; // Native SegWit (starts with bc1q/tb1q)
bech32m: string | undefined; // Taproot (starts with bc1p/tb1p)
}
interface BtcClientOptions {
dryRun?: boolean;
apiBaseUrl?: string; // e.g. 'https://signet.verifiedx.io/api' for the VFX testnet
}
interface AccountInfo {
balance: number; // Confirmed balance (satoshis, or BTC with inSatoshis = false)
totalRecieved: number; // Total received (spelling as in the SDK)
totalSent: number; // Total sent
txCount: number; // Number of transactions
}
interface TransactionInput {
txid: string; // Previous transaction ID
vout: number; // Output index
prevout: TransactionOutput;
scriptsig: string;
scriptsig_asm: string;
witness: string[];
is_coinbase: boolean;
sequence: number;
}
interface TransactionOutput {
scriptpubkey: string;
scriptpubkey_asm: string;
scriptpubkey_type: string;
scriptpubkey_address?: string;
value: number; // Value in satoshis
}
interface TransactionStatus {
confirmed: boolean;
block_height: number;
block_hash: string;
block_time: number;
}
// btc.Transaction, as getTransactions returns it
interface Transaction {
txid: string;
version: number;
locktime: number;
vin: TransactionInput[];
vout: TransactionOutput[];
size: number; // bytes
weight: number;
fee: number; // satoshis
status: TransactionStatus;
}
interface UTXO {
txid: string;
vout: number;
status: TransactionStatus;
value: number;
}
interface FeeRates {
fastestFee: number; // Fastest confirmation fee (sat/vB)
halfHourFee: number; // ~30 minute confirmation fee (sat/vB)
hourFee: number; // ~1 hour confirmation fee (sat/vB)
economyFee: number; // Economy fee rate (sat/vB)
minimumFee: number; // Minimum fee rate (sat/vB)
}
// createTransaction()
interface CreateTxResponse {
success: boolean;
result: string | null; // Signed raw transaction hex
error: string | null;
}
// broadcastTransaction()
interface BroadcastTxResponse {
success: boolean;
result: string | null; // Transaction ID
error: string | null;
}
// checkBroadcast()
type BroadcastCheck =
| { state: 'found'; txid: string; confirmed: boolean }
| { state: 'conflicted'; txid: string; conflictingTxid: string }
| { state: 'absent'; txid: string }
| { state: 'unresolved'; txid: string };

El SDK no tiene alias para direcciones, claves ni montos; son simples string y number. Las convenciones:

  • Las direcciones de VFX empiezan con R en mainnet y con x en testnet; las direcciones de reserva (bóveda) empiezan con xRBX.
  • Las direcciones de Bitcoin usan los formatos de mainnet (1…, 3…, bc1q…, bc1p…) o, en testnet y en el signet de VerifiedX, m…/n…, 2…, tb1q…, tb1p….
  • Montos: VFX en VFX (se permiten decimales); sendBtc y createTransaction reciben BTC; getAddressInfo informa satoshis de forma predeterminada; las tasas de comisión están en sat/vB.

Clases de error que exporta vfx-web-sdk (usa instanceof):

class VfxApiError extends Error { // non-2xx answer from the data API
readonly status: number | undefined;
readonly url: string;
readonly body: string | undefined;
}
class TransactionDispatchError extends Error { // sent, but no answer came back
readonly hash: string;
readonly cause: unknown;
}
class TransactionRefusedError extends Error { // the node refused it (methods that opt in)
readonly hash: string;
readonly reason: string | null;
}
class PreSignCheckError extends Error {} // the transaction to sign was not the one asked for
class VbtcWithdrawalIncompleteError extends Error { // request on chain, completion failed
readonly withdrawalRequestHash: string;
readonly cause: unknown;
}
class VbtcWithdrawalUnrecordedError extends Error { // Bitcoin sent (or maybe sent), completion not recorded
readonly withdrawalRequestHash: string;
readonly btcTransactionHash: string | null;
readonly signedBtcTxHex: string | null;
readonly cause: unknown;
}
class VbtcWithdrawalClosedError extends Error { // watched withdrawal closed unpaid
readonly withdrawalRequestHash: string;
readonly withdrawal: VbtcWatchedWithdrawal;
}
class VbtcNodeUnreachableError extends Error { // Spyglass could not reach the node; ask again
readonly answer: string;
}
class BtcBroadcastUnknownError extends Error { // Bitcoin broadcast outcome unknown (also btc.BtcBroadcastUnknownError)
readonly txid: string;
readonly signedTxHex: string;
readonly cause: unknown;
}
const TOKEN_BASE_ADDRESS = 'Token_Base';
const RESERVE_BASE_ADDRESS = 'Reserve_Base';
const RESERVE_ACTIVATION_COST = 4; // VFX sent with Register()
const RESERVE_MIN_UNLOCK_HOURS = 24;
const VBTC_MULTI_MAX_INPUTS = 25; // contracts per multi transfer
const VBTC_MULTI_WITHDRAWAL_MAX_INPUTS = 10; // vaults per multi withdrawal
const VBTC_MULTI_WITHDRAWAL_FUNCTION = 'VBTCWithdrawalRequestMultiV2()';
const VBTC_WITHDRAWAL_DUST_SATS = 546;
const VBTC_WATCHED_MAX_FEE_RATE = 5000; // sat/vB
const BTC_NAME_ACCEPTANCE_MAX_AGE_SECONDS = 86400;
const BTC_NAME_SIGNED_MESSAGE_HEIGHT_MAINNET = 7_575_250;
const BTC_NAME_SIGNED_MESSAGE_HEIGHT_TESTNET = 7400;
// btc namespace
const BTC_TO_SATOSHI_MULTIPLIER = 100000000;
const SATOSHI_TO_BTC_MULTIPLIER = 0.00000001;
// btc.networks re-exports bitcoinjs-lib's networks (bitcoin, testnet, regtest)

El SDK exporta dos verificaciones de dirección:

  • isOtherNetworksAddress(address, network): devuelve true para una dirección de VFX bien formada de la otra red (el nodo las rechaza como destinatarias).
  • assertRecipientOnNetwork(address, network, label?) y assertBtcAddressOnNetwork(btcAddress, network, label): lanzan un error cuando la dirección pertenece a otra red.

Funciones auxiliares que puedes escribir tú mismo:

import type { Keypair } from 'vfx-web-sdk';
// VFX address prefix check (use isOtherNetworksAddress for checksum and version)
function isVfxAddress(value: unknown, network: 'mainnet' | 'testnet'): value is string {
if (typeof value !== 'string') return false;
// Reserve (vault) accounts start with xRBX on both networks
return network === 'mainnet' ? value.startsWith('R') || value.startsWith('xRBX') : value.startsWith('x');
}
// Check if object is a local keypair the SDK can sign with
function isKeypair(value: any): value is Keypair {
return (
typeof value === 'object' &&
typeof value.privateKey === 'string' &&
typeof value.publicKey === 'string' &&
typeof value.address === 'string'
);
}

Lo que exporta vfx-web-sdk 9.0.3 (src/index.ts):

// Clients
export { VfxClient, MediaApiClient }; // VfxClient is also the default export and vfx.VfxClient
export * as btc from './btc'; // btc.BtcClient, btc types, KeypairService, TransactionService,
// AccountService, publicKeyToAddress, wifToPrivateKey,
// seedToPrivateKey, hashSeed, regtestUtils, networks
// Enums and constants
export { Network, TxType };
export {
TOKEN_BASE_ADDRESS, RESERVE_BASE_ADDRESS, RESERVE_ACTIVATION_COST, RESERVE_MIN_UNLOCK_HOURS,
VBTC_MULTI_MAX_INPUTS, VBTC_MULTI_WITHDRAWAL_FUNCTION, VBTC_MULTI_WITHDRAWAL_MAX_INPUTS,
VBTC_WITHDRAWAL_DUST_SATS, VBTC_WATCHED_MAX_FEE_RATE, BTC_NAME_ACCEPTANCE_MAX_AGE_SECONDS,
BTC_NAME_SIGNED_MESSAGE_HEIGHT_MAINNET, BTC_NAME_SIGNED_MESSAGE_HEIGHT_TESTNET,
};
// Errors
export {
VfxApiError, TransactionDispatchError, TransactionRefusedError, PreSignCheckError,
VbtcWithdrawalIncompleteError, VbtcWithdrawalUnrecordedError, VbtcWithdrawalClosedError,
VbtcNodeUnreachableError, BtcBroadcastUnknownError,
};
// Functions
export {
verifySignature, vfxSignatureFromDer,
allocateVbtcInputs, vbtcMultiTransferData, vbtcMultiWithdrawalData, withdrawalFeeFloorError,
parseWatchedWithdrawal, assertBtcAddressOnNetwork, isOtherNetworksAddress, assertRecipientOnNetwork,
btcNameAcceptanceMessage, buildBtcNameAcceptanceCode, parseBtcNameAcceptanceCode,
btcNameSignedMessageHeight, btcNameSignedMessagesActive,
};
// Types
export type {
VfxClientOptions, ReserveSendOptions, Signer, KeypairOrSigner,
Keypair, VfxAddress, Transaction, PaginatedResponse,
VbtcV2Token, VbtcWithdrawalRequest, VbtcTransfer, CreateVbtcResult, VbtcTransferResult,
VbtcMultiTransferResult, VbtcMultiWithdrawalResult, VbtcWithdrawalShare, VbtcWithdrawalShareOutcome,
VbtcWithdrawalSharesResult, VbtcWithdrawalResult, VbtcWatchedWithdrawal,
VbtcWatchedWithdrawalTransaction, VbtcCancelResult, VbtcProgressPhase, VbtcProgressEvent,
VbtcAllocation, VbtcAllocationInput, VbtcAllocationFailure, BtcNameAcceptance,
FungibleToken, FungibleTokenDetail, FungibleTokenBalance, TokenVotingTopic, TokenImage,
DeployTokenParams, DeployTokenResult, ReserveKeypair,
};

Estas definiciones de tipos ofrecen compatibilidad completa con TypeScript en el VerifiedX Web SDK, con seguridad de tipos y compatibilidad con IntelliSense en tus aplicaciones.