From 07ca8559f09837d6bafa093621ae742c28f163e8 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 17 Mar 2025 10:20:30 -0400 Subject: [PATCH 01/12] docs(ref): add placeholder page for token info --- docs/protocol-ref/data-contract-token.md | 1 + docs/protocol-ref/data-contract.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 docs/protocol-ref/data-contract-token.md diff --git a/docs/protocol-ref/data-contract-token.md b/docs/protocol-ref/data-contract-token.md new file mode 100644 index 000000000..334f7d1df --- /dev/null +++ b/docs/protocol-ref/data-contract-token.md @@ -0,0 +1 @@ +# Contract Tokens diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index a581b4921..edb2aa3c4 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -735,4 +735,5 @@ Data contract state transitions must be signed by a private key associated with :hidden: data-contract-document +data-contract-token ``` From 544cca52a351faac54c6e0f6ad1096d81c704aac Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 17 Mar 2025 16:04:34 -0400 Subject: [PATCH 02/12] docs(ref): link updates Some links changed after recent pull requests --- docs/protocol-ref/data-contract-document.md | 8 ++++---- docs/protocol-ref/data-contract.md | 2 +- docs/protocol-ref/state-transition.md | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/protocol-ref/data-contract-document.md b/docs/protocol-ref/data-contract-document.md index 7dc97a4e8..df4d8b071 100644 --- a/docs/protocol-ref/data-contract-document.md +++ b/docs/protocol-ref/data-contract-document.md @@ -209,13 +209,13 @@ For performance and security reasons, indices have the following constraints. Th | ----------- | ----- | | Minimum/maximum length of index `name` | [1](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L311) / [32](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L312) | | Maximum number of indices | [10](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L390) | -| Maximum number of unique indices | [10](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L26) | +| Maximum number of unique indices | [10](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L27) | | Maximum number of contested indices | [1](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_validation_versions/v2.rs#L26) | | Maximum number of properties in a single index | [10](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/schema/meta_schemas/document/v0/document-meta.json#L331) | -| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L72) | +| Maximum length of indexed string property | [63](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L34) | | Usage of `$id` in an index [disallowed](https://github.com/dashpay/platform/pull/178) | N/A | -| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L73) | -| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/v0/mod.rs#L74) | +| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum length of indexed byte array property | [255](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L35) | +| **Note: Dash Platform [does not allow indices for arrays](https://github.com/dashpay/platform/pull/225).**
Maximum number of indexed array items | [1024](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/document_type/class_methods/try_from_schema/mod.rs#L36) | **Example** The following example (excerpt from the DPNS contract's `preorder` document) creates an index named `saltedHash` on the `saltedDomainHash` property that also enforces uniqueness across all documents of that type: diff --git a/docs/protocol-ref/data-contract.md b/docs/protocol-ref/data-contract.md index edb2aa3c4..e3357a3a2 100644 --- a/docs/protocol-ref/data-contract.md +++ b/docs/protocol-ref/data-contract.md @@ -40,7 +40,7 @@ Include the following at the same level as the `properties` keyword to ensure pr ## Data Contract Object -The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L46-L75)): +The data contract object consists of the following fields as defined in the Rust reference client ([rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/v1/data_contract.rs#L67-L105)): | Property | Type | Size | Description | | --------------- | -------------- | ---- | ----------- | diff --git a/docs/protocol-ref/state-transition.md b/docs/protocol-ref/state-transition.md index 469b07f2c..2edc3f2bb 100644 --- a/docs/protocol-ref/state-transition.md +++ b/docs/protocol-ref/state-transition.md @@ -13,7 +13,7 @@ ### Fees -State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of [1000 credits/satoshi](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/balances/credits.rs#L40). Fees for actions vary based on parameters related to storage and computational effort that are defined in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/fee/default_costs/constants.rs). +State transition fees are paid via the credits established when an identity is created. Credits are created at a rate of [1000 credits/satoshi](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/balances/credits.rs#L37). Fees for actions vary based on parameters related to storage and computational effort that are defined in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/fee/default_costs/constants.rs). ### Size @@ -47,7 +47,7 @@ Dash Platform Protocol defines the [state transition types](https://github.com/d | ownerId | array of bytes | 32 bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) | | transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-overview) or token actions (up to 10 objects) | -More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L39-L50). +More detailed information about the `transitions` array can be found in the [document section](../protocol-ref/document.md). See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L29-L37). ### Data Contract Create From a671cdad6a038858381c14643772ac50cb13e9b4 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 17 Mar 2025 17:04:06 -0400 Subject: [PATCH 03/12] docs(ref): start token page --- docs/index.md | 1 + docs/protocol-ref/token.md | 94 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/protocol-ref/token.md diff --git a/docs/index.md b/docs/index.md index b81974968..2c9233e51 100644 --- a/docs/index.md +++ b/docs/index.md @@ -161,6 +161,7 @@ protocol-ref/identity protocol-ref/data-contract protocol-ref/state-transition protocol-ref/document +protocol-ref/token protocol-ref/data-trigger protocol-ref/errors ``` diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md new file mode 100644 index 000000000..4c5b158a7 --- /dev/null +++ b/docs/protocol-ref/token.md @@ -0,0 +1,94 @@ +# Token + +## Token Overview + +## Token State Transition Details + +### Token Base Transition + +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72 + +```rs +pub struct TokenBaseTransitionV0 { + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "$identity-contract-nonce") + )] + pub identity_contract_nonce: IdentityNonce, + /// ID of the token within the contract + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "$tokenContractPosition") + )] + pub token_contract_position: u16, + /// Data contract ID generated from the data contract's `owner_id` and `entropy` + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "$dataContractId") + )] + pub data_contract_id: Identifier, + /// Token ID generated from the data contract ID and the token position + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "$tokenId") + )] + pub token_id: Identifier, + /// Using group multi party rules for authentication + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub using_group_info: Option, +} +``` + +### Token Burn Transition + +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L38 + +```rs +pub struct TokenBurnTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "burnAmount") + )] + /// How much should we burn + pub burn_amount: u64, + /// The public note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "publicNote") + )] + pub public_note: Option, +} +``` + +### Token Claim Transition + +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L18-L26 + +```rs +pub struct TokenClaimTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// The type of distribution we are targeting + pub distribution_type: TokenDistributionType, + /// A public note, this will only get saved to the state if we are using a historical contract + pub public_note: Option, +} +``` + +### Token Config Update Transition + +### Token Destroy Frozen Funds Transition + +### Token Emergency Action Transition + +### Token Freeze Transition + +### Token Mint Transition + +### Token Transfer Transition + +### Token Unfreeze Transition From a474ae35f22a3434819db8c92fadf80afe6074b3 Mon Sep 17 00:00:00 2001 From: thephez Date: Mon, 17 Mar 2025 17:15:26 -0400 Subject: [PATCH 04/12] docs(ref): add links for remaining token transitions --- docs/protocol-ref/token.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 4c5b158a7..3d4e429bc 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -81,14 +81,28 @@ pub struct TokenClaimTransitionV0 { ### Token Config Update Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27 + ### Token Destroy Frozen Funds Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25 + ### Token Emergency Action Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24 + ### Token Freeze Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L35 + ### Token Mint Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L43 + ### Token Transfer Transition +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61 + ### Token Unfreeze Transition + +https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35 From 191ef06efb19509fd6e998d9f69581d2ebf86b6d Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 18 Mar 2025 10:19:22 -0400 Subject: [PATCH 05/12] docs(ref): add more token st info --- docs/protocol-ref/token.md | 139 ++++++++++++++++++++++++++++++++++++- 1 file changed, 138 insertions(+), 1 deletion(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 3d4e429bc..ae93c2083 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -1,9 +1,11 @@ -# Token +# Token ## Token Overview ## Token State Transition Details +All token transitions include the [token base transition fields](#token-base-transition). Most token transitions (.e.g., [token mint](#token-mint-transition)) require additional fields to provide their functionality. + ### Token Base Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72 @@ -83,26 +85,161 @@ pub struct TokenClaimTransitionV0 { https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27 +```rs +pub struct TokenConfigUpdateTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// Updated token configuration item + pub update_token_configuration_item: TokenConfigurationChangeItem, + /// The public note + pub public_note: Option, +} +``` + ### Token Destroy Frozen Funds Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25 +```rs +pub struct TokenDestroyFrozenFundsTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// The identity id of the account whose balance should be destroyed + pub frozen_identity_id: Identifier, + /// The public note + pub public_note: Option, +} +``` + ### Token Emergency Action Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24 +```rs +pub struct TokenEmergencyActionTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// The emergency action + pub emergency_action: TokenEmergencyAction, + /// The public note + pub public_note: Option, +} +``` + ### Token Freeze Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L35 +```rs +pub struct TokenFreezeTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// The identity that we are freezing + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "frozenIdentityId") + )] + pub identity_to_freeze_id: Identifier, + /// The public note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "publicNote") + )] + pub public_note: Option, +} +``` + ### Token Mint Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L43 +```rs +pub struct TokenMintTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "issuedToIdentityId") + )] + /// Who should we issue the token to? If this is not set then we issue to the identity set in + /// contract settings. If such an operation is allowed. + pub issued_to_identity_id: Option, + + /// How much should we issue + pub amount: u64, + /// The public note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "publicNote") + )] + pub public_note: Option, +} +``` + ### Token Transfer Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61 +```rs +pub struct TokenTransferTransitionV0 { + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "$amount") + )] + pub amount: u64, + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "recipientId") + )] + pub recipient_id: Identifier, + /// The public note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "publicNote") + )] + pub public_note: Option, + /// An optional shared encrypted note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "sharedEncryptedNote") + )] + pub shared_encrypted_note: Option, + /// An optional private encrypted note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "privateEncryptedNote") + )] + pub private_encrypted_note: Option, +} +``` + ### Token Unfreeze Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35 + +```rs +pub struct TokenUnfreezeTransitionV0 { + /// Document Base Transition + #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] + pub base: TokenBaseTransition, + /// The identity that we are freezing + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "frozenIdentityId") + )] + pub frozen_identity_id: Identifier, + /// The public note + #[cfg_attr( + feature = "state-transition-serde-conversion", + serde(rename = "publicNote") + )] + pub public_note: Option, +} +``` From 6de4e41b8a18c8586474feee33ce974f1b9d70e5 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 18 Mar 2025 10:51:16 -0400 Subject: [PATCH 06/12] docs(ref): add token base transition info --- docs/protocol-ref/token.md | 41 ++++++++++---------------------------- 1 file changed, 10 insertions(+), 31 deletions(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index ae93c2083..a071cbd8a 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -8,38 +8,17 @@ All token transitions include the [token base transition fields](#token-base-tra ### Token Base Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72 +The following fields are included in all token transitions: -```rs -pub struct TokenBaseTransitionV0 { - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "$identity-contract-nonce") - )] - pub identity_contract_nonce: IdentityNonce, - /// ID of the token within the contract - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "$tokenContractPosition") - )] - pub token_contract_position: u16, - /// Data contract ID generated from the data contract's `owner_id` and `entropy` - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "$dataContractId") - )] - pub data_contract_id: Identifier, - /// Token ID generated from the data contract ID and the token position - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "$tokenId") - )] - pub token_id: Identifier, - /// Using group multi party rules for authentication - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub using_group_info: Option, -} -``` +| 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](../protocol-ref/data-contract.md#data-contract-id) 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](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/group/mod.rs#L42-L59) | Varies | Optional field indicating group multi-party authentication rules | + +Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72). ### Token Burn Transition From 489c13e4647ba9c1c046dee5db01c89391665de8 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 18 Mar 2025 11:46:26 -0400 Subject: [PATCH 07/12] docs(ref): add transition actions --- docs/protocol-ref/token.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index a071cbd8a..f1b149944 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -20,6 +20,22 @@ The following fields are included in all token transitions: Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72). +#### Token Transition Action + +The token transition actions [defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transition_action_type.rs#L7-L17) indicate what operation platform should perform with the provided transition data. + +| Action | Name | Description | +| :-: | - | - | +| 0 | [Burn](#token-burn-transition) | Permanently remove a specified amount of tokens from circulation | +| 1 | [Mint](#token-mint-transition) | Create new tokens | +| 2 | [Transfer](#token-transfer-transition) | Send tokens from one identity to another | +| 3 | [Freeze](#token-freeze-transition) | Restrict an identity’s ability to transfer or use tokens | +| 4 | [Unfreeze](#token-unfreeze-transition) | Lift a freeze restriction on an identity's tokens | +| 5 | [Destroy Frozen Funds](#token-destroy-frozen-funds-transition) | Remove frozen tokens from an identity's balance | +| 6 | [Claim](#token-claim-transition) | Retrieve tokens based on a specified distribution method | +| 7 | [Emergency Action](#token-emergency-action-transition) | Execute an emergency protocol affecting tokens | +| 8 | [Config Update](#token-config-update-transition) | Modify the configuration settings of a token | + ### Token Burn Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L38 From 4f0b51b1d116fdb49cfc371e4c418728a3f77cfe Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 18 Mar 2025 15:25:57 -0400 Subject: [PATCH 08/12] docs(ref): update token base, mint, transfer transitions --- docs/protocol-ref/token.md | 120 ++++++++++--------------------------- 1 file changed, 33 insertions(+), 87 deletions(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index f1b149944..969251660 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -38,27 +38,40 @@ The token transition actions [defined in rs-dpp](https://github.com/dashpay/plat ### Token Burn Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L38 +The token burn transition extends the [base transition](#token-base-transition) to include the following additional fields: -```rs -pub struct TokenBurnTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "burnAmount") - )] - /// How much should we burn - pub burn_amount: u64, - /// The public note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "publicNote") - )] - pub public_note: Option, -} -``` +| Field | Type | Size | Description | +| ----- | ---- | ---- | ----------- | +| burnAmount | unsigned integer | 64 bits | Amount of tokens to be burned | +| publicNote | string | Varies | Optional public note | + +Each token burn transition must comply with the [token burn transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L38). + +### Token Mint Transition + +The token mint transition extends the [base transition](#token-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 | Amount of tokens to mint | +| publicNote | string | Varies | Optional public note | + +Each token mint transition must comply with the [token mint transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L43). + +### Token Transfer Transition + +The token transfer transition extends the [base transition](#token-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 | Varies | Optional public note | +| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L15) | Varies | Optional shared encrypted note | +| privateEncryptedNote | [PrivateEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L16-L20) | Varies | Optional private encrypted note | + +Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61). ### Token Claim Transition @@ -148,73 +161,6 @@ pub struct TokenFreezeTransitionV0 { } ``` -### Token Mint Transition - -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L43 - -```rs -pub struct TokenMintTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "issuedToIdentityId") - )] - /// Who should we issue the token to? If this is not set then we issue to the identity set in - /// contract settings. If such an operation is allowed. - pub issued_to_identity_id: Option, - - /// How much should we issue - pub amount: u64, - /// The public note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "publicNote") - )] - pub public_note: Option, -} -``` - -### Token Transfer Transition - -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61 - -```rs -pub struct TokenTransferTransitionV0 { - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "$amount") - )] - pub amount: u64, - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "recipientId") - )] - pub recipient_id: Identifier, - /// The public note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "publicNote") - )] - pub public_note: Option, - /// An optional shared encrypted note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "sharedEncryptedNote") - )] - pub shared_encrypted_note: Option, - /// An optional private encrypted note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "privateEncryptedNote") - )] - pub private_encrypted_note: Option, -} -``` - ### Token Unfreeze Transition https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35 From 2f91ee1336071b28e0385faa8a95b6b547ccc733 Mon Sep 17 00:00:00 2001 From: thephez Date: Tue, 18 Mar 2025 17:00:37 -0400 Subject: [PATCH 09/12] docs(ref): update remaining token transitions --- docs/protocol-ref/token.md | 142 +++++++++++++------------------------ 1 file changed, 48 insertions(+), 94 deletions(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 969251660..e3a57d20b 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -73,114 +73,68 @@ The token transfer transition extends the [base transition](#token-base-transiti Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61). -### Token Claim Transition +### Token Freeze Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L18-L26 +The token freeze transition extends the [base transition](#token-base-transition) to include the following additional fields: -```rs -pub struct TokenClaimTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// The type of distribution we are targeting - pub distribution_type: TokenDistributionType, - /// A public note, this will only get saved to the state if we are using a historical contract - pub public_note: Option, -} -``` +| Field | Type | Size | Description | +| ----- | ---- | ---- | ----------- | +| frozenIdentityId | array | 32 bytes | Identity ID of the account to be frozen | +| publicNote | string | Varies | Optional public note | -### Token Config Update Transition +Each token freeze transition must comply with the [token freeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L35). -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27 +### Token Unfreeze Transition -```rs -pub struct TokenConfigUpdateTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// Updated token configuration item - pub update_token_configuration_item: TokenConfigurationChangeItem, - /// The public note - pub public_note: Option, -} -``` +The token unfreeze transition extends the [base transition](#token-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 | Varies | Optional public note | + +Each token unfreeze transition must comply with the [token unfreeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35). ### Token Destroy Frozen Funds Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25 +The token destroy frozen funds transition extends the [base transition](#token-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 | Varies | Optional public note | -```rs -pub struct TokenDestroyFrozenFundsTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// The identity id of the account whose balance should be destroyed - pub frozen_identity_id: Identifier, - /// The public note - pub public_note: Option, -} -``` +Each token destroy frozen funds transition must comply with the [token destroy frozen funds transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25). + +### Token Claim Transition + +The token claim transition extends the [base transition](#token-base-transition) to include the following additional fields: + +| Field | Type | Size | Description | +| ----- | ---- | ---- | ----------- | +| distributionType | [TokenDistributionType enum](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_distribution_key.rs#L18-L25) | Varies | Type of [token distribution](../explanations/tokens.md#distribution-rules) targeted | +| publicNote | string | Varies | Optional public note (only saved for historical contracts) | + +Each token claim transition must comply with the [token claim transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L18-L26). ### Token Emergency Action Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24 +The token emergency action transition extends the [base transition](#token-base-transition) to include the following additional fields: + +| Field | Type | Size | Description | +| ----- | ---- | ---- | ----------- | +| emergencyAction | [TokenEmergencyAction enum](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/emergency_action.rs#L14-L18) | Varies | The emergency action to be executed | +| publicNote | string | Varies | Optional public note | -```rs -pub struct TokenEmergencyActionTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// The emergency action - pub emergency_action: TokenEmergencyAction, - /// The public note - pub public_note: Option, -} -``` +Each token emergency action transition must comply with the [token emergency action transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24). -### Token Freeze Transition +### Token Config Update Transition -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L35 - -```rs -pub struct TokenFreezeTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// The identity that we are freezing - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "frozenIdentityId") - )] - pub identity_to_freeze_id: Identifier, - /// The public note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "publicNote") - )] - pub public_note: Option, -} -``` +The token config update transition extends the [base transition](#token-base-transition) to include the following additional fields: -### Token Unfreeze Transition +| Field | Type | Size | Description | +| ----- | ---- | ---- | ----------- | +| updateTokenConfigurationItem | [TokenConfigurationChangeItem object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L32-L63) | Varies | Updated token configuration item | +| publicNote | string | Varies | Optional public note | -https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35 - -```rs -pub struct TokenUnfreezeTransitionV0 { - /// Document Base Transition - #[cfg_attr(feature = "state-transition-serde-conversion", serde(flatten))] - pub base: TokenBaseTransition, - /// The identity that we are freezing - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "frozenIdentityId") - )] - pub frozen_identity_id: Identifier, - /// The public note - #[cfg_attr( - feature = "state-transition-serde-conversion", - serde(rename = "publicNote") - )] - pub public_note: Option, -} -``` +Each token configuration update transition must comply with the [token config update transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27). From f4123924443fceb34c80aa3e10efcc004578b7a3 Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 19 Mar 2025 11:53:29 -0400 Subject: [PATCH 10/12] docs(ref): add token id and note info --- docs/protocol-ref/token.md | 47 ++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 14 deletions(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index e3a57d20b..3188d3f95 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -15,11 +15,26 @@ The following fields are included in all token transitions: | $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](../protocol-ref/data-contract.md#data-contract-id) from the data contract's `ownerId` and `entropy` | -| $tokenId | array | 32 bytes | Token ID generated from the data contract ID and the token position | +| [$tokenId](#token-id) | array | 32 bytes | Token ID generated from the data contract ID and the token position | | usingGroupInfo | [GroupStateTransitionInfo object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/group/mod.rs#L42-L59) | Varies | Optional field indicating group multi-party authentication rules | Each token transition must comply with the [token base transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_base_transition/v0/mod.rs#L45-L72). +#### 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](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L22-L27). + +```rust +// 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](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transition_action_type.rs#L7-L17) indicate what operation platform should perform with the provided transition data. @@ -36,14 +51,18 @@ The token transition actions [defined in rs-dpp](https://github.com/dashpay/plat | 7 | [Emergency Action](#token-emergency-action-transition) | Execute an emergency protocol affecting tokens | | 8 | [Config Update](#token-config-update-transition) | 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](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L14). + ### Token Burn Transition The token burn transition extends the [base transition](#token-base-transition) to include the following additional fields: | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | -| burnAmount | unsigned integer | 64 bits | Amount of tokens to be burned | -| publicNote | string | Varies | Optional public note | +| burnAmount | unsigned integer | 64 bits | Number of tokens to be burned | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token burn transition must comply with the [token burn transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_burn_transition/v0/mod.rs#L22-L38). @@ -54,8 +73,8 @@ The token mint transition extends the [base transition](#token-base-transition) | 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 | Amount of tokens to mint | -| publicNote | string | Varies | Optional public note | +| amount | unsigned integer | 64 bits | Number of tokens to mint | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token mint transition must comply with the [token mint transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_mint_transition/v0/mod.rs#L23-L43). @@ -67,9 +86,9 @@ The token transfer transition extends the [base transition](#token-base-transiti | ----- | ---- | ---- | ----------- | | amount | unsigned integer | 64 bits | Number of tokens to transfer | | recipientId | array | 32 bytes | Identity ID of the recipient | -| publicNote | string | Varies | Optional public note | -| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L15) | Varies | Optional shared encrypted note | -| privateEncryptedNote | [PrivateEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L16-L20) | Varies | Optional private encrypted note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | +| sharedEncryptedNote | [SharedEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L15) | [<= 2048 characters](#token-notes) | Optional shared encrypted note | +| privateEncryptedNote | [PrivateEncryptedNote object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/mod.rs#L16-L20) | [<= 2048 characters](#token-notes) | Optional private encrypted note | Each token transfer transition must comply with the [token transfer transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_transfer_transition/v0/mod.rs#L30-L61). @@ -80,7 +99,7 @@ The token freeze transition extends the [base transition](#token-base-transition | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | frozenIdentityId | array | 32 bytes | Identity ID of the account to be frozen | -| publicNote | string | Varies | Optional public note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token freeze transition must comply with the [token freeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_freeze_transition/v0/mod.rs#L19-L35). @@ -91,7 +110,7 @@ The token unfreeze transition extends the [base transition](#token-base-transiti | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | frozenIdentityId | array | 32 bytes | Identity ID of the account to be unfrozen | -| publicNote | string | Varies | Optional public note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token unfreeze transition must comply with the [token unfreeze transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_unfreeze_transition/v0/mod.rs#L19-L35). @@ -102,7 +121,7 @@ The token destroy frozen funds transition extends the [base transition](#token-b | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | frozenIdentityId | array | 32 bytes | Identity ID of the account whose frozen balance should be destroyed | -| publicNote | string | Varies | Optional public note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token destroy frozen funds transition must comply with the [token destroy frozen funds transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_destroy_frozen_funds_transition/v0/mod.rs#L17-L25). @@ -113,7 +132,7 @@ The token claim transition extends the [base transition](#token-base-transition) | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | distributionType | [TokenDistributionType enum](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_distribution_key.rs#L18-L25) | Varies | Type of [token distribution](../explanations/tokens.md#distribution-rules) targeted | -| publicNote | string | Varies | Optional public note (only saved for historical contracts) | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note (only saved for historical contracts) | Each token claim transition must comply with the [token claim transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_claim_transition/v0/mod.rs#L18-L26). @@ -124,7 +143,7 @@ The token emergency action transition extends the [base transition](#token-base- | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | emergencyAction | [TokenEmergencyAction enum](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/tokens/emergency_action.rs#L14-L18) | Varies | The emergency action to be executed | -| publicNote | string | Varies | Optional public note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token emergency action transition must comply with the [token emergency action transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_emergency_action_transition/v0/mod.rs#L16-L24). @@ -135,6 +154,6 @@ The token config update transition extends the [base transition](#token-base-tra | Field | Type | Size | Description | | ----- | ---- | ---- | ----------- | | updateTokenConfigurationItem | [TokenConfigurationChangeItem object](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/data_contract/associated_token/token_configuration_item.rs#L32-L63) | Varies | Updated token configuration item | -| publicNote | string | Varies | Optional public note | +| publicNote | string | [<= 2048 characters](#token-notes) | Optional public note | Each token configuration update transition must comply with the [token config update transition defined in rs-dpp](https://github.com/dashpay/platform/blob/v2.0-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/batched_transition/token_config_update_transition/v0/mod.rs#L19-L27). From 4885b06988db1ed33c0605220427f7974eec6c4e Mon Sep 17 00:00:00 2001 From: thephez Date: Wed, 19 Mar 2025 12:35:14 -0400 Subject: [PATCH 11/12] docs(ref): add initial token overview --- docs/protocol-ref/token.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 3188d3f95..29aaa377e 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -2,6 +2,8 @@ ## Token Overview +Dash Platform lets developers create and manage tokens (similar to ERC-20 style assets) without writing smart contracts. Tokens leverage [data contracts](./data-contract.md), [state transitions](./state-transition.md), and built-in access control (via data contract groups) to enable flexible token management. + ## Token State Transition Details All token transitions include the [token base transition fields](#token-base-transition). Most token transitions (.e.g., [token mint](#token-mint-transition)) require additional fields to provide their functionality. From 523c22bf128fe52046a3ca31e6a313c2b38b52f8 Mon Sep 17 00:00:00 2001 From: thephez Date: Thu, 20 Mar 2025 10:10:19 -0400 Subject: [PATCH 12/12] docs(ref): link to batch st in token overview --- docs/protocol-ref/token.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/protocol-ref/token.md b/docs/protocol-ref/token.md index 29aaa377e..d915de5be 100644 --- a/docs/protocol-ref/token.md +++ b/docs/protocol-ref/token.md @@ -2,7 +2,7 @@ ## Token Overview -Dash Platform lets developers create and manage tokens (similar to ERC-20 style assets) without writing smart contracts. Tokens leverage [data contracts](./data-contract.md), [state transitions](./state-transition.md), and built-in access control (via data contract groups) to enable flexible token management. +Dash Platform lets developers create and manage tokens (similar to ERC-20 style assets) without writing smart contracts. Tokens leverage [data contracts](./data-contract.md), [state transitions](./state-transition.md), 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](./state-transition.md#batch). ## Token State Transition Details