rpc

Documentation

Overview

Package rpc provides a minimal Elements JSON-RPC client.

Index

• type BlockTx
• type BlockVout
• type Client
  • func New(url, user, pass string) *Client
  • func (c *Client) CreateWallet(name string) error
  • func (c *Client) DecodeRawTransaction(txid string) (*DecodedTx, error)
  • func (c *Client) DecodeRawTx(hexTx string) (*DecodedRawTx, error)
  • func (c *Client) EstimateSmartFee(confTarget int) (uint64, error)
  • func (c *Client) GetBlockCount() (int, error)
  • func (c *Client) GetBlockHash(height int) (string, error)
  • func (c *Client) GetBlockTxs(hash string) ([]BlockTx, error)
  • func (c *Client) GetMempoolMinFee() (float64, error)
  • func (c *Client) GetNetworkInfo() (string, error)
  • func (c *Client) GetNewAddress() (string, error)
  • func (c *Client) GetOutputFromTx(txid string, vout uint32) (amount float64, asset string, err error)
  • func (c *Client) GetRawTransaction(txid string) (string, error)
  • func (c *Client) GetTransaction(txid string) (*WalletTx, error)
  • func (c *Client) GetTxOut(txid string, vout uint32) (*UTXO, error)
  • func (c *Client) GetUnconfidentialAddress(addr string) (string, error)
  • func (c *Client) GetWalletUTXO(txid string, vout uint32) (*WalletUTXO, error)
  • func (c *Client) ListUnspentAll() ([]WalletUTXO, error)
  • func (c *Client) ListUnspentByAsset(assetID string) ([]WalletUTXO, error)
  • func (c *Client) LoadOrCreateWallet(name string) (*Client, error)
  • func (c *Client) LoadWallet(name string) error
  • func (c *Client) ReissueAsset(assetID string, amount float64) (*ReissueResult, error)
  • func (c *Client) ScanAddress(addr string) ([]ScanResult, error)
  • func (c *Client) SendMany(outputs map[string]uint64, assetID string) (string, error)
  • func (c *Client) SendRawTransaction(hexTx string) (string, error)
  • func (c *Client) SendToAddress(addr string, satoshis uint64, assetID string) (string, error)
  • func (c *Client) SignRawTransactionWithWallet(hexTx string) (string, bool, error)
  • func (c *Client) TestMempoolAccept(hexTx string) (allowed bool, rejectReason string, err error)
  • func (c *Client) WaitForConfirmations(txid string, minConf int, timeout, interval time.Duration) error
  • func (c *Client) WalletClient(name string) *Client
• type DecodedRawTx
• type DecodedTx
• type PoolCreationRecord
  • func ScanPoolCreations(client *Client, asset0, asset1 string, startBlock int) ([]PoolCreationRecord, error)
• type ReissueResult
• type ScanResult
• type UTXO
• type WalletTx
• type WalletTxDetail
• type WalletUTXO
  • func (u *WalletUTXO) IsExplicit() bool

Types

type BlockTx

type BlockTx struct {
	TxID string      `json:"txid"`
	Vout []BlockVout `json:"vout"`
}

BlockTx is a transaction entry in a verbose block.

type BlockVout

type BlockVout struct {
	N            uint32 `json:"n"`
	ScriptPubKey struct {
		Hex string `json:"hex"`
	} `json:"scriptPubKey"`
}

BlockVout is an output entry in a verbose block transaction.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an Elements node JSON-RPC client.

func New

func New(url, user, pass string) *Client

New creates an RPC client for the given endpoint.

func (*Client) CreateWallet

func (c *Client) CreateWallet(name string) error

CreateWallet creates a new wallet with the given name.

func (*Client) DecodeRawTransaction

func (c *Client) DecodeRawTransaction(txid string) (*DecodedTx, error)

DecodeRawTransaction fetches and decodes a transaction by txid.

func (*Client) DecodeRawTx

func (c *Client) DecodeRawTx(hexTx string) (*DecodedRawTx, error)

DecodeRawTx decodes a raw transaction hex and returns the parsed structure.

func (*Client) EstimateSmartFee

func (c *Client) EstimateSmartFee(confTarget int) (uint64, error)

EstimateSmartFee returns an estimated fee rate in sat/vb for the given confirmation target. Returns 1 sat/vb as a fallback if the node cannot estimate (e.g. insufficient data on regtest).

func (*Client) GetBlockCount

func (c *Client) GetBlockCount() (int, error)

GetBlockCount returns the current best block height.

func (*Client) GetBlockHash

func (c *Client) GetBlockHash(height int) (string, error)

GetBlockHash returns the block hash for the given height.

func (*Client) GetBlockTxs

func (c *Client) GetBlockTxs(hash string) ([]BlockTx, error)

GetBlockTxs returns all transactions in the block with the given hash (verbosity=2).

func (*Client) GetMempoolMinFee

