Asset User Whitelists

Asset User Whitelists

Asset User white- and black-lists serve the need for companies to restrict service to a subset of accounts. For instance, a fiat gateway may require to follow KYC/AML regulations and can hence only deal with those customers that have been verified accordingly. If the issuer of an user-issued asset desires, he may set a restriction so that only users on the white-list (and/or not on the blacklist) are allowed to hold his token.

Instead of putting all verified accounts into the respective asset’s white-list directly, BitShares 2.0 allows to define one or several white-list authorities. In practice, the white- and black-lists of these accounts are combined and serve as white- and black-lists for the asset.

This allows for easy out-sourcing of KYC/AML verification to 3rd-party providers.

Note

By removing a user from the whitelist, funds can effectively be frozen.

Example

Let’s assume user alice wants to own a gateways IOUs called G.USD which are restricted by a whitelists. Before being able to own G.USD, alice needs to be white-listed by one of the authorities of G.USD.

Defining an asset’s list authorities

We now define the authorities (i.e. accounts) that define the white- and blacklist of the asset G.USD. We add g-issuer and kycprovider to the white- and black-list::

>>> update_asset G.USD "" "{blacklist_authorities:[g-issuer, kycprovider], whitelist_authorities:[g-issuer, kycprovider], flags:white_list}" true

Note

The third argument for update_asset replaces the existing settings. Make sure to have all desired settings present.

Adding alice to a whitelist

Let’s assume the only authority is the issuer g-issuer himself for simplicity. The issuer now needs to add alice to g-issuer‘s account whitelist::

>>> whitelist_account g-issuer alice white_listed true

Definition

White- and Black-listing of assets works with the following API call:

signed_transaction graphene::wallet::wallet_api::update_asset(string symbol, optional<string> new_issuer, asset_options new_options, bool broadcast = false)

Update the core options on an asset. There are a number of options which all assets in the network use. These options are enumerated in the asset_object::asset_options struct. This command is used to update these options for an existing asset.

Note
This operation cannot be used to update BitAsset-specific options. For these options, update_bitasset() instead.
Return
the signed transaction updating the asset
Parameters
  • symbol: the name or id of the asset to update
  • new_issuer: if changing the asset’s issuer, the name or id of the new issuer. null if you wish to remain the issuer of the asset
  • new_options: the new asset_options object, which will entirely replace the existing options.
  • broadcast: true to broadcast the transaction on the network

struct graphene::chain::asset_options

The asset_options struct contains options available on all assets in the network.

Note
Changes to this struct will break protocol compatibility

Public Functions

void validate() const

Perform internal consistency checks.

Exceptions
  • fc::exception: if any check fails

Public Members

share_type max_supply = GRAPHENE_MAX_SHARE_SUPPLY

The maximum supply of this asset which may exist at any given time. This can be as large as GRAPHENE_MAX_SHARE_SUPPLY

uint16_t market_fee_percent = 0

When this asset is traded on the markets, this percentage of the total traded will be exacted and paid to the issuer. This is a fixed point value, representing hundredths of a percent, i.e. a value of 100 in this field means a 1% fee is charged on market trades of this asset.

share_type max_market_fee = GRAPHENE_MAX_SHARE_SUPPLY

Market fees calculated as market_fee_percent of the traded volume are capped to this value.

uint16_t issuer_permissions = UIA_ASSET_ISSUER_PERMISSION_MASK

The flags which the issuer has permission to update. See asset_issuer_permission_flags.

uint16_t flags = 0

The currently active flags on this permission. See asset_issuer_permission_flags.

price core_exchange_rate

When a non-core asset is used to pay a fee, the blockchain must convert that asset to core asset in order to accept the fee. If this asset’s fee pool is funded, the chain will automatically deposite fees in this asset to its accumulated fees, and withdraw from the fee pool the same amount as converted at the core exchange rate.

flat_set<account_id_type> whitelist_authorities

A set of accounts which maintain whitelists to consult for this asset. If whitelist_authorities is non-empty, then only accounts in whitelist_authorities are allowed to hold, use, or transfer the asset.

flat_set<account_id_type> blacklist_authorities

A set of accounts which maintain blacklists to consult for this asset. If flags & white_list is set, an account may only send, receive, trade, etc. in this asset if none of these accounts appears in its account_object::blacklisting_accounts field. If the account is blacklisted, it may not transact in this asset even if it is also whitelisted.

flat_set<asset_id_type> whitelist_markets

defines the assets that this asset may be traded against in the market

flat_set<asset_id_type> blacklist_markets

defines the assets that this asset may not be traded against in the market, must not overlap whitelist

string description

data that describes the meaning/purpose of this asset, fee will be charged proportional to size of description.

enum graphene::chain::asset_issuer_permission_flags

Values:

charge_market_fee = 0x01

an issuer-specified percentage of all market trades in this asset is paid to the issuer

white_list = 0x02

accounts must be whitelisted in order to hold this asset

override_authority = 0x04

issuer may transfer asset back to himself

transfer_restricted = 0x08

require the issuer to be one party to every transfer

disable_force_settle = 0x10

disable force settling

global_settle = 0x20

allow the bitasset issuer to force a global settling this may be set in permissions, but not flags

disable_confidential = 0x40

allow the asset to be used with confidential transactions

witness_fed_asset = 0x80

allow the asset to be fed by witnesses

committee_fed_asset = 0x100

allow the asset to be fed by the committee