Skip to content

docs: v3.1 release cleanup (state-transition dedup, deprecated DAPI removal, build-warning fixes) #151

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thephez merged 4 commits into from
May 28, 2026
Merged

docs: v3.1 release cleanup (state-transition dedup, deprecated DAPI removal, build-warning fixes) #151

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3b95d1a
docs(protocol-ref): dedup state transition page and drop deprecated D…
thephez May 27, 2026
3ef4a6a
docs: minor formatting update
thephez May 28, 2026
82eab0e
docs: fix broken cross-references to clean up build warnings
thephez May 28, 2026
e5ae753
docs: silence Pygments warnings on placeholder JSON blocks
thephez May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 8 additions & 4 deletions docs/protocol-ref/data-contract-document.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,9 @@ The `indices` array consists of one or more objects that each contain:
* An optional `nullSearchable` element that indicates whether the index allows searching for NULL values. If nullSearchable is false (default: true) and all properties of the index are null then no reference is added.
* An optional `contested` element that determines if duplicate values are allowed for the document

```json
:::{code-block} json
:force:

"indices": [
{
"name": "<index name a>",
Expand All @@ -171,7 +173,7 @@ The `indices` array consists of one or more objects that each contain:
],
}
]
```
:::

### Contested Indices

Expand Down Expand Up @@ -380,7 +382,9 @@ schema](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/schema

This example syntax shows the structure of a documents object that defines two documents, an index, and a required field.

```json
:::{code-block} json
:force:

{
"<document name a>": {
"type": "object",
Expand Down Expand Up @@ -425,7 +429,7 @@ This example syntax shows the structure of a documents object that defines two d
"additionalProperties": false
},
}
```
:::

## Document Schema

Expand Down
97 changes: 26 additions & 71 deletions docs/protocol-ref/state-transition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The list of common fields used by multiple state transitions is defined in [rs-d
| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| $version | unsigned integer | 16 bits | The state transition format version (FeatureVersion). Currently `0` for most transitions, `1` for Batch. This is not the global platform protocol version, which is negotiated separately. |
| type | unsigned integer | 8 bits | State transition type (defined in [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21)):<br>`0` - [data contract create](../protocol-ref/data-contract.md#data-contract-create)<br>`1` - [batch](#batch)<br>`2` - [identity create](../protocol-ref/identity.md#identity-create)<br>`3` - [identity topup](identity.md#identity-topup)<br>`4` - [data contract update](data-contract.md#data-contract-update)<br>`5` - [identity update](identity.md#identity-update)<br>`6` - [identity credit withdrawal](identity.md#identity-credit-withdrawal)<br>`7` - [identity credit transfer](identity.md#identity-credit-transfer)<br>`8` - [masternode vote](#masternode-vote)<br>`9` - [identity credit transfer to addresses](address-system.md#identity-credit-transfer-to-addresses)<br>`10` - [identity create from addresses](address-system.md#identity-create-from-addresses)<br>`11` - [identity topup from addresses](address-system.md#identity-topup-from-addresses)<br>`12` - [address funds transfer](address-system.md#address-funds-transfer)<br>`13` - [address funding from asset lock](address-system.md#address-funding-from-asset-lock)<br>`14` - [address credit withdrawal](address-system.md#address-credit-withdrawal)<br>`15` - [shield](shielded-pool.md#shield)<br>`16` - [shielded transfer](shielded-pool.md#shielded-transfer)<br>`17` - [unshield](shielded-pool.md#unshield)<br>`18` - [shield from asset lock](shielded-pool.md#shield-from-asset-lock)<br>`19` - [shielded withdrawal](shielded-pool.md#shielded-withdrawal) |
| type | unsigned integer | 8 bits | State transition type discriminator (defined in [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21)). See [State Transition Types](#state-transition-types) for the full list. |
| userFeeIncrease | unsigned integer | 16 bits | Extra fee to prioritize processing if the mempool is full. Typically set to zero. |
| signature | array of bytes | 65 bytes |Signature of state transition data |

Expand All @@ -42,85 +42,40 @@ Additionally, all state transitions except the identity create and topup state t

## State Transition Types

Dash Platform Protocol defines the [state transition types](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21-L43) that perform identity, contract, document, and token operations. See the subsections below for details on each state transition type.
Dash Platform Protocol defines the following [state transition types](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transition_types.rs#L21-L43). Most are documented in detail on the protocol reference page for the feature they operate on. Batch and Masternode Vote do not have a dedicated feature page; their formats are documented inline below.

| Type | Name | Documented in |
| --- | --- | --- |
| 0 | Data Contract Create | [Data Contract Create](data-contract.md#data-contract-create) |
| 1 | Batch | [Batch](#batch) (below) |
| 2 | Identity Create | [Identity Create](identity.md#identity-create) |
| 3 | Identity TopUp | [Identity TopUp](identity.md#identity-topup) |
| 4 | Data Contract Update | [Data Contract Update](data-contract.md#data-contract-update) |
| 5 | Identity Update | [Identity Update](identity.md#identity-update) |
| 6 | Identity Credit Withdrawal | [Identity Credit Withdrawal](identity.md#identity-credit-withdrawal) |
| 7 | Identity Credit Transfer | [Identity Credit Transfer](identity.md#identity-credit-transfer) |
| 8 | Masternode Vote | [Masternode Vote](#masternode-vote) (below) |
| 9 | Identity Credit Transfer to Addresses | [Identity Credit Transfer to Addresses](address-system.md#identity-credit-transfer-to-addresses) |
| 10 | Identity Create from Addresses | [Identity Create from Addresses](address-system.md#identity-create-from-addresses) |
| 11 | Identity TopUp from Addresses | [Identity TopUp from Addresses](address-system.md#identity-top-up-from-addresses) |
| 12 | Address Funds Transfer | [Address Funds Transfer](address-system.md#address-funds-transfer) |
| 13 | Address Funding from Asset Lock | [Address Funding from Asset Lock](address-system.md#address-funding-from-asset-lock) |
| 14 | Address Credit Withdrawal | [Address Credit Withdrawal](address-system.md#address-credit-withdrawal) |
| 15 | Shield | [Shield](shielded-pool.md#shield) |
| 16 | Shielded Transfer | [Shielded Transfer](shielded-pool.md#shielded-transfer) |
| 17 | Unshield | [Unshield](shielded-pool.md#unshield) |
| 18 | Shield from Asset Lock | [Shield from Asset Lock](shielded-pool.md#shield-from-asset-lock) |
| 19 | Shielded Withdrawal | [Shielded Withdrawal](shielded-pool.md#shielded-withdrawal) |

### Batch

| Field | Type | Size | Description |
| ----------- | -------------- | ---- | ----------- |
| ownerId | array of bytes | 32 bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) |
| ownerId | array of bytes | 32 bytes | [Identity](../protocol-ref/identity.md) submitting the document(s) or token action(s) |
| transitions | array of transition objects | Varies | A batch of [document](../protocol-ref/document.md#document-overview) or token actions (currently limited to [1 object per batch](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/system_limits/v1.rs#L7)) |

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/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/document/batch_transition/v1/mod.rs#L31-L39).

### Data Contract Create

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| dataContract | [data contract object](../protocol-ref/data-contract.md#data-contract-object) | Varies | Object containing valid [data contract](../protocol-ref/data-contract.md) details |
| identityNonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks |

More detailed information about the `dataContract` object can be found in the [data contract section](../protocol-ref/data-contract.md).

### Data Contract Update

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| dataContract | [data contract object](../protocol-ref/data-contract.md#data-contract-object) | Varies | Object containing valid [data contract](../protocol-ref/data-contract.md) details |
| identityContractNonce | unsigned integer | 64 bits | Identity contract nonce for replay protection |

More detailed information about the `dataContract` object can be found in the [data contract section](../protocol-ref/data-contract.md).

### Identity Create

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| assetLockProof | array of bytes | 36 bytes | Lock [outpoint](https://docs.dash.org/en/stable/docs/core/resources/glossary.html#outpoint) from the layer 1 locking transaction (36 bytes) |
| publicKeys | array of keys | Varies | [Public key(s)](../protocol-ref/identity.md#identity-publickeys) associated with the identity (maximum number of keys: `6`) |

More detailed information about the `publicKeys` object can be found in the [identity section](../protocol-ref/identity.md).

### Identity TopUp

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| assetLockProof | array of bytes | 36 bytes | Lock [outpoint](https://docs.dash.org/en/stable/docs/core/resources/glossary.html#outpoint) from the layer 1 locking transaction (36 bytes) |
| identityId | array of bytes | 32 bytes | An [Identity ID](../protocol-ref/identity.md#identity-id) for the identity receiving the topup (can be any identity) (32 bytes) |

### Identity Update

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| identityId | array of bytes | 32 bytes | The [Identity ID](../protocol-ref/identity.md#identity-id) for the identity being updated |
| revision | unsigned integer | 64 bits | Identity update revision. Used for optimistic concurrency control. Incremented by one with each new update so that the update will fail if the underlying data is modified between reading and writing. |
| nonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks |
| addPublicKeys | array of public keys | Varies | (Optional) Array of up to 6 new public keys to add to the identity. Required if adding keys. |
| disablePublicKeys | array of integers | Varies | (Optional) Array of up to 10 existing identity public key ID(s) to disable for the identity. Required if disabling keys. |

### Identity Credit Transfer

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| identityId | array of bytes | 32 bytes | An [Identity ID](../protocol-ref/identity.md#identity-id) for the identity sending the credits |
| recipientId | array of bytes | 32 bytes | An [Identity ID](../protocol-ref/identity.md#identity-id) for the identity receiving the credits |
| amount | unsigned integer | 64 bits | Number of credits being transferred |
| nonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks |

See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_transfer_transition/v0/mod.rs#L42-L53).

### Identity Credit Withdrawal

| Field | Type | Size | Description |
| --------------- | -------------- | ---- | ----------- |
| identityId | array of bytes | 32 bytes | An [Identity ID](../protocol-ref/identity.md#identity-id) for the identity sending the credits |
| amount | unsigned integer | 64 bits | Number of credits being transferred |
| coreFeePerByte | unsigned integer | 32 bits | |
| pooling | unsigned integer | 8 bits | 0 = Never, 1 = If Available, 2 = Standard |
| outputScript | script | Varies | If None, the withdrawal is sent to the address set by Core |
| nonce | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks |

See the implementation in [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/v1/mod.rs#L35-L48).

### Masternode Vote

| Field | Type | Size | Description |
Expand Down
33 changes: 0 additions & 33 deletions docs/reference/dapi-endpoints-platform-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4627,39 +4627,6 @@ Returns compacted nullifier additions from a specified block height. Compacted c
| `start_block_height` | String (uint64) | Yes | Block height to start from (as a string due to uint64 size) |
| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested changes |

## Deprecated Endpoints

The following endpoints were recently deprecated. See the [previous version of documentation](https://docs.dash.org/projects/platform/en/2.0.0/docs/reference/dapi-endpoints-platform-endpoints.html) for additional information on these endpoints.

### getIdentities

:::{attention}
Deprecated in Dash Platform v1.0.0
:::

**Returns**: [Identity](../explanations/identity.md) information for the requested identities

**Parameters**:

| Name | Type | Required | Description |
| ------- | ------- | -------- | ------------ |
| `ids` | Array | Yes | An array of identity IDs
| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identity

### getIdentitiesByPublicKeyHashes

:::{attention}
Deprecated in Dash Platform v1.0.0
:::

**Returns**: An array of [identities](../explanations/identity.md) associated with the provided public key hashes
**Parameters**:

| Name | Type | Required | Description |
| ------------------- | ------- | -------- | ----------------------------------------------------------------------- |
| `public_key_hashes` | Bytes | Yes | Public key hashes (sha256-ripemd160) of identity public keys |
| `prove` | Boolean | No | Set to `true` to receive a proof that contains the requested identities |

## Code Reference

Implementation details related to the information on this page can be found in:
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/dapi-endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ without introducing issues for endpoint consumers.
| [`getIdentity`](../reference/dapi-endpoints-platform-endpoints.md#getidentity) | Returns the requested identity |
| [`getIdentityBalance`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalance) | Returns the requested identity's balance |
| [`getIdentityBalanceAndRevision`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybalanceandrevision) | Returns the requested identity's balance and revision |
| [`getIdentityByNonUniquePublicKeyHash`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybynonuniquepublickeyhash) | **Added in Dash Platform v2.0.0**<br>Returns one or more identities associated with a public key hash, including for non-unique masternode keys. |
| [`getIdentityByNonUniquePublicKeyHash`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybynonuniquepublickeyhash) | *Added in Dash Platform v2.0.0*<br>Returns one or more identities associated with a public key hash, including for non-unique masternode keys. |
| [`getIdentityByPublicKeyHash`](../reference/dapi-endpoints-platform-endpoints.md#getidentitybypublickeyhash) | Returns the identity associated with the provided public key hash |
| [`getIdentityContractNonce`](../reference/dapi-endpoints-platform-endpoints.md#getidentitycontractnonce) | Returns the identity contract nonce |
| [`getIdentityKeys`](../reference/dapi-endpoints-platform-endpoints.md#getidentitykeys) | Returns the requested identity keys |
Expand Down Expand Up @@ -80,7 +80,7 @@ Security groups provide a way to distribute token configuration and update autho
| [`getEvonodesProposedEpochBlocksByIds`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyids) | *Added in Dash Platform v1.3.0*<br>Retrieves the number of blocks proposed by the specified evonodes in a certain epoch, based on their IDs |
| [`getEvonodesProposedEpochBlocksByRange`](../reference/dapi-endpoints-platform-endpoints.md#getevonodesproposedepochblocksbyrange) | *Added in Dash Platform v1.3.0*<br>Retrieves the number of blocks proposed by evonodes for a specified epoch |
| [`getEpochsInfo`](../reference/dapi-endpoints-platform-endpoints.md#getepochsinfo) | Returns information about the requested epoch(s) |
| [`getFinalizedEpochInfos`](../reference/dapi-endpoints-platform-endpoints.md#getfinalizedepochinfos) | **Added in Dash Platform v2.0.0**<br>Retrieves finalized epoch information within a specified index range |
| [`getFinalizedEpochInfos`](../reference/dapi-endpoints-platform-endpoints.md#getfinalizedepochinfos) | *Added in Dash Platform v2.0.0*<br>Retrieves finalized epoch information within a specified index range |
| [`getPathElements`](../reference/dapi-endpoints-platform-endpoints.md#getpathelements) | *Added in Dash Platform v1.0.0*<br>Returns elements for a specified path in the Platform |
| [`getPrefundedSpecializedBalance`](../reference/dapi-endpoints-platform-endpoints.md#getprefundedspecializedbalance) | *Added in Dash Platform v1.0.0*<br>Returns the pre-funded specialized balance for a specific identity |
| [`getProtocolVersionUpgradeState`](../reference/dapi-endpoints-platform-endpoints.md#getprotocolversionupgradestate) | Returns the number of votes cast for each protocol version |
Expand Down
22 changes: 13 additions & 9 deletions docs/reference/data-contracts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,14 +249,16 @@ The `indices` array consists of one or more objects that each contain:
* An optional `nullSearchable` element that indicates whether the index allows searching for NULL values. If nullSearchable is false (default: true) and all properties of the index are null then no reference is added.
* An optional `contested` element that determines if duplicate values are allowed for the document

```json
"indices": [
:::{code-block} json
:force:

"indices": [
{
"name": "<index name a>",
"properties": [
{ "<field name a>": "<asc"|"desc>" },
{ "<field name b>": "<asc"|"desc>" }
],
],
"unique": true|false,
"nullSearchable": true|false,
"contested": {
Expand All @@ -273,10 +275,10 @@ The `indices` array consists of one or more objects that each contain:
"name": "<index name b>",
"properties": [
{ "<field name c>": "<asc"|"desc>" },
],
}
],
}
]
```
:::

#### Contested indices

Expand Down Expand Up @@ -343,10 +345,12 @@ The following example (excerpt from the DPNS contract's `preorder` document) cre

This example syntax shows the structure of a document object including all optional properties.

:::{dropdown} Document schema
::::{dropdown} Document schema
:open:

```json
:::{code-block} json
:force:

{
"<document name a>": {
"documentsKeepHistory": true|false,
Expand Down Expand Up @@ -411,8 +415,8 @@ This example syntax shows the structure of a document object including all optio
"additionalProperties": false
},
}
```
:::
::::

## General Constraints

Expand Down
Loading
Loading