func (c *Client) GetMempoolMinFee() (float64, error)

GetMempoolMinFee returns the minimum fee rate (sat/vb) that will get accepted into the mempool. Returns 0.1 as fallback (Elements minimum).

func (*Client) GetNetworkInfo

func (c *Client) GetNetworkInfo() (string, error)

GetNetworkInfo returns the node network name for connectivity checks.

func (*Client) GetNewAddress

func (c *Client) GetNewAddress() (string, error)

GetNewAddress returns a new bech32 receiving address from the wallet.

func (*Client) GetOutputFromTx

func (c *Client) GetOutputFromTx(txid string, vout uint32) (amount float64, asset string, err error)

GetOutputFromTx fetches a specific output's amount and asset from the raw transaction. Use as a fallback when GetTxOut returns nil (e.g. for confidential/Taproot outputs).

func (*Client) GetRawTransaction

func (c *Client) GetRawTransaction(txid string) (string, error)

GetRawTransaction fetches a raw transaction as hex.

func (*Client) GetTransaction

func (c *Client) GetTransaction(txid string) (*WalletTx, error)

GetTransaction returns wallet transaction details for txid.

func (*Client) GetTxOut

func (c *Client) GetTxOut(txid string, vout uint32) (*UTXO, error)

GetTxOut returns UTXO details for (txid, vout). Returns nil if spent/not found.

func (*Client) GetUnconfidentialAddress

func (c *Client) GetUnconfidentialAddress(addr string) (string, error)

GetUnconfidentialAddress returns the non-confidential (unblinded) form of a Liquid address. Funds sent to a non-confidential address produce explicit (unblinded) UTXOs, which can be spent in transactions with explicit outputs without Pedersen-commitment balance issues. Returns addr unchanged if the node does not report an unconfidential form.

func (*Client) GetWalletUTXO

func (c *Client) GetWalletUTXO(txid string, vout uint32) (*WalletUTXO, error)

GetWalletUTXO calls listunspent and returns the entry matching (txid, vout). Returns nil if not found. The wallet decrypts confidential amounts automatically.

func (*Client) ListUnspentAll

func (c *Client) ListUnspentAll() ([]WalletUTXO, error)

ListUnspentAll returns all wallet UTXOs with 0 or more confirmations.

func (*Client) ListUnspentByAsset

func (c *Client) ListUnspentByAsset(assetID string) ([]WalletUTXO, error)

ListUnspentByAsset returns explicit (unblinded) wallet UTXOs for a specific asset ID. Confidential UTXOs are excluded because they cannot be used as inputs in manually-built transactions with explicit outputs.

func (*Client) LoadOrCreateWallet

func (c *Client) LoadOrCreateWallet(name string) (*Client, error)

LoadOrCreateWallet ensures the named wallet is loaded, creating it if needed. Returns a wallet-scoped Client for subsequent wallet RPC calls.

func (*Client) LoadWallet

func (c *Client) LoadWallet(name string) error

LoadWallet loads a wallet by name. Returns an error if not found.

func (*Client) ReissueAsset

func (c *Client) ReissueAsset(assetID string, amount float64) (*ReissueResult, error)

ReissueAsset uses the wallet to reissue (mint) more of an existing asset. The wallet must hold the reissuance token for the given asset. amount is in BTC units (e.g., 0.00003162 for 3162 sats).

func (*Client) ScanAddress

func (c *Client) ScanAddress(addr string) ([]ScanResult, error)

ScanAddress uses scantxoutset to find UTXOs at a given address.

func (*Client) SendMany

func (c *Client) SendMany(outputs map[string]uint64, assetID string) (string, error)

SendMany sends satoshis to multiple addresses in a single wallet transaction. All recipients use the same assetID; pass "" for the network's native asset. Returns the txid of the broadcast transaction.

func (*Client) SendRawTransaction

func (c *Client) SendRawTransaction(hexTx string) (string, error)

SendRawTransaction broadcasts a raw hex transaction and returns the txid.

func (*Client) SendToAddress

func (c *Client) SendToAddress(addr string, satoshis uint64, assetID string) (string, error)

SendToAddress sends satoshis of assetID to addr and returns the txid. Pass assetID="" to send the network native asset (L-BTC).

func (*Client) SignRawTransactionWithWallet

func (c *Client) SignRawTransactionWithWallet(hexTx string) (string, bool, error)

SignRawTransactionWithWallet signs a raw transaction hex using the node's wallet. Returns the signed hex and whether all inputs are complete.

func (*Client) TestMempoolAccept

func (c *Client) TestMempoolAccept(hexTx string) (allowed bool, rejectReason string, err error)

TestMempoolAccept tests whether a raw tx would be accepted into the mempool. Returns the accept/reject result per transaction.

func (*Client) WaitForConfirmations

func (c *Client) WaitForConfirmations(txid string, minConf int, timeout, interval time.Duration) error

