token.md

Token

Token Overview

Dash Platform lets developers create and manage tokens (similar to ERC-20 style assets) without writing smart contracts. Tokens leverage data contracts, state transitions, and built-in access control (via data contract groups) to enable flexible token management. All token operations are completed by submitting them to the platform in a batch state transition.

Token State Transition Details

All token transitions include the token base transition fields. Most token transitions (.e.g., token mint) require additional fields to provide their functionality.

Token Base Transition

The following fields are included in all token transitions:

Field	Type	Size	Description
$identityContractNonce	unsigned integer	64 bits	Identity contract nonce
$tokenContractPosition	unsigned integer	16 bits	Position of the token within the contract
$dataContractId	array	32 bytes	Data contract ID generated from the data contract's ownerId and entropy
$tokenId	array	32 bytes	Token ID generated from the data contract ID and the token position
usingGroupInfo	GroupStateTransitionInfo object	Varies	Optional field indicating group multi-party authentication rules

Each token transition must comply with the token base transition defined in rs-dpp.

Token id

The $tokenId is created by double sha256 hashing the token $dataContractId and $tokenContractPosition with a byte vector of the string "dash_token" as shown in rs-dpp.

// From the Rust reference implementation (rs-dpp)
// tokens/mod.rs
pub fn calculate_token_id(contract_id: &[u8; 32], token_pos: TokenContractPosition) -> [u8; 32] {
    let mut bytes = b"dash_token".to_vec();
    bytes.extend_from_slice(contract_id);
    bytes.extend_from_slice(&token_pos.to_be_bytes());
    hash_double(bytes)
}

Token Transition Action

The token transition actions defined in rs-dpp indicate what operation platform should perform with the provided transition data.

Action	Name	Description
0	Burn	Permanently remove a specified amount of tokens from circulation
1	Mint	Create new tokens
2	Transfer	Send tokens from one identity to another
3	Freeze	Restrict an identity’s ability to transfer or use tokens
4	Unfreeze	Lift a freeze restriction on an identity's tokens
5	Destroy Frozen Funds	Remove frozen tokens from an identity's balance
6	Claim	Retrieve tokens based on a specified distribution method
7	Emergency Action	Execute an emergency protocol affecting tokens
8	Config Update	Modify the configuration settings of a token

Token Notes

Some token transitions include optional notes fields. The maximum note length for these fields is 2048 characters.

Token Burn Transition

The token burn transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
burnAmount	unsigned integer	64 bits	Number of tokens to be burned
publicNote	string	<= 2048 characters	Optional public note

Each token burn transition must comply with the token burn transition defined in rs-dpp.

Token Mint Transition

The token mint transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
issuedToIdentityId	array	32 bytes	Optional identity ID receiving the minted tokens. If this is not set then we issue to the identity set in contract settings.
amount	unsigned integer	64 bits	Number of tokens to mint
publicNote	string	<= 2048 characters	Optional public note

Each token mint transition must comply with the token mint transition defined in rs-dpp.

Token Transfer Transition

The token transfer transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
amount	unsigned integer	64 bits	Number of tokens to transfer
recipientId	array	32 bytes	Identity ID of the recipient
publicNote	string	<= 2048 characters	Optional public note
sharedEncryptedNote	SharedEncryptedNote object	<= 2048 characters	Optional shared encrypted note
privateEncryptedNote	PrivateEncryptedNote object	<= 2048 characters	Optional private encrypted note

Each token transfer transition must comply with the token transfer transition defined in rs-dpp.

Token Freeze Transition

The token freeze transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
frozenIdentityId	array	32 bytes	Identity ID of the account to be frozen
publicNote	string	<= 2048 characters	Optional public note

Each token freeze transition must comply with the token freeze transition defined in rs-dpp.

Token Unfreeze Transition

The token unfreeze transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
frozenIdentityId	array	32 bytes	Identity ID of the account to be unfrozen
publicNote	string	<= 2048 characters	Optional public note

Each token unfreeze transition must comply with the token unfreeze transition defined in rs-dpp.

Token Destroy Frozen Funds Transition

The token destroy frozen funds transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
frozenIdentityId	array	32 bytes	Identity ID of the account whose frozen balance should be destroyed
publicNote	string	<= 2048 characters	Optional public note

Each token destroy frozen funds transition must comply with the token destroy frozen funds transition defined in rs-dpp.

Token Claim Transition

The token claim transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
distributionType	TokenDistributionType enum	Varies	Type of token distribution targeted
publicNote	string	<= 2048 characters	Optional public note (only saved for historical contracts)

Each token claim transition must comply with the token claim transition defined in rs-dpp.

Token Emergency Action Transition

The token emergency action transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
emergencyAction	TokenEmergencyAction enum	Varies	The emergency action to be executed
publicNote	string	<= 2048 characters	Optional public note

Each token emergency action transition must comply with the token emergency action transition defined in rs-dpp.

Token Config Update Transition

The token config update transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
updateTokenConfigurationItem	TokenConfigurationChangeItem object	Varies	Updated token configuration item
publicNote	string	<= 2048 characters	Optional public note

Each token configuration update transition must comply with the token config update transition defined in rs-dpp.