Using Whitelists and Blacklists

User Whitelists

Any live-time member can cast an opinion about other accounts using white- and black-lists. They do not prevent anyone from interacting with your account but serve as a basis for list authorities.

Examples*

A user white can be added to the white-list of account provider with::

>>> whitelist_account provider white white_listed true

In contrast a black user can be added to its blacklist with::

>>> whitelist_account provider black black_listed true

Both can be removed from their lists with::

>>> whitelist_account provider black no_listing true
>>> whitelist_account provider white no_listing true

Definition

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

signed_transaction graphene::wallet::wallet_api::whitelist_account(const string &authorizing_account, const string &account_to_list, account_whitelist_operation::account_listing new_listing_status, bool broadcast = false) const

Whitelist and blacklist accounts, primarily for transacting in whitelisted assets.

Accounts can freely specify opinions about other accounts, in the form of either whitelisting or blacklisting them. This information is used in chain validation only to determine whether an account is authorized to transact in an asset type which enforces a whitelist, but third parties can use this information for other uses as well, as long as it does not conflict with the use of whitelisted assets.

An asset which enforces a whitelist specifies a list of accounts to maintain its whitelist, and a list of accounts to maintain its blacklist. In order for a given account A to hold and transact in a whitelisted asset S, A must be whitelisted by at least one of S’s whitelist_authorities and blacklisted by none of S’s blacklist_authorities. If A receives a balance of S, and is later removed from the whitelist(s) which allowed it to hold S, or added to any blacklist S specifies as authoritative, A’s balance of S will be frozen until A’s authorization is reinstated.

Return

the signed transaction changing the whitelisting status

Parameters

  • authorizing_account: the account who is doing the whitelisting

  • account_to_list: the account being whitelisted

  • new_listing_status: the new whitelisting status

  • broadcast: true to broadcast the transaction on the network

It expects a new_listing_status from

enum graphene::protocol::account_whitelist_operation::account_listing

Values:

no_listing = 0x0

No opinion is specified about this account.

white_listed = 0x1

This account is whitelisted, but not blacklisted.

black_listed = 0x2

This account is blacklisted, but not whitelisted.

white_and_black_listed = white_listed | black_listed

This account is both whitelisted and blacklisted.


Asset Market Whitelists

An issuer of an user-issued-asset may want to restrict trading partners for his assets for legal reasons. For instance, a gateway for US dollar may not be allowed to let his customers trade USD against CNY because additional licenses would be required. Hence, in BitShares 2.0 we let issuers chose to restrict trading partners with white- and black-lists.

Example

A gateway with IOU G.USD that wants to prevent his customers from trading G.USD against bitCNY can do so by adding bitCNY to the blacklist of G.USD by issuing::

>>> update_asset G.USD "" "{blacklist_markets:[CNY]}" true

Alternatively, if an issuer may want to only open the market G.USD : bitUSD with his asset, he can do so as well with::

>>> update_asset G.USD "" "{whitelist_markets:[USD]}" true

Note

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

Definition

Asset Market white-lists work with the following API call:

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

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_or_id: the symbol 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

Warning

doxygenstruct: Cannot find class “graphene::chain::asset_options” in doxygen xml output for project “bitshares” from directory: ../doxygen/xml/

Warning

doxygenenum: Cannot find enum “graphene::chain::asset_issuer_permission_flags” in doxygen xml output for project “bitshares” from directory: ../doxygen/xml/


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(const string &symbol_or_id, const optional<string> &new_issuer, const asset_options &new_options, bool broadcast = false) const

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_or_id: the symbol 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

Warning

doxygenstruct: Cannot find class “graphene::chain::asset_options” in doxygen xml output for project “bitshares” from directory: ../doxygen/xml/

Warning

doxygenenum: Cannot find enum “graphene::chain::asset_issuer_permission_flags” in doxygen xml output for project “bitshares” from directory: ../doxygen/xml/