WaitForConfirmations polls gettransaction every interval until txid has at least minConf confirmations, or until timeout is reached.

func (*Client) WalletClient

func (c *Client) WalletClient(name string) *Client

WalletClient returns a Client that routes calls to /wallet/<name>. Wallet-specific RPCs (listunspent, sendtoaddress, etc.) must use this client when more than one wallet is loaded.

type DecodedRawTx

type DecodedRawTx struct {
	TxID string `json:"txid"`
	Vin  []struct {
		TxID     string `json:"txid"`
		Vout     uint32 `json:"vout"`
		Issuance *struct {
			AssetBlindingNonce string  `json:"assetBlindingNonce"`
			AssetEntropy       string  `json:"assetEntropy"`
			IsReissuance       bool    `json:"isReissuance"`
			Asset              string  `json:"asset"`
			AssetAmount        float64 `json:"assetamount"`
			Token              string  `json:"token"`
			TokenAmount        float64 `json:"tokenamount"`
		} `json:"issuance"`
	} `json:"vin"`
	Vout []struct {
		N            uint32  `json:"n"`
		Value        float64 `json:"value"`
		Asset        string  `json:"asset"`
		ScriptPubKey struct {
			Hex string `json:"hex"`
		} `json:"scriptPubKey"`
	} `json:"vout"`
}

DecodedRawTx holds the decoded output of decoderawtransaction.

type DecodedTx

type DecodedTx struct {
	TxID string `json:"txid"`
	Vin  []struct {
		TxID string `json:"txid"`
		Vout uint32 `json:"vout"`
	} `json:"vin"`
	Vout []struct {
		N            uint32  `json:"n"`
		Value        float64 `json:"value"`
		Asset        string  `json:"asset"`
		ScriptPubKey struct {
			Hex     string `json:"hex"`
			Address string `json:"address"`
		} `json:"scriptPubKey"`
	} `json:"vout"`
}

DecodedTx holds decoded raw transaction data.

type PoolCreationRecord

type PoolCreationRecord struct {
	TxID   string // creation transaction ID
	Asset0 string // display hex (reversed from internal)
	Asset1 string // display hex
	FeeNum uint16
	FeeDen uint16
	Height int
}

PoolCreationRecord holds parameters decoded from an ANCHR OP_RETURN output.

func ScanPoolCreations

func ScanPoolCreations(client *Client, asset0, asset1 string, startBlock int) ([]PoolCreationRecord, error)

ScanPoolCreations scans blocks from startBlock to the chain tip for ANCHR OP_RETURN outputs. If asset0 or asset1 is non-empty, only records matching both assets are returned (case-insensitive). Pass "" to return all pools.

Note: this calls getblockhash + getblock for every block in the range. Use a narrow startBlock range on long chains to avoid slow scans.

type ReissueResult

type ReissueResult struct {
	TxID string `json:"txid"`
	Vin  int    `json:"vin"`
}

ReissueResult holds the result of a reissueasset RPC call.

type ScanResult

type ScanResult struct {
	TxID   string  `json:"txid"`
	Vout   uint32  `json:"vout"`
	Asset  string  `json:"asset"`
	Amount float64 `json:"amount"`
	Height int     `json:"height"`
}

ScanResult holds a UTXO from scantxoutset.

type UTXO

type UTXO struct {
	TxID          string  `json:"txid"`
	Vout          uint32  `json:"vout"`
	Asset         string  `json:"asset"`
	Amount        float64 `json:"amount"`
	ScriptPubKey  string  `json:"scriptPubKey"`
	Confirmations int     `json:"confirmations"`
}

UTXO holds unspent output details.

type WalletTx

type WalletTx struct {
	TxID          string           `json:"txid"`
	Confirmations int              `json:"confirmations"`
	Details       []WalletTxDetail `json:"details"`
}

WalletTx is the result of gettransaction.

type WalletTxDetail

type WalletTxDetail struct {
	Address  string  `json:"address"`
	Category string  `json:"category"`
	Amount   float64 `json:"amount"`
	Asset    string  `json:"asset"`
	Vout     uint32  `json:"vout"`
}

WalletTxDetail is one output entry in a gettransaction result.

type WalletUTXO

type WalletUTXO struct {
	TxID          string  `json:"txid"`
	Vout          uint32  `json:"vout"`
	Asset         string  `json:"asset"`
	Amount        float64 `json:"amount"`
	AmountBlinder string  `json:"amountblinder"`
}

WalletUTXO holds an unspent output from the wallet's listunspent.

func (*WalletUTXO) IsExplicit

func (u *WalletUTXO) IsExplicit() bool

IsExplicit returns true if this UTXO has unblinded (explicit) value and asset. Confidential UTXOs cannot be used as inputs in manually-built transactions because Elements cannot verify balance with mixed confidential/explicit values.