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

* docs(protocol-ref): dedup state transition page and drop deprecated DAPI entries

Replace the cramped one-cell type discriminator with a proper catalog table,
remove the 7 type-0–8 detail sections that duplicate the canonical identity
and data-contract pages, and drop the long-deprecated getIdentities and
getIdentitiesByPublicKeyHashes endpoints (removed from the platform proto in
v1.0.0).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: minor formatting update

* docs: fix broken cross-references to clean up build warnings

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: silence Pygments warnings on placeholder JSON blocks

Convert affected fences to code-block directives with :force: so JSON
highlighting is preserved without lexer errors on schema-style
placeholders and JS-literal query examples.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: thephez

docs/protocol-ref/data-contract-document.md

@@ -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>",
@@ -171,7 +173,7 @@ The `indices` array consists of one or more objects that each contain:
     ],
   }
 ]
-```
+:::
 
 ### Contested Indices
 
@@ -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",
@@ -425,7 +429,7 @@ This example syntax shows the structure of a documents object that defines two d
     "additionalProperties": false
   },    
 }
-```
+:::
 
 ## Document Schema
 

docs/protocol-ref/state-transition.md

@@ -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 |
 
@@ -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 |

docs/reference/dapi-endpoints-platform-endpoints.md

@@ -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:

docs/reference/dapi-endpoints.md

@@ -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 |
@@ -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 |

docs/reference/data-contracts.md

@@ -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": {
@@ -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
 
@@ -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,
@@ -411,8 +415,8 @@ This example syntax shows the structure of a document object including all optio
     "additionalProperties": false
   },  
 }
-```
 :::
+::::
 
 ## General Constraints