-
Notifications
You must be signed in to change notification settings - Fork 206
Confidential assets
This documents describes CLI Confidential Assets workflow.
Consult the MW CLA section for Confidential Assets implementation details.
Consult the Beam wallet protocol API section for API calls description. N.B. assets can be registered only via CLI.
Assets Support
Confidential Assets (hereinafter СA) support requires Fork2 and at least v5.0 CLI/API. Any CA operation before Fork2 would fail with the AssetsDisabledFork2 (45) error code.
In v5.0 CA support is disabled by default to avoid compatibility issues. In the GUI wallet CA support cannot be enabled at the moment. All incoming CA transactions would be rejected by the GUI wallet with the AssetsDisabled (43) error code. Rejected CA transactions are not displayed by the GUI wallet. Full GUI assets support is planned for v5.1.
In the CLI and API --enable_assets flag should be specified to perform any CA transactions. Without this flag CA transactions would be rejected with the AssetsDisabled (43) error code.
Information about Assets UTXOs/Shielded Coins/Assets Transactions/Assets Summary can be displayed using --assets or --asset_id ID parameters added to the corresponding commands.
Fees
All fees (transaction fees and registration deposit) are always paid in BEAM/Groth. It is not possible to pay any fees using assets.
Asset Owner
Asset Owner is the person (wallet) which registered the asset. Asset owner owns private key used for signing asset issue/consume/unreg operations. Only the asset owner can perform these operations.
Asset ID is an unsigned integer associated with the asset. Asset is known to the world by its asset id. Asset operations are performed using its asset id. Node assigns asset id during the asset registration process and uses the first id available.
Technically there can be a situation when one asset is unregistered, asset id becomes available and the next registered asset takes the id that has been previously used. Lock period is introduced to ensure that asset receiver would never receive an unexpected (forged) asset.
Asset ID of 0 is reserved and represents original BEAM.
Asset Info
Asset info is information about the asset. It includes asset metadata, total emission and lock height. Asset info is received by the wallet automatically during asset transactions or can be requested manually using asset_info command.
Some parts of the asset info are valid only at the height the asset info has been received (refresh height). In subsequent blocks total asset emission can change or the asset become unregistered. Unregistering the asset invalidates all the information associated with the particular asset id.
Maximum Asset emission is 2128-1 asset nth units. Maximum amount for a single asset transaction (issue, consume, send, receive &c.) is 264-1 asset nth units.
Lock period is a timeframe when several asset operations are restricted for safety reasons. This ensures that asset is not changed during rollback and/or by the asset owner and that receiver of the asset would receive exactly the expected asset.
Asset becomes locked every time when its total emission reaches 0 or leaves 0. Currently lock period duration is set to 1440 blocks (24 hours roughly).
Restricted operations are the following:
- Asset unreg
- Asset send/receive
Restore
General rules apply to the restore process. You can restore your UTXOs but not transactions. To restore shielded
UTXOs node used for the restore process should be running with your owner key. Asset info is not restored automatically. You would need to execute the asset_info command for each restored asset manually after the restore process is completed.
Before asset can be used it should be registered on chain using the asset_reg command:
./beam-wallet asset_reg --pass 1 -n 127.0.0.1:10000 --asset_meta "STD:SCH_VER=1;N=Beam Coin;SN=BEAM;UN=Beam;NTHUN=Groth;CUSTOM1=VAL1;CUSTOM2=VAL2" --fee 100 --enable_assets
You must specify your wallet password, node address, asset meta, optional transaction fee and add --enable_assets flag.
Fees
There is a fixed fee for asset registration of 10 BEAM. This fee is mandatory, cannot be changed and deduced from your wallet automatically. Registration fee ensures that the network would not be spammed with dummy assets. Registration fee is returned to the owner of the asset as soon as the asset is unregistered. So basically 10 BEAM are locked for the asset lifetime. You must also pay regular transactions fees. The --fee param applies only to the transaction fee, not the registration fee.
Asset meta
Asset meta is a byte buffer associated with the asset and stored on chain. It is provided on asset registration and cannot be changed afterwards. Currently CLI expects UTF8 string with several mandatory Key=Value pairs. It is not possible to register an asset without meta. Please consult the Asset Descriptor document for more details.
Asset ID
After successful asset registration it is associated with the Asset ID issued by the node. Asset becomes known to the world by its ID. Asset id is used in any asset operations performed by any person. Asset owner can perform asset operations using as asset id or asset meta. Consult the Asset ID section for more details.
Lock Period
Immediately after the asset registration it becomes locked for 24h hours. Consult the Lock period section for more details.
Privacy
Transaction kernel including all the asset meta becomes visible to the world. Node would know that you/your IP is the owner of the asset.
API Restriction
Asset registration can be performed only via CLI. There is no API call for asset registration for safety reasons.
After asset registration its total emission is set to 0. Before performing any asset transactions the owner must mint (issue) asset coins using the issue command. Only asset owner can mint asset coins.
./beam-wallet issue --pass 1 --asset_id 1 -n 127.0.0.1:10000 --amount 10 --fee 100 --enable_assets
./beam-wallet issue --pass 1 --asset_meta "STD:SCH_VER=1;N=Beam Coin;SN=BEAM;UN=Beam;NTHUN=Groth;CUSTOM1=VAL1;CUSTOM2=VAL2" -n 127.0.0.1:10000 --amount 10 --fee 100 --enable_assets
You must specify your wallet password, node address, asset id or asset meta, issue amount, optional transaction fee and add --enable_assets flag.
Coins availability
New Asset coins cannot be used until the issue transaction is completed. Please ensure that the minting process is completed and new coins are present in your wallet and marked as available before sending them.
Fees
Asset emission is absolutely free. You can mint as many coins as you want. You pay only regular transaction fee.
Limits
Maximum Asset emission is 2128-1 asset nth units. Maximum amount for a single issue transaction is 264-1 asset nth units.
Lock Period
If after the issue operation total asset emission leaves 0 asset becomes locked. Consult the Lock period section for more details. Asset issue can be performed even if asset is locked. Subsequent asset issue operations do not extend the lock period.
Privacy
Asset information is forcibly refreshed (received from node) during this operation. Operation fails if node doesn't confirm the asset. Transaction kernel including the issued asset amount and asset id becomes visible to the world. Node would know that you/your IP is the owner of the asset.
Owner of the asset can consume (burn) asset coins. To burn the asset you must both be the owner of the asset and the owner of the particular coin/utxo. Asset can be consumed using the consume command.
./beam-wallet consume --pass 1 --asset_id 1 -n 127.0.0.1:10000 --amount 10 --fee 100 --enable_assets
./beam-wallet consume --pass 1 --asset_meta "STD:SCH_VER=1;N=Beam Coin;SN=BEAM;UN=Beam;NTHUN=Groth;CUSTOM1=VAL1;CUSTOM2=VAL2" -n 127.0.0.1:10000 --amount 10 --fee 100 --enable_assets
You must specify your wallet password, node address, asset id or asset meta, consume amount, optional transaction fee and add --enable_assets flag.
Fees
Asset consuming is absolutely free. You pay only regular transaction fee.
Limits
Maximum amount for a single consume transaction is 264-1 asset nth units.
Lock Period
If after the consume operation total asset emission reaches 0 asset becomes locked. Consult the Lock period section for more details.
Privacy
Asset information is forcibly refreshed (received from node) during this operation. Operation fails if node doesn't confirm the asset. Transaction kernel including the consumed asset amount and asset id becomes visible to the world. Node would know that you/your IP is the owner of the asset.
Asset can be unregistered from chain by the owner. To unregister the asset its emission should be 0 and it should be not locked. Asset is unregistered using the asset_unreg command.
./beam-wallet asset_unreg --pass 1 -n 127.0.0.1:10000 --asset_meta "STD:SCH_VER=1;N=Beam Coin;SN=BEAM;UN=Beam;NTHUN=Groth;CUSTOM1=VAL1;CUSTOM2=VAL2" --fee 100 --enable_assets
./beam-wallet asset_unreg --pass 1 -n 127.0.0.1:10000 --asset_id 1 --fee 100 --enable_assets
You must specify your wallet password, node address, asset meta or asset id, optional transaction fee and add --enable_assets flag.
Fees
Asset unregistration is free. You pay only regular transaction fee. This operation also returns 3000 BEAM locked during the asset registration.
Asset ID
Asset ID becomes free after this operation and can be reused by another asset.
Limits
Maximum amount for a single consume transaction is 264-1 asset nth units.
Privacy
Asset information is forcibly refreshed (received from node) during this operation. Operation fails if node doesn't confirm the asset. Transaction kernel which includes asset id becomes visible to the world. Node would know that you/your IP is the owner of the asset.
API Restriction
Asset unregistration can be performed only via CLI. There is no API call for asset unregistration for safety reasons.
Asset info can be received from node using asset_info command for any asset registered on chain. asset_info command stores the received info in a local database for future usage.
./beam-wallet asset_info --pass 1 -n 127.0.0.1:10000 --asset_id 1 --enable_assets
asset_info command always receives the latest information from node. To view locally stored information regular info command should be used with --assets or --asset_id ID parameters.
Asset owner can query asset info using asset meta (--asset_meta "STD:....") as well. Non-owners can use only asset id.
Fees
asset_info operation is free. You do not pay any fees.
Privacy
asset_info operation only communicates with the node and doesn't leave any traces in the blockchain. Node would know that particular IP has been interested in given asset.
By default CLI wallet doesn't display any information about assets you own or have. To view assets info, assets UTXOs & assets transactions --assets (for all assets) or --asset_id ID (for a specific asset) params should be used.
View asset info & asset UTXOs
./beam-wallet info --pass 1 --asset_id 1
./beam-wallet info --pass 1 --assets
View asset transactions
./beam-wallet info --pass 1 --asset_id 1 --tx_history
./beam-wallet info --pass 1 --assets --tx_history
View shielded (Lelantus) asset UTXOs
./beam-wallet info --pass 1 --asset_id 1 --shielded_utxos
./beam-wallet info --pass 1 --assets --shielded_utxos
View Shielded (Lelantus) Asset transactions
./beam-wallet info --pass 1 --asset_id 1 --shielded_tx_history
./beam-wallet info --pass 1 --assets --shielded_tx_history
Enable flag
Asset info can be displayed without the --enable_assets flag
Orphaned transactions
Asset transactions that do not include asset id would be displayed as orphaned. This can occur when transaction has been started with --asset_meta param and no valid asset id has been associated with the transaction while it was running. For example it can happen if you have tried to register an asset but there is not enough BEAM to pay the registration fee.
Asset can be sent using regular send command. The only difference from regular BEAM transaction is the --asset_id and --enable_assets parameters.
./beam-wallet -n 127.0.0.1:10000 --pass 1 --command send -r 1ec08b72ea25cd471ec37f9088a1ae0dcb8f4526eff3b8ab38f8e23901e2adf48a2 --amount 5 --asset_id 1 --enable_assets
Limits
Maximum amount for a single send transaction is 264-1 asset nth units.
Enable flag
Both sender and receiver should specify --enable_assets flag in command line otherwise transaction would fail with the AssetsDisabled (43) error code.
Lock period
Asset cannot be sent to non-owner during the lock period. Transaction would be rejected by the receiving party with the AssetLocked (34) error code.
Privacy
Send transaction doesn't refresh asset info. Asset ID is hidden during the send transaction though it is visible that the transaction is performed on some asset. General Mimblewimble rules apply to the transaction. Amount, sender and receiver are not disclosed.
Process of receiving assets is mostly identical to the receiving of regular BEAM.
Enable flag
CLI/API receives assets automatically if it is running (listens) with the --assets_enable option. If assets are not enabled all incoming asset transaction would be rejected with the AssetsDisabled (43) error code.
Lock period
Asset cannot be received by non-owner during the lock period. Transaction would be rejected by the receiving party with the AssetLocked (34) error code.
Privacy
Receive operation does not refresh asset info if there are any unspent UTXOs of the asset being received in the wallet. If there are no unspent UTXOs asset info might be refreshed if wallet doesn't have info about the asset (first receive) or info is older than the lock period duration.
Asset ID is hidden during the receive transaction though it is visible that the transaction is performed on some asset. General Mimblewimble rules apply to the transaction. Amount, sender and receiver are not disclosed.
N.B. As of v5.1 basic lelantus operations (pull & push) are removed. The info below applies only to the v5.0
Lelantus transactions fully support confidential assets. To insert to/extract asset from pool --asset_id ID option should be specified as well as --enable_assets flag. Refer Lelantus CLI for details.
Lock Period
Lock period rules do not apply to Lelantus transactions. Assets can be inserted to the pool and extracted from the pool at any time.
Privacy
Asset info is never refreshed during Lelantus transactions. Amount and Asset ID is hidden though it is visible that the transaction is performed on some asset.