docs(protocol-ref): audit corrections for v3.1 protocol reference

docs/protocol-ref/address-system.md

@@ -5,7 +5,7 @@
 # Platform Address System
 
 :::{attention}
-Address-based state transitions were introduced in **Protocol Version 11**. These transitions enable direct operations using Platform addresses without requiring a pre-existing identity for some operations.
+Address-based state transitions were [enabled in Protocol Version 11](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/feature_initial_protocol_versions.rs). These transitions enable direct operations using Platform addresses without requiring a pre-existing identity for some operations.
 :::
 
 ## Overview
@@ -107,7 +107,7 @@ Transfer credits from an existing identity to one or more Platform addresses.
 | signature            | array of bytes   | 65 bytes | Signature of state transition data                                                            |
 
 :::{note}
-Minimum recipients: 1. Maximum recipients: `max_address_outputs`. Minimum per recipient: 500,000 credits. Minimum fee: 500,000 credits.
+Minimum recipients: 1. Maximum recipients: `max_address_outputs`. Minimum per recipient: 500,000 credits. Fee: 500,000 credits base + 6,000,000 credits per recipient (example: 1 recipient = 6,500,000 credits minimum fee).
 :::
 
 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_to_addresses_transition/).

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

@@ -249,6 +249,7 @@ Distribution rules govern how tokens are created, allocated, and priced within t
 | `newTokensDestinationIdentityRules` | object | Change control rules for destination identity |
 | `mintingAllowChoosingDestination` | boolean | Whether minting operations can specify custom destinations |
 | `mintingAllowChoosingDestinationRules` | object | Change control rules for destination choice |
+| `preProgrammedDistribution` | object | Scheduled token allocations at predetermined timestamps |
 | `changeDirectPurchasePricingRules` | object | Change control rules for direct purchase pricing |
 
 ### Perpetual Distribution
@@ -372,8 +373,8 @@ Emits tokens following a linear function that can increase or decrease over time
   - Parameters
     - `a`: slope numerator (positive = increase, negative = decrease)
     - `d`: slope divisor (enables fractional precision)
-    - `s`: optional start period offset (defaults to contract creation)
-    - `b`: starting emission amount
+    - `s` (`start_step`): optional start period offset (defaults to contract creation)
+    - `b` (`starting_amount`): starting emission amount
     - `min_value` / `max_value`: optional emission bounds
   - Behavior
     - If `a > 0`, emissions increase linearly over time
@@ -401,7 +402,7 @@ A polynomial function using fixed-point arithmetic for fractional or integer exp
   - `a`: coefficient scaling the curve (positive for growth, negative for decay)  
   - `m` and `n`: exponent numerator and denominator, allowing fractional powers (e.g., `m = 1`, `n = 2` → square root)
   - `d`: divisor to scale the result
-  - `s`: optional start period offset
+  - `s` (`start_moment`): optional start period offset
   - `o`: offset inside the exponent input
   - `b`: amount added after the curve is computed
   - `min_value` / `max_value`: optional boundaries to clamp emissions
@@ -448,7 +449,7 @@ Emits tokens following an inverted logarithmic decay curve.
   - `d`: divisor to scale the final result
   - `m` and `n`: Control the logarithmic inversion
   - `o`: offset applied inside the logarithm
-  - `s`: optional start period offset (defaults to contract creation time if not provided)
+  - `s` (`start_moment`): optional start period offset (defaults to contract creation time if not provided)
   - `b`: offset added after scaling
   - `min_value` / `max_value`: optional bounds to constrain emissions
 
@@ -595,6 +596,10 @@ The distribution functions use the following parameters defined across various i
 | `denominator` | integer | - | Reduction factor denominator |
 | `interval` | integer | - | Time interval in milliseconds |
 
+:::{note}
+Parameter sign types vary by function: `a` is unsigned (u64) for `Exponential` but signed (i64) for all other functions. `m` is unsigned (u64) for `Logarithmic` and `InvertedLogarithmic` but signed (i64) for `Polynomial` and `Exponential`.
+:::
+
 ### Distribution Recipients
 
 | Recipient | Description |
@@ -615,7 +620,7 @@ For performance and security reasons, tokens have the following constraints:
 
 | Parameter | Value |
 |-----------|-------|
-| Maximum number of keywords | [20 at creation; 50 on update](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L272-L277) |
+| Maximum number of keywords | [50](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L272-L277) |
 | Keyword length | [3 to 50 characters](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L279-L287) |
 | Description length | [3 to 100 characters](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/methods/validate_update/v0/mod.rs#L312-L323) |
 | Maximum note length | [2048 bytes](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/tokens/mod.rs#L19) |
@@ -732,6 +737,19 @@ This example shows the complete structure of a token definition with all major c
           }
         }
       },
+      "marketplaceRules": {
+        "$format_version": "0",
+        "tradeMode": "NotTradeable",
+        "tradeModeChangeRules": {
+          "V0": {
+            "authorized_to_make_change": "NoOne",
+            "admin_action_takers": "NoOne",
+            "changing_authorized_action_takers_to_no_one_allowed": false,
+            "changing_admin_action_takers_to_no_one_allowed": false,
+            "self_changing_admin_action_takers_allowed": false
+          }
+        }
+      },
       "manualMintingRules": {
         "V0": {
           "authorized_to_make_change": "ContractOwner",

docs/protocol-ref/data-contract.md

@@ -80,7 +80,7 @@ The data contract object consists of the following fields as defined in the Rust
 | $defs           | object         | Varies       | (Optional) Definitions for `$ref` references used in the `documents` object (if present, must be a non-empty object with \<= 100 valid properties) |
 | [groups](#data-contract-groups) | Group | Varies | (Optional) Groups that allow for specific multiparty actions on the contract. |
 | [tokens](./data-contract-token.md) | object         | Varies    | (Optional \*) Token definitions (see [Contract Tokens](./data-contract-token.md) for details) |
-| keywords | array of strings | Varies | (Optional) Keywords associated with the contract to improve searchability. Maximum of 20 keywords at creation; contract updates allow up to 50. |
+| keywords | array of strings | Varies | (Optional) Keywords associated with the contract to improve searchability. Maximum of 50 keywords. |
 | description | string | 3-100 characters | (Optional) Brief description of the contract. |
 | createdAt | unsigned integer | 64 bits | (Read-only) Timestamp in milliseconds when the contract was created. Set by platform. |
 | updatedAt | unsigned integer | 64 bits | (Read-only) Timestamp in milliseconds when the contract was last updated. Set by platform. |
@@ -797,8 +797,9 @@ Groups can be used to distribute contract configuration and update authorization
 
 | Constant | Value | Description |
 |----------|-------|-------------|
+| Minimum group size | [2](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L107-L110) | Minimum members per group |
 | `max_contract_group_size` | 256 | Maximum members per group |
-| Maximum member power | 65,535 (u32; cap enforced at u16::MAX) | Maximum voting power per member |
+| Maximum member power | 65,535 (u32; cap enforced at u16::MAX) | Maximum voting power per member. Each member's power must also not exceed the group's [`requiredPower`](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/data_contract/group/v0/mod.rs#L129-L134) value. |
 | Maximum required power | 65,535 (u32; cap enforced at u16::MAX) | Maximum threshold power |
 
 #### Group Action Info
@@ -807,9 +808,9 @@ When submitting a group-authorized action, the transition includes:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `groupContractPosition` | u16 | Position of the group in the contract |
-| `actionId` | Identifier (32 bytes) | The action identifier |
-| `actionIsProposer` | bool | Whether the signer is the action proposer |
+| `$groupContractPosition` | u16 | Position of the group in the contract |
+| `$groupActionId` | Identifier (32 bytes) | The action identifier |
+| `$groupActionIsProposer` | bool | Whether the signer is the action proposer |
 
 #### Use Cases
 
@@ -857,7 +858,7 @@ Data contracts are created on the platform by submitting the [data contract obje
 
 | Field           | Type           | Size | Description |
 | --------------- | -------------- | ---- | ----------- |
-| $version        | unsigned integer | 32 bits | The state transition format version (currently `0`) |
+| $version        | unsigned integer | 16 bits | The state transition format version (currently `0`) |
 | type            | unsigned integer | 8 bits  | State transition type (`0` for data contract create)  |
 | dataContract    | [data contract object](#data-contract-object) | Varies | Object containing the data contract details |
 | identityNonce   | unsigned integer | 64 bits | Identity nonce for this transition to prevent replay attacks |
@@ -881,7 +882,7 @@ object](#data-contract-object) in a data contract update state transition consis
 
 | Field           | Type           | Size | Description |
 | --------------- | -------------- | ---- | ----------- |
-| $version        | unsigned integer | 32 bits | The state transition format version (currently `0`) |
+| $version        | unsigned integer | 16 bits | The state transition format version (currently `0`) |
 | type            | unsigned integer | 8 bits  | State transition type (`4` for data contract update)  |
 | dataContract    | [data contract object](#data-contract-object) | Varies | Object containing the updated data contract details<br>**Note:** the data contract's [`version` property](#data-contract-version) must be incremented with each update |
 | identityContractNonce | unsigned integer | 64 bits | Identity contract nonce for replay protection |

docs/protocol-ref/data-trigger.md

@@ -34,12 +34,12 @@ As an example, DPP contains several data triggers for DPNS as defined in the [da
 
 The following table details the DPNS constraints applied via data triggers. These constraints are in addition to the ones applied directly by the DPNS data contract.
 
-| Document   | Action    | Constraint                                                                                                  |
-| ---------- | --------- | ----------------------------------------------------------------------------------------------------------- |
+| Document   | Action    | Constraint |
+| ---------- | --------- | ---------- |
 | `domain`   | `CREATE`  | Full domain length \<= 253 characters                                                                       |
 | `domain`   | `CREATE`  | `normalizedLabel` matches homograph-safe conversion of `label` (lowercase with character substitutions: o→0, l/i→1) |
 | `domain`   | `CREATE`  | `normalizedParentDomainName` matches homograph-safe conversion of `parentDomainName` |
-| `domain`   | `CREATE`  | `ownerId` matches `records.dashUniqueIdentityId` or `dashAliasIdentityId` (whichever one is present)        |
+| `domain`   | `CREATE`  | `ownerId` validation against `records` identity fields is a no-op (see note below) |
 | `domain`   | `CREATE`  | Only creating a top-level domain with an authorized identity                                                |
 | `domain`   | `CREATE`  | Referenced `normalizedParentDomainName` must be an existing parent domain                                   |
 | `domain`   | `CREATE`  | Subdomain registration for non-top-level domains prevented if the new domain's `subdomainRules.allowSubdomains` is true |
@@ -51,6 +51,15 @@ The following table details the DPNS constraints applied via data triggers. Thes
 | `domain`   | `PURCHASE`     | Action not allowed                                                                                          |
 | `domain`   | `UPDATE_PRICE` | Action not allowed                                                                                          |
 
+:::{note}
+The trigger for `domain` `CREATE` attempts to validate that `ownerId` matches
+`records.dashUniqueIdentityId` or `records.dashAliasIdentityId`. However, the
+DPNS v1 schema defines only `records.identity` and sets `additionalProperties:
+false`, so neither field can exist in a valid document. Both checks are
+therefore permanent no-ops and `records.identity` is not validated against
+`ownerId` at the trigger level.
+:::
+
 ### Other System Contract Triggers
 
 In addition to DPNS, the following system contracts have registered data triggers:

docs/protocol-ref/identity.md

@@ -64,13 +64,13 @@ Each item in the `publicKeys` array consists of an object containing:
 | Field         | Type           | Description |
 | ------------- | -------------- | ----------- |
 | [id](#public-key-id) | integer        | The key id (all public keys must be unique) |
-| [type](#public-key-type) | integer        | Type of key (default: `0` - ECDSA) |
-| [data](#public-key-data)          | array of bytes | Public key (`0` - ECDSA: 33 bytes, `1` - BLS: 48 bytes, `2` - ECDSA Hash160: 20 bytes, `3` - [BIP13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) Hash160: 20 bytes, `4` - EDDSA_25519_HASH160: 20 bytes) |
 | [purpose](#public-key-purpose) | integer        | Public key purpose (`0` - Authentication, `1` - Encryption, `2` - Decryption, `3` - Transfer) |
 | [securityLevel](#public-key-securitylevel) | integer        | Public key security level (`0` - Master, `1` - Critical, `2` - High, `3` - Medium) |
-| [readonly](#public-key-readonly) | boolean        | Identity public key can't be modified with `readOnly` set to `true`. This can’t be changed after adding a key. |
-| [disabledAt](#public-key-disabledat) | integer        | Timestamp indicating that the key was disabled at a specified time |
 | contractBounds | object (optional) | Restricts this key to a specific data contract or document type context |
+| [type](#public-key-type) | integer        | Type of key (default: `0` - ECDSA) |
+| [readonly](#public-key-readonly) | boolean        | Identity public key can’t be modified with `readOnly` set to `true`. This can’t be changed after adding a key. |
+| [data](#public-key-data)          | array of bytes | Public key (`0` - ECDSA: 33 bytes, `1` - BLS: 48 bytes, `2` - ECDSA Hash160: 20 bytes, `3` - [BIP13](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki) Hash160: 20 bytes, `4` - EDDSA_25519_HASH160: 20 bytes) |
+| [disabledAt](#public-key-disabledat) | integer        | Timestamp indicating that the key was disabled at a specified time |
 | signature     | array of bytes | Signature of the signable identity create or topup state transition by the private key associated with this public key |
 
 See the [public key implementation in rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/identity/identity_public_key/v0/mod.rs#L42-L53) for more details.

docs/protocol-ref/protocol-constants.md

@@ -262,9 +262,9 @@ These limits apply to token perpetual distribution function parameters.
 
 | Limit | Value | Description | Source |
 |-------|-------|-------------|--------|
-| Min output amount | 500,000 credits | Minimum output per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L39) |
-| Min input amount | 100,000 credits | Minimum input per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L40) |
-| Max fee strategies | 4 | Maximum fee strategy steps | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v1.rs#L45) |
+| Min output amount | 500,000 credits | Minimum output per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L39) |
+| Min input amount | 100,000 credits | Minimum input per address | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L40) |
+| Max fee strategies | 4 | Maximum fee strategy steps | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L45) |
 | Max address inputs | 16 | Maximum input addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L43) |
 | Max address outputs | 128 | Maximum output addresses per address-based transition | [rs-platform-version](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-platform-version/src/version/dpp_versions/dpp_state_transition_versions/v3.rs#L44) |
 
@@ -288,5 +288,5 @@ These limits apply to token perpetual distribution function parameters.
 
 | Constant | Value | Description | Source |
 |----------|-------|-------------|--------|
-| Min withdrawal amount | ~181,000 credits | Based on unlock tx size | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L44-L45) |
+| Min withdrawal amount | 190,000 credits | ASSET_UNLOCK_TX_SIZE (190) × MIN_CORE_FEE_PER_BYTE (1) × CREDITS_PER_DUFF (1,000) | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L44-L45) |
 | Min core fee per byte | 1 | Must be Fibonacci number | [rs-dpp](https://github.com/dashpay/platform/blob/v3.1-dev/packages/rs-dpp/src/state_transition/state_transitions/identity/identity_credit_withdrawal_transition/mod.rs#L41) |