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 Constants and Limits

Constant	Value	Description
MAX_TOKEN_NOTE_LEN	2,048 bytes	Maximum length for public/private notes
document_batch_sub_transition	100,000 credits	Minimum fee per token sub-transition

Token Fee Payer Options

A document action whose token cost is paid with a token can shift its gas fees (storage and processing) to the contract owner via the GasFeesPaidBy enum. The document type’s token cost states what the contract owner offers, and the transition’s token payment info states what the document owner asks for:

Value	Name	Description
0	DocumentOwner	Fees paid by the identity submitting the transition
1	ContractOwner	Fees paid by the contract owner
2	PreferContractOwner	Fees paid by the contract owner if their balance covers them, otherwise by the document owner

Changed in version 5.0.0: Protocol version 14 acts on GasFeesPaidBy. Earlier versions carried the value but ignored it, and the signer always paid. A request for ContractOwner is rejected unless the document type offers ContractOwner, and PreferContractOwner falls back to the document owner when the contract does not offer to pay. At execution, PreferContractOwner also falls back to the document owner when the contract owner’s balance cannot cover the fee, while a ContractOwner request is refused, and nobody is charged, when the contract owner cannot pay (rs-dpp). See the resolution rules in rs-dpp.

See also

For all protocol constants, see Protocol Constants.

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
$identity-contract-nonce	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
$groupContractPosition $groupActionId $groupActionIsProposer	unsigned integer array boolean	16 bits 32 bytes -	Optional group multi-party authentication info, flattened from GroupStateTransitionInfo so the three fields appear at the top level of the transition. All three are present together or absent together. Since protocol version 13, a transition confirming an existing group action must carry the same $dataContractId and $tokenContractPosition as the original proposal.

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
9	Purchase	Purchase tokens directly from the token’s owner or distribution pool at the predefined price (transfers tokens to the buyer in exchange for Platform credits)
10	Set Purchase Price	Define or update the token’s direct purchase pricing schedule for users (enables or adjusts direct token sales)
11	Shield	Move tokens from the owner’s balance into the token’s shielded pool (added in 5.0.0)
12	Mint To Pool	Mint new tokens directly into the token’s shielded pool (added in 5.0.0)
13	Burn From Pool	Burn tokens held in the token’s shielded pool (added in 5.0.0)
14	Claim To Pool	Claim a distribution into the token’s shielded pool (added in 5.0.0)
15	Direct Purchase To Pool	Purchase tokens at the direct purchase price and receive them in the token’s shielded pool (added in 5.0.0)
16	Unshield	Move tokens from the token’s shielded pool to an identity’s balance (added in 5.0.0)
17	Shielded Transfer	Transfer tokens within the token’s shielded pool (added in 5.0.0)

Note

The numeric action codes above are for client-side reference ordering only. TokenTransitionActionType is not used by the platform backend consensus directly.

The codes follow the order of TokenTransitionActionType. The wire (bincode) variant index of the batch TokenTransition enum matches for codes 0-11 but differs for codes 12-17, whose wire indexes are Unshield 12, Shielded Transfer 13, Mint To Pool 14, Burn From Pool 15, Claim To Pool 16, Direct Purchase To Pool 17.

Token Notes

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

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 bytes	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 bytes	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. Note the $ prefix, which is specific to the transfer transition - the mint transition uses a plain amount field
recipientId	array	32 bytes	Identity ID of the recipient
publicNote	string	<= 2048 bytes	Optional public note
sharedEncryptedNote	SharedEncryptedNote object	<= 2048 bytes	Optional shared encrypted note
privateEncryptedNote	PrivateEncryptedNote object	<= 2048 bytes	Optional private encrypted note

Added in version 5.0.0: A token whose configuration sets transferable: false rejects every transfer transition. Such a token also cannot be a document token cost that pays the contract owner; it can only be burned. Contract registration rejects such a cost, and a payment to the contract owner is refused.

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 bytes	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 bytes	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 bytes	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 (binary 0 = PreProgrammed, 1 = Perpetual, 2 = OncePerIdentity; JSON "PreProgrammed", "Perpetual", or "OncePerIdentity")
publicNote	string	<= 2048 bytes	Optional public note (only saved for historical contracts)

Added in version 5.0.0: Protocol version 14 added the OncePerIdentity distribution type for tokens with a once-per-identity distribution. Each identity can claim it once and receives the configured amount. A second claim by the same identity is rejected. Earlier protocol versions reject a OncePerIdentity claim.

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 (binary 0 = Pause, 1 = Resume; JSON "pause" or "resume")
publicNote	string	<= 2048 bytes	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 bytes	Optional public note

Added in version 5.0.0: TokenConfigurationChangeItem adds MinimumPoolNotesForOutgoing, MinimumPoolNotesForOutgoingControlGroup, and MinimumPoolNotesForOutgoingAdminGroup. They change a token’s minimumPoolNotesForOutgoing and its change control rules, and apply only to a token that has a shielded pool. The new threshold may not exceed 250. hasShieldedPool and transferable cannot be changed.

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

Token Set Purchase Price Transition

The token set purchase price transition enables token purchases by setting the token price using a pricing schedule. This can be a single entry (for a fixed price) or multiple entries for tiered pricing. For example, a token might define a price of 100 credits each for a minimum of 1 token, and 90 credits each for a minimum of 10 tokens – allowing a discount for bulk purchases.

Only an identity authorized by the token’s change direct purchase pricing rules can successfully execute this transition. On execution, platform will update the token’s current direct purchase price schedule. If direct pricing history is enabled, it will also record the change in the token’s history.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
price	Optional TokenPricingSchedule	Variable	(Optional) Set the fixed price or tiered price. Tiered pricing entries consists of a minimum token amount (unsigned 64-bit) and a price in credits (unsigned 64-bit) applicable for purchases of that size or greater. The smallest amount tier also defines the minimum purchasable amount. If the lowest tier has amount > 1, users cannot buy less than that amount in a single purchase. If multiple tiers are provided, they should be ordered by ascending minimum amount. Note: Setting price to null disables direct purchases for the token.
publicNote	string	<= 2048 bytes	Optional public note

The pricing schedule is tagged by a $type field naming the form. A single fixed price uses singlePrice:

{
  "$type": "singlePrice",
  "price": 100
}

Tiered pricing uses setPrices, keyed by minimum token amount:

{
  "$type": "setPrices",
  "prices": {
    "1": 100,
    "10": 90
  }
}

Note

In human-readable JSON, credit and token amount values above Number.MAX_SAFE_INTEGER are serialized as strings. This affects JSON representations only; the bincode serialization used for consensus is unaffected.

Each token set purchase price transition must comply with the token set purchase price transition defined in rs-dpp.

Token Purchase Transition

The token purchase transition mints the requested number of tokens to the purchasing identity. Platform simultaneously deducts the corresponding purchase cost in credits from the buyer’s balance as part of the state transition. The credits are moved from the purchaser to the contract owner by the purchase transition itself; no separate credit transfer is needed. Purchases that would push the total supply above maxSupply are rejected. If direct purchase history is enabled for the token, platform will create a record of this sale in the token’s history.

Attempts to purchase tokens when no price is set, when providing insufficient payment, or below the minimum amount will be rejected by platform consensus.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
tokenCount	unsigned integer	64 bits	Number of tokens the user is purchasing. Must be at least the minimum purchase amount defined by the current pricing and cannot exceed any available supply limits.
totalAgreedPrice	unsigned integer	64 bits	Maximum total price (in credits) the purchaser agrees to pay. Must be at least the unit price (or tiered price) times tokenCount according to the current pricing schedule.

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

Token Shielded Pool Transitions

Added in version 5.0.0: Protocol version 14 added these transitions.

A token whose configuration sets hasShieldedPool has its own shielded pool that holds that token instead of credits. Holders and issuers move tokens into, within, and out of the pool with the token transitions below. Like every token transition, they are submitted in a batch that the identity signs, and the identity pays the fee in credits, including a proof verification fee for each bundle. Tokens are never used to pay fees. To move pooled tokens without an identity, see the token shielded pool state transitions.

Each transition carries an Orchard bundle (actions, anchor, proof, bindingSignature) next to the token base transition fields. The bundle is bound to the transition through the platform sighash, using the extra_data layout listed for each transition below (|| is concatenation; amounts are u64 little-endian). Outputs-only bundles (Shield, Mint To Pool, Claim To Pool, Direct Purchase To Pool) have no spends, so their anchor is not checked against the pool. Their extra_data starts with a kind tag. Bundles that spend notes must use an anchor recorded for the token’s pool.

The following rules apply to every token shielded pool transition:

• Structure validation checks the bundle like other shielded bundles: at most max_shielded_transition_actions actions, correctly sized encrypted notes, a non-empty proof, and a non-zero anchor.

• The token must have a shielded pool and must not be paused. Pausing blocks every pool operation, including transitions that move tokens into the pool.

• A bundle that spends notes must use an anchor recorded for the token pool, and its nullifiers must be unspent. An outputs-only bundle’s dummy nullifiers must not repeat or already be recorded in the pool.

• The proof verification fee is charged before the proof is checked, so a batch whose proof fails is still charged and its nonce advances.

• Transitions that move tokens out of the pool to a visible destination (Unshield and Burn From Pool) require the pool to hold at least the token’s minimumPoolNotesForOutgoing notes. The same minimum applies to a document token cost paid from the token’s pool ($tokenPaymentInfo.shieldedPayment) and to Token Unshield With Shielded Fee (type 27). Transfers inside the pool are not limited.

Token Shield Transition

Move tokens from the batch owner’s token balance into the token’s shielded pool as new notes. The bundle is outputs-only, and its value balance is -amount.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
amount	unsigned integer	64 bits	Tokens leaving the owner’s balance and entering the pool
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature

Sighash extra_data: 0x80 || tokenId || ownerId. amount must be from 1 to 2^48 - 1. The owner’s token balance must cover amount.

Each token shield transition must comply with the token shield transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Mint To Pool Transition

Mint new tokens directly into the token’s shielded pool as new notes. The bundle is outputs-only, and its value balance is -amount. The total supply and the pool balance both grow by amount. This transition can be submitted as a group action (see the base transition group fields).

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
amount	unsigned integer	64 bits	Tokens minted into the pool
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature
publicNote	string	<= 2048 bytes	Optional public note. In a group action, only the proposer may set it

Sighash extra_data: 0x81 || tokenId || minterId, where minterId is the batch owner, or the proposer of a group action. amount must be from 1 to 2^48 - 1. The identity (or group) must be authorized by the token’s manualMintingRules. The token’s mintingAllowChoosingDestination must be true, because the minter chooses the notes’ recipients. The mint must not push the total supply above maxSupply.

Each token mint to pool transition must comply with the token mint to pool transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Burn From Pool Transition

Spend notes in the token’s shielded pool and destroy amount tokens. The bundle’s value balance is +amount, and change returns to the pool as new notes. The total supply and the pool balance both shrink by amount. This transition can be submitted as a group action (see the base transition group fields).

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
amount	unsigned integer	64 bits	Tokens burned from the pool
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature
publicNote	string	<= 2048 bytes	Optional public note. In a group action, only the proposer may set it

Sighash extra_data: tokenId || burnerId || amount, where burnerId is the batch owner, or the proposer of a group action. amount must be from 1 to 2^48 - 1. The identity (or group) must be authorized by the token’s manualBurningRules.

Each token burn from pool transition must comply with the token burn from pool transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Claim To Pool Transition

Claim a token distribution into the token’s shielded pool as new notes instead of into the claimant’s balance. The bundle is outputs-only. The claim is resolved the same way as a token claim.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
distributionType	TokenDistributionType enum	Varies	Type of distribution claimed
claimUpTo	unsigned integer	64 bits	The cycle-aligned moment to claim up to. Required for a perpetual distribution (InvalidTokenClaimPropertyMismatch when missing) and ignored for other distribution types
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature
publicNote	string	<= 2048 bytes	Optional public note

Sighash extra_data: 0x82 || tokenId || ownerId. The claim must not push the total supply above maxSupply.

Each token claim to pool transition must comply with the token claim to pool transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Direct Purchase To Pool Transition

Purchase tokens at the token’s direct purchase price and mint them into the token’s shielded pool as new notes. The batch owner pays the price in credits. The bundle is outputs-only, and its value balance is -tokenCount.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
tokenCount	unsigned integer	64 bits	Number of tokens purchased and minted into the pool
totalAgreedPrice	unsigned integer	64 bits	Maximum total price (in credits) the purchaser agrees to pay
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature

Sighash extra_data: 0x83 || tokenId || ownerId. tokenCount must be from 1 to 2^48 - 1. The pricing schedule and maximum supply are checked as for a token purchase.

Each token direct purchase to pool transition must comply with the token direct purchase to pool transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Unshield Transition

Spend notes in the token’s shielded pool and credit amount to the recipient’s token balance. The bundle’s value balance is +amount, and change returns to the pool as new notes.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
amount	unsigned integer	64 bits	Tokens leaving the pool and credited to recipientId
recipientId	array	32 bytes	Identity ID whose token balance receives amount
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature

Sighash extra_data: tokenId || ownerId || recipientId || amount. amount must be from 1 to 2^48 - 1. The recipient identity must exist, and the pool must hold amount.

Each token unshield transition must comply with the token unshield transition defined in rs-dpp. See the state validation in rs-drive-abci.

Token Shielded Transfer Transition

Spend and recreate notes inside the token’s shielded pool. The bundle’s value balance is zero, so the pool balance does not change.

This transition extends the base transition to include the following additional fields:

Field	Type	Size	Description
actions	array	Varies	Orchard actions of the bundle in the token’s shielded pool
anchor	array of bytes	32 bytes	Anchor of the token pool’s note commitment tree
proof	array of bytes	Varies	Halo 2 proof
bindingSignature	array of bytes	64 bytes	RedPallas binding signature

Sighash extra_data: tokenId || ownerId.

Each token shielded transfer transition must comply with the token shielded transfer transition defined in rs-dpp. See the state validation in rs-drive-abci.