Struct rgb_lib::wallet::Wallet

pub struct Wallet { /* private fields */ }

An RGB wallet.

This should not be manually constructed but should be obtained from the Wallet::new method.

Implementations

impl Wallet

pub fn backup(&self, backup_path: &str, password: &str) -> Result<(), Error>

Create a backup of the wallet as a file with the provided name and encrypted with the provided password.

Scrypt is used for hashing and xchacha20poly1305 is used for encryption. A random salt for hashing and a random nonce for encrypting are randomly generated and included in the final backup file, along with the backup version.

pub fn backup_info(&self) -> Result<bool, Error>

Return whether the wallet requires to perform a backup.

impl Wallet

pub fn new(wallet_data: WalletData) -> Result<Self, Error>

Create a new RGB wallet based on the provided WalletData.

pub fn blind_receive( &self, asset_id: Option<String>, amount: Option<u64>, duration_seconds: Option<u32>, transport_endpoints: Vec<String>, min_confirmations: u8 ) -> Result<ReceiveData, Error>

Blind an UTXO to receive RGB assets and return the resulting ReceiveData.

An optional asset ID can be specified, which will be embedded in the invoice, resulting in the refusal of the transfer is the asset doesn’t match.

An optional amount can be specified, which will be embedded in the invoice. It will not be checked when accepting the transfer.

An optional duration (in seconds) can be specified, which will set the expiration of the invoice. A duration of 0 seconds means no expiration.

Each endpoint in the provided transport_endpoints list will be used as RGB data exchange medium. The list needs to contain at least 1 endpoint and a maximum of 3. Strings specifying invalid endpoints and duplicate ones will cause an error to be raised. A valid endpoint string encodes an RgbTransport. At the moment the only supported variant is JsonRpc (e.g. rpc://127.0.0.1 or rpcs://example.com).

The min_confirmations number determines the minimum number of confirmations needed for the transaction anchoring the transfer for it to be considered final and move (while refreshing) to the TransferStatus::Settled status.

pub fn witness_receive( &self, asset_id: Option<String>, amount: Option<u64>, duration_seconds: Option<u32>, transport_endpoints: Vec<String>, min_confirmations: u8 ) -> Result<ReceiveData, Error>

Create an address to receive RGB assets and return the resulting ReceiveData.

An optional asset ID can be specified, which will be embedded in the invoice, resulting in the refusal of the transfer is the asset doesn’t match.

An optional amount can be specified, which will be embedded in the invoice. It will not be checked when accepting the transfer.

An optional duration (in seconds) can be specified, which will set the expiration of the invoice. A duration of 0 seconds means no expiration.

Each endpoint in the provided transport_endpoints list will be used as RGB data exchange medium. The list needs to contain at least 1 endpoint and a maximum of 3. Strings specifying invalid endpoints and duplicate ones will cause an error to be raised. A valid endpoint string encodes an RgbTransport. At the moment the only supported variant is JsonRpc (e.g. rpc://127.0.0.1 or rpcs://example.com).

The min_confirmations number determines the minimum number of confirmations needed for the transaction anchoring the transfer for it to be considered final and move (while refreshing) to the TransferStatus::Settled status.

pub fn sign_psbt( &self, unsigned_psbt: String, sign_options: Option<SignOptions> ) -> Result<String, Error>

Sign a PSBT, optionally providing BDK sign options.

pub fn create_utxos( &self, online: Online, up_to: bool, num: Option<u8>, size: Option<u32>, fee_rate: f32 ) -> Result<u8, Error>

Create new UTXOs.

This calls create_utxos_begin, signs the resulting PSBT and finally calls create_utxos_end.

A wallet with private keys is required.

pub fn create_utxos_begin( &self, online: Online, up_to: bool, num: Option<u8>, size: Option<u32>, fee_rate: f32 ) -> Result<String, Error>

Prepare the PSBT to create new UTXOs to hold RGB allocations with the provided fee_rate (in sat/vB).

If up_to is false, just create the required UTXOs, if it is true, create as many UTXOs as needed to reach the requested number or return an error if none need to be created.

Providing the optional num parameter requests that many UTXOs, if it’s not specified the default number (5) is used.

Providing the optional size parameter requests that UTXOs be created of that size (in sats), if it’s not specified the default one (1000) is used.

If not enough bitcoin funds are available to create the requested (or default) number of UTXOs, the number is decremented by one until it is possible to complete the operation. If the number reaches zero, an error is returned.

Signing of the returned PSBT needs to be carried out separately. The signed PSBT then needs to be fed to the create_utxos_end function.

This doesn’t require the wallet to have private keys.

Returns a PSBT ready to be signed.

pub fn create_utxos_end( &self, online: Online, signed_psbt: String ) -> Result<u8, Error>

Broadcast the provided PSBT to create new UTXOs.

The provided PSBT, prepared with the create_utxos_begin function, needs to have already been signed.

This doesn’t require the wallet to have private keys.

Returns the number of created UTXOs.

pub fn delete_transfers( &self, recipient_id: Option<String>, txid: Option<String>, no_asset_only: bool ) -> Result<bool, Error>

Delete eligible transfers from the database and return true if any transfer has been deleted.

An optional recipient_id can be provided to operate on a single transfer. An optional txid can be provided to operate on a batch transfer.

If both a recipient_id and a txid are provided, they need to belong to the same batch transfer or an error is returned.

If at least one of recipient_id or txid are provided and no_asset_only is true, transfers with an associated asset ID will not be deleted and instead return an error.

If neither recipient_id nor txid are provided, all failed transfers will be deleted, unless no_asset_only is true, in which case transfers with an associated asset ID will be skipped.

Eligible transfers are the ones in status TransferStatus::Failed.

pub fn drain_to( &self, online: Online, address: String, destroy_assets: bool, fee_rate: f32 ) -> Result<String, Error>

Send bitcoin funds to the provided address.

This calls drain_to_begin, signs the resulting PSBT and finally calls drain_to_end.

A wallet with private keys is required.

pub fn drain_to_begin( &self, online: Online, address: String, destroy_assets: bool, fee_rate: f32 ) -> Result<String, Error>

Prepare the PSBT to send bitcoin funds not in use for RGB allocations, or all funds if destroy_assets is set to true, to the provided Bitcoin address with the provided fee_rate (in sat/vB).

Warning: setting destroy_assets to true is dangerous, only do this if you know what you're doing!

Signing of the returned PSBT needs to be carried out separately. The signed PSBT then needs to be fed to the drain_to_end function.

This doesn’t require the wallet to have private keys.

Returns a PSBT ready to be signed.

pub fn drain_to_end( &self, online: Online, signed_psbt: String ) -> Result<String, Error>

Broadcast the provided PSBT to send bitcoin funds.

The provided PSBT, prepared with the drain_to_begin function, needs to have already been signed.

This doesn’t require the wallet to have private keys.

Returns the TXID of the transaction that’s been broadcast.

pub fn fail_transfers( &self, online: Online, recipient_id: Option<String>, txid: Option<String>, no_asset_only: bool ) -> Result<bool, Error>

Set the status for eligible transfers to TransferStatus::Failed and return true if any transfer has changed.

An optional recipient_id can be provided to operate on a single transfer. An optional txid can be provided to operate on a batch transfer.

If both a recipient_id and a txid are provided, they need to belong to the same batch transfer or an error is returned.

If at least one of recipient_id or txid are provided and no_asset_only is true, transfers with an associated asset ID will not be failed and instead return an error.

If neither recipient_id nor txid are provided, only expired transfers will be failed, and if no_asset_only is true transfers with an associated asset ID will be skipped.

Transfers are eligible if they remain in status TransferStatus::WaitingCounterparty after a refresh has been performed.

pub fn get_address(&self) -> Result<String, Error>

Return a new Bitcoin address from the vanilla wallet.

pub fn get_asset_balance(&self, asset_id: String) -> Result<Balance, Error>

Return the Balance for the RGB asset with the provided ID.

pub fn get_btc_balance(&self, online: Online) -> Result<BtcBalance, Error>

Return the BtcBalance of the internal Bitcoin wallets.

pub fn get_asset_metadata(&self, asset_id: String) -> Result<Metadata, Error>

Return the Metadata for the RGB asset with the provided ID.

pub fn get_wallet_data(&self) -> WalletData

Return the data that defines the wallet.

pub fn get_wallet_dir(&self) -> PathBuf

Return the wallet directory.

pub fn go_online( &mut self, skip_consistency_check: bool, electrum_url: String ) -> Result<Online, Error>

Return the existing or freshly generated set of wallet Online data.

Setting skip_consistency_check to false runs a check on UTXOs (BDK vs rgb-lib DB) and assets (RGB vs rgb-lib DB) to try and detect possible inconsistencies in the wallet. Setting skip_consistency_check to true bypasses the check and allows operating an inconsistent wallet.

Warning: setting `skip_consistency_check` to true is dangerous, only do this if you know what you're doing!

pub fn issue_asset_nia( &self, online: Online, ticker: String, name: String, precision: u8, amounts: Vec<u64> ) -> Result<AssetNIA, Error>

Issue a new RGB NIA asset with the provided ticker, name, precision and amounts, then return it.

At least 1 amount needs to be provided and the sum of all amounts cannot exceed the maximum u64 value.

If amounts contains more than 1 element, each one will be issued as a separate allocation for the same asset (on a separate UTXO that needs to be already available).

pub fn issue_asset_cfa( &self, online: Online, name: String, description: Option<String>, precision: u8, amounts: Vec<u64>, file_path: Option<String> ) -> Result<AssetCFA, Error>

Issue a new RGB CFA asset with the provided name, optional description, precision and amounts, then return it.

An optional file_path containing the path to a media file can be provided. Its hash (as attachment ID) and mime type will be encoded in the contract.

At least 1 amount needs to be provided and the sum of all amounts cannot exceed the maximum u64 value.

If amounts contains more than 1 element, each one will be issued as a separate allocation for the same asset (on a separate UTXO that needs to be already available).

pub fn list_assets( &self, filter_asset_schemas: Vec<AssetSchema> ) -> Result<Assets, Error>

List the known RGB assets.

Providing an empty filter_asset_schemas will list assets for all schemas, otherwise only assets for the provided schemas will be listed.

The returned Assets will have fields set to None for schemas that have not been requested.

pub fn list_transactions( &self, online: Option<Online> ) -> Result<Vec<Transaction>, Error>

List the Bitcoin Transactions known to the wallet.

pub fn list_transfers( &self, asset_id: Option<String> ) -> Result<Vec<Transfer>, Error>

List the RGB Transfers known to the wallet.

When an asset_id is not provided, return transfers that are not connected to a specific asset.

pub fn list_unspents( &self, online: Option<Online>, settled_only: bool ) -> Result<Vec<Unspent>, Error>

List the Unspents known to the wallet.

If settled is true only show settled RGB allocations, if false also show pending RGB allocations.

pub fn list_unspents_vanilla( &self, online: Online, min_confirmations: u8 ) -> Result<Vec<LocalUtxo>, Error>

List the Bitcoin unspents of the vanilla wallet, using BDK’s objects, filtered by min_confirmations.

This method is meant for special usage, for most cases the method [`list_unspents`] is sufficient

pub fn save_new_asset( &self, runtime: &mut RgbRuntime, asset_schema: &AssetSchema, contract_id: ContractId ) -> Result<ContractIface, Error>

Extract the metadata of a new RGB asset and save the asset into the DB.

This method is meant for special usage and is normally not needed, use it only if you know what you're doing

pub fn refresh( &self, online: Online, asset_id: Option<String>, filter: Vec<RefreshFilter> ) -> Result<bool, Error>

Update pending RGB transfers, based on their current status, and return true if any transfer has changed.

An optional asset_id can be provided to refresh transfers related to a specific asset.

Each item in the RefreshFilter vector defines transfers to be refreshed. Transfers not matching any provided filter are skipped. If the vector is empty, all transfers are refreshed.

pub fn send( &self, online: Online, recipient_map: HashMap<String, Vec<Recipient>>, donation: bool, fee_rate: f32, min_confirmations: u8 ) -> Result<String, Error>

Send RGB assets.

This calls send_begin, signs the resulting PSBT and finally calls send_end.

A wallet with private keys is required.

pub fn send_begin( &self, online: Online, recipient_map: HashMap<String, Vec<Recipient>>, donation: bool, fee_rate: f32, min_confirmations: u8 ) -> Result<String, Error>

Prepare the PSBT to send RGB assets according to the given recipient map, with the provided fee_rate (in sat/vB).

The recipient_map maps asset IDs to a vector of Recipients. When multiple recipients are provided, a batch transfer will be performed, meaning a single Bitcoin transaction will be used to move all assets to the respective recipients. Each asset being sent will result in the creation of a single consignment, which will then be posted to the RGB proxy server for each of its recipients.

If donation is true, the resulting transaction will be broadcast (by send_end) as soon as it’s ready, without the need for recipients to ACK the transfer. If donation is false, all recipients will need to ACK the transfer before the transaction is broadcast.

The min_confirmations number determines the minimum number of confirmations needed for the transaction anchoring the transfer for it to be considered final and move (while refreshing) to the TransferStatus::Settled status.

Signing of the returned PSBT needs to be carried out separately. The signed PSBT then needs to be fed to the send_end function for broadcasting.

This doesn’t require the wallet to have private keys.

Returns a PSBT ready to be signed.

pub fn send_end( &self, online: Online, signed_psbt: String ) -> Result<String, Error>

Complete the send operation by saving the PSBT to disk, POSTing consignments to the RGB proxy server, saving the transfer to DB and broadcasting the provided PSBT, if appropriate.

The provided PSBT, prepared with the send_begin function, needs to have already been signed.

This doesn’t require the wallet to have private keys.

Returns the TXID of the signed PSBT that’s been saved and optionally broadcast.

pub fn send_btc( &self, online: Online, address: String, amount: u64, fee_rate: f32 ) -> Result<String, Error>

Send bitcoins using the vanilla wallet.

This calls send_btc_begin, signs the resulting PSBT and finally calls send_btc_end.

A wallet with private keys and Online data are required.

pub fn send_btc_begin( &self, online: Online, address: String, amount: u64, fee_rate: f32 ) -> Result<String, Error>

Prepare the PSBT to send the specified amount of bitcoins (in sats) using the vanilla wallet to the specified Bitcoin address with the specified fee_rate (in sat/vB).

Signing of the returned PSBT needs to be carried out separately. The signed PSBT then needs to be fed to the send_btc_end function.

This doesn’t require the wallet to have private keys.

Returns a PSBT ready to be signed.

pub fn send_btc_end( &self, online: Online, signed_psbt: String ) -> Result<String, Error>

Broadcast the provided PSBT to send bitcoins using the vanilla wallet.

The provided PSBT, prepared with the send_btc_begin function, needs to have already been signed.

This doesn’t require the wallet to have private keys.

Returns the TXID of the broadcasted transaction.