Bitcoin and Altcoin Wallets 6.2.5

Currency extends Post_Type
in package

Currency class.

Encapsulates a currency. A currency:

  • is associated with one wallet
  • specifies details relevant to the currency such as decimals
  • can render amounts

Create a new currency programmatically:

Normally you'd create a currency via the admin screens. But here's how you can do it in PHP:

$bitcoin = new Currency;
$bitcoin->name = 'Bitcoin';
$bitcoin->symbol = 'BTC';
$bitcoin->decimals = 8;
$bitcoin->pattern = 'BTC %01.8f';
$bitcoin->coingecko_id = 'bitcoin';
$bitcoin->min_withdraw = 100000; // all amounts are in satoshis
$bitcoin->max_withdraw = 0; // zero means no daily limit
$bitcoin->max_withdraw_per_role = [ 'administrator' => 0, 'subscriber' => 10000000, ]; // no limit for admins, 1BTC for subscribers
$bitcoin->fee_deposit_site = 0;
$bitcoin->fee_move_site = 100;
$bitcoin->explorer_uri_tx = 'https://blockchair.com/bitcoin/transaction/%s';
$bitcoin->explorer_uri_add = 'https://blockchair.com/bitcoin/address/%s';

try {
	$bitcoin->save();
} catch ( \Exception $e ) {
	error_log( 'Could not save bitcoin currency due to: ' . $e->getMessage() );
}

if ( $bitcoin->post_id ) {
	error_log( "Bitcoin currency was saved with post_id: $bitcoin->post_id" );
}

Get currency

...by post_id

In the general case, there can be multiple currencies using the same ticker symbol. It's safest to refer to currencies by their post_id, if you know it

...by coingecko_id

If you have associated your currency with its correct CoinGecko ID (you should do this to get exchange rates) then you can get a currency by its unique CoinGecko ID.

$bitcoin = \DSWallets\get_first_currency_by_coingecko_id( 'bitcoin' );

...by ticker symbol

If you know that only one currency uses this ticker, you can retrieve the currency by its ticker:

$bitcoin = \DSWallets\get_first_currency_by_symbol( 'BTC' );

Iterate over all the Currency posts:

$currencies = \DSWallets\get_all_currencies();

foreach ( $currencies as $currency ) {
	error_log( $currency );
	// do stuff with each currency
}

Get all fiat currencies

Fiat currencies should have the fiat taxonomy term (tag) assigned to them.

$fiat_currencies = load_currencies( get_currency_ids( 'fiat' ) );

Get all cryptocurrencies (i.e. not fiat)

$cryptocurrencies = load_currencies(
	array_diff(
		get_currency_ids(), // gets all currency IDs
		get_currency_ids( 'fiat' )
		)
	);

Is a currency fiat or not?

// returns true if currency has `fiat` tag, OR if it is assigned to the Bank_Fiat_Adapter
	$currency->is_fiat();

Displaying amounts to the user

Here we display the minimal withdrawal amount for this currency. We first convert the integer amount to a float, then we use the sprintf() pattern to render it to a string:

// get a hold of the currency
$bitcoin = \DSWallets\get_first_currency_by_symbol( 'BTC' );

// divide the integer amount by ten to the power of how many decimals are allowed, i.e. *10^(-8)
$min_withdraw_amount_btc = $bitcoin->min_withdraw * 10 ** -$bitcoin->decimals;

// use the pattern field to render the float amount
error_log( sprintf( "Min withdraw: $bitcoin->pattern", $min_withdraw_amount_btc" );
Tags
since
6.0.0

Introduced.

author

Alexandros Georgiou info@dashed-slug.net

Table of Contents

$post_id  : int
The id of the post that this object represents.
$coingecko_id  : string|null
CoinGecko unique ID for currency.
$contract_address  : string|null
Contract address or asset_id.
$decimals  : int
Number of decimals
$explorer_uri_add  : string|null
Block explorer URI pattern for addresses.
$explorer_uri_tx  : string|null
Block explorer URI pattern for transactions.
$fee_deposit_site  : int
Deposit fee paid to the site (not the blockchain).
$fee_move_site  : int
Internal transaction fee paid to the site (off-chain transactions)
$fee_withdraw_site  : int
Withdrawal fee paid to the site (not the blockchain)
$icon_url  : string|null
Coin icon url.
$max_withdraw  : int
Daily maximum withdraw limit. Zero means no limit.
$max_withdraw_per_role  : array<string|int, mixed>
Daily maximum withdraw limits per role. Is an assoc array mapping role slugs to amounts. Zero means no limit.
$min_withdraw  : int
Minimum withdraw amount.
$name  : string
Currency name.
$pattern  : string
An sprintf() pattern for rendering amounts
$rates  : array<string, float>
Exchange rates.
$symbol  : string
Ticker symbol
$wallet  : Wallet|null
The wallet adapter associated with this currency
__get()  : mixed
Allows getting one of this object's fields.
__set()  : mixed
Sets a field of this Currency object.
__toString()  : string
To String.
delete()  : mixed
Trashes this object in the DB.
get_max_withdraw()  : int
Get max withdraw for user
get_platform()  : string|null
get_rate()  : float|null
Get the exchange rate of this currency against the specified "VS currency".
get_rate_to()  : float|null
Get the exchange rate of this currency against the specified other currency.
is_fiat()  : bool
Determines whether this currency is fiat.
is_online()  : bool
Determines whether this currency is online.
is_set_decimals()  : bool
Returns true iff decimals field has been set for this currency.
is_token()  : bool
Determines whether this currency is a token on a blockchain that supports multiple assets.
load()  : Currency
Load a Currency object from its custom post entry.
save()  : void
Saves this object to the DB.
set_rate()  : bool
render_bool_field()  : mixed
render_boolean_field()  : mixed
render_number_field()  : mixed
render_secret_field()  : mixed
render_select_field()  : mixed
render_string_field()  : mixed
render_strings_field()  : mixed

Properties

$coingecko_id

CoinGecko unique ID for currency.

private string|null $coingecko_id

$contract_address

Contract address or asset_id.

private string|null $contract_address = null
  • For EVM tokens, this will always start with 0x.
  • For Taproot Assets, this will typically be a string without the 0x prefix.
  • For other coins that are native to their blockchain, this will be null.

$decimals

Number of decimals

private int $decimals = 0

This is used for saving all amounts as integers to DB and avoid FP/rounding errors.

Side effect: If a pattern is not set, an appropriate pattern for this number of decimals will also be set, when a new amount of decimals is set.

$explorer_uri_add

Block explorer URI pattern for addresses.

private string|null $explorer_uri_add = null

An sprintf() pattern to generate a block explorer URI from an address string.

Tags
see
sprintf()

$explorer_uri_tx

Block explorer URI pattern for transactions.

private string|null $explorer_uri_tx = null

An sprintf() pattern to generate a block explorer URI from a transaction id (TXID)

Tags
see
sprintf()

$fee_deposit_site

Deposit fee paid to the site (not the blockchain).

private int $fee_deposit_site = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$fee_move_site

Internal transaction fee paid to the site (off-chain transactions)

private int $fee_move_site = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$fee_withdraw_site

Withdrawal fee paid to the site (not the blockchain)

private int $fee_withdraw_site = 0

The amount must be shifted by $this->decimals decimal places to get the actual float amount.

$icon_url

Coin icon url.

private string|null $icon_url = null

The post thumbnail url. Read only. Admin must set the thumbnail image via the WP editor.

$max_withdraw

Daily maximum withdraw limit. Zero means no limit.

private int $max_withdraw = 0

$max_withdraw_per_role

Daily maximum withdraw limits per role. Is an assoc array mapping role slugs to amounts. Zero means no limit.

private array<string|int, mixed> $max_withdraw_per_role = []

$min_withdraw

Minimum withdraw amount.

private int $min_withdraw = 0

$name

Currency name.

private string $name

Free text string, stored on the post_title column in the DB.

$pattern

An sprintf() pattern for rendering amounts

private string $pattern = '%f'
Tags
see
sprintf()

$rates

Exchange rates.

private array<string, float> $rates = []

An assoc array of vs_currencies to rates.

The keys are strings containing ticker symbols for the major currencies.

Methods

__get()

Allows getting one of this object's fields.

public __get(mixed $name) : mixed
Parameters
$name : mixed

The name of the field to retrieve.

Return values
mixed —

__set()

Sets a field of this Currency object.

public __set(string $name, mixed $value) : mixed
Parameters
$name : string

Can be: post_id, name, symbol, pattern, coingecko_id, contract_address, explorer_uri_tx, explorer_uri_add, wallet, min_withdraw, max_withdraw, fee_deposit_site, fee_move_site, fee_withdraw_site, decimals.

$value : mixed

The value to set to the field.

Tags
see
Post_Type::__set()
throws
InvalidArgumentException

If value is not appropriate for field or if field does not exist.

Return values
mixed —

delete()

Trashes this object in the DB.

public delete([mixed $force = false ]) : mixed
Parameters
$force : mixed = false
Tags
throws
Exception

If the object was not on the DB or if it could not be trashed.

Return values
mixed —

get_max_withdraw()

Get max withdraw for user

public get_max_withdraw([WP_User|null $user = null ]) : int

Returns the maximum allowed amount to withdraw for this user and currency.

The hard daily withdraw limit is max_withdraw. The user can also belong to a number of roles: The role with the highest withdrawal daily limit is always applicable, as long as it is less than the hard daily limit.

Parameters
$user : WP_User|null = null

The user whose limit to return. If not set, function returns the hard daily limit for this currency.

Return values
int —

The applicable daily withdrawal limit.

get_platform()

public get_platform() : string|null
Return values
string|null —

get_rate()

Get the exchange rate of this currency against the specified "VS currency".

public get_rate(string $vs_currency) : float|null

You can multiply an amount expressed in this currency by the returned value to convert to the "VS currency".

Parameters
$vs_currency : string

A CoinGecko "VS currency".

Tags
since
6.0.0

Introduced.

Return values
float|null —

The exchange rate, or null if not defined.

get_rate_to()

Get the exchange rate of this currency against the specified other currency.

public get_rate_to(Currency $currency) : float|null

For the conversion to be successful, there must be a common "VS currency rate" defined for both Currencies.

Example code:

get_rate_to( $doge ); $rate2 = $doge->get_rate_to( $btc ); printf( "BTC->get_rate_to(DOGE): %01.8f\nDOGE->get_rate_to(BTC): %01.8f", $rate1, $rate2 ); ?>

Will print out:

BTC->get_rate_to(DOGE): 165837.47927032
DOGE->get_rate_to(BTC): 0.0000060374
Parameters
$currency : Currency

The other currency to convert to.

Return values
float|null —

The exchange rate, or null if not defined.

is_fiat()

Determines whether this currency is fiat.

public is_fiat() : bool
Return values
bool —

is_online()

Determines whether this currency is online.

public is_online() : bool

Checks if the currency is connected to a wallet and if that wallet is enabled and has a successfully instantiated wallet adapter, and if that adapter is responding to commands.

Return values
bool —

Whether we can connect to wallet backing this currency.

is_set_decimals()

Returns true iff decimals field has been set for this currency.

public is_set_decimals() : bool

Will return false if the field is not set. Will return true if field has been set to 0 (zero). This is to allow for currencies that have no decimals.

Return values
bool —

Whether the decimals field has been set to an integer or 0.

is_token()

Determines whether this currency is a token on a blockchain that supports multiple assets.

public is_token() : bool

Fiat currencies and crytocurrency coins are not tokens.

Return values
bool —

load()

Load a Currency object from its custom post entry.

public static load(int $post_id) : Currency
Parameters
$post_id : int

The post_id for the object to load.

Tags
inheritdoc
see
Post_Type::load()
Return values
Currency —

save()

Saves this object to the DB.

public save() : void

If the object already had a post_id, then the post is updated. Else, a new custom post is created and the new post_id is assigned to the object.

Return values
void —

set_rate()

public set_rate(string $vs_currency, float $rate) : bool
Parameters
$vs_currency : string
$rate : float
Return values
bool —

render_bool_field()

protected static render_bool_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_boolean_field()

protected static render_boolean_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_number_field()

protected static render_number_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_secret_field()

protected static render_secret_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_select_field()

protected static render_select_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_string_field()

protected static render_string_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

render_strings_field()

protected static render_strings_field(mixed $schema, mixed $value) : mixed
Parameters
$schema : mixed
$value : mixed
Return values
mixed —

Search results