From 4c0c411742b7f58b34b13f3484caa248506063b0 Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 27 Sep 2026 18:50:02 +0700 Subject: [PATCH 1/2] docs(platform): document the genesis protocol version exception and Swift/Kotlin indentation The book named a protocol_version comparison inside a generation as the thing that needs a new generation, and described the upgrade ladder and the is_allowed gate as the places that compare on purpose, but not create_genesis_state v1, which adds genesis content behind protocol_version >= N by design: only chains born at 9 or later run it, and all of them are re-created per release. Describe it in the Versioned Dispatch chapter and point to the three exceptions from the coding conventions. .editorconfig gave Swift and Kotlin the 2-space default while all Kotlin files and nearly all Swift files use 4 spaces; add their section, and say so in AGENTS.md. Co-Authored-By: Claude Opus 5.5 --- .editorconfig | 4 ++++ AGENTS.md | 3 ++- book/src/contributing/coding-conventions.md | 6 +++++- book/src/versioning/versioned-dispatch.md | 14 ++++++++++++++ 4 files changed, 25 insertions(+), 2 deletions(-) diff --git a/.editorconfig b/.editorconfig index 2e9dc07ba04..35057547424 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,6 +11,10 @@ end_of_line = lf [*.rs] indent_size = 4 +# Swift and Kotlin follow their languages' 4-space convention. +[*.{swift,kt,kts}] +indent_size = 4 + # Preserve the existing indentation of the Swift SDK Python scripts. [packages/swift-sdk/scripts/*.py] indent_size = 4 diff --git a/AGENTS.md b/AGENTS.md index 316d53322ad..26ede667802 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,7 +78,8 @@ Platform uses data contracts to define application data schemas: - Run linters: `yarn lint` ## Coding Style & Naming Conventions -- Follow `.editorconfig`: 2-space indent by default; 4 spaces for `*.rs` and +- Follow `.editorconfig`: 2-space indent by default; 4 spaces for `*.rs`, + Swift and Kotlin (`*.swift`, `*.kt`, `*.kts`), and `packages/swift-sdk/scripts/*.py`, preserving the existing Python script style. Use LF, UTF‑8, and a final newline. - JS/TS: ESLint (Airbnb/TypeScript rules via package configs). Use camelCase for variables/functions, PascalCase for classes; prefer kebab-case filenames within JS packages. diff --git a/book/src/contributing/coding-conventions.md b/book/src/contributing/coding-conventions.md index 47bbb0f4f9f..9aabbb35d94 100644 --- a/book/src/contributing/coding-conventions.md +++ b/book/src/contributing/coding-conventions.md @@ -84,7 +84,11 @@ dpp method whose own gate is `None` there), or the edit is a pure refactor with identical output. "Probably inert" is not enough. If the argument takes more than a sentence, or rests on a runtime check inside the shipped module, add a generation instead. Inside a new generation the capability is a constant fact -(`Index::try_from_value_map(map, true)`), not a runtime check. +(`Index::try_from_value_map(map, true)`), not a runtime check. The places that +compare `protocol_version` on purpose are the protocol upgrade ladder, the +`is_allowed` gate for new transition kinds, and genesis content in +`create_genesis_state` v1; the [Versioned +Dispatch](../versioning/versioned-dispatch.md) chapter describes all three. Why: replay safety is structural when a shipped file stays byte-identical, and becomes a proof the reviewer has to check the moment it does not. An in-place diff --git a/book/src/versioning/versioned-dispatch.md b/book/src/versioning/versioned-dispatch.md index ba303a9a835..10e0dc19d81 100644 --- a/book/src/versioning/versioned-dispatch.md +++ b/book/src/versioning/versioned-dispatch.md @@ -687,6 +687,20 @@ stage of the validation pipeline reading the constants in its initial version is rejected with a `StateTransitionNotActiveError` rather than an unknown-version dispatch error. +Genesis content is the other place a `protocol_version` comparison is the +intended shape. `create_genesis_state` runs once per chain, under the protocol +version the chain is born at. Mainnet and testnet were born at protocol +version 1 and replay generation 0, which stays frozen. Generation 1 is selected +only for chains born at protocol version 9 or later, and every such chain is a +devnet, a local network or a test suite that is created again for each +release, so no live node reproduces its genesis. When a protocol version adds +a system contract or other genesis content, it goes into +`create_genesis_state_v1` behind `if platform_version.protocol_version >= N` +(document history at 13, app connect and moderation charters at 14), and a +chain that already exists gets the same content from its +`transition_to_version_N` rung. A new genesis generation would add code for no +replay benefit. Never edit generation 0. + ## Rules **Do:** From cfbee48f6d42f28bd83e25cd2c746766fe3449de Mon Sep 17 00:00:00 2001 From: Quantum Explorer Date: Sun, 27 Sep 2026 22:04:47 +0700 Subject: [PATCH 2/2] docs(platform): say the protocol_version patterns list is for new changes Review follow-up: the list read as exhaustive. Name it as the patterns for new changes, include the Drive helpers that build the initial state structure (add_initial_withdrawal_state_structure_operations gates on 4 and 14 at chain creation), and say that older comparisons such as the pre-version-9 arithmetic in DocumentPropertyType stay for replay but are not a pattern to copy. Co-Authored-By: Claude Opus 5.5 --- book/src/contributing/coding-conventions.md | 14 +++++++++----- book/src/versioning/versioned-dispatch.md | 7 +++++++ 2 files changed, 16 insertions(+), 5 deletions(-) diff --git a/book/src/contributing/coding-conventions.md b/book/src/contributing/coding-conventions.md index 9aabbb35d94..ee0556e0325 100644 --- a/book/src/contributing/coding-conventions.md +++ b/book/src/contributing/coding-conventions.md @@ -84,11 +84,15 @@ dpp method whose own gate is `None` there), or the edit is a pure refactor with identical output. "Probably inert" is not enough. If the argument takes more than a sentence, or rests on a runtime check inside the shipped module, add a generation instead. Inside a new generation the capability is a constant fact -(`Index::try_from_value_map(map, true)`), not a runtime check. The places that -compare `protocol_version` on purpose are the protocol upgrade ladder, the -`is_allowed` gate for new transition kinds, and genesis content in -`create_genesis_state` v1; the [Versioned -Dispatch](../versioning/versioned-dispatch.md) chapter describes all three. +(`Index::try_from_value_map(map, true)`), not a runtime check. For new +changes, the patterns that compare `protocol_version` on purpose are the +protocol upgrade ladder, the `is_allowed` gate for new transition kinds, and +chain-creation content (`create_genesis_state` v1 and the Drive helpers that +build the initial state structure); the [Versioned +Dispatch](../versioning/versioned-dispatch.md) chapter describes them. Older +comparisons elsewhere (for example the pre-version-9 arithmetic in +`DocumentPropertyType`) stay because history replays through them; they are not +a pattern to copy. Why: replay safety is structural when a shipped file stays byte-identical, and becomes a proof the reviewer has to check the moment it does not. An in-place diff --git a/book/src/versioning/versioned-dispatch.md b/book/src/versioning/versioned-dispatch.md index 10e0dc19d81..7a59a994be1 100644 --- a/book/src/versioning/versioned-dispatch.md +++ b/book/src/versioning/versioned-dispatch.md @@ -701,6 +701,13 @@ chain that already exists gets the same content from its `transition_to_version_N` rung. A new genesis generation would add code for no replay benefit. Never edit generation 0. +The Drive helpers that build the initial state structure follow the same rule +for the same reason: they run once, at chain creation, under the chain's +initial protocol version, and a chain that already exists gets the same trees +from its upgrade rung. `add_initial_withdrawal_state_structure_operations` +adds the withdrawal sum trees behind `>= 4` and the credit history trees behind +`>= 14`; replaying mainnet's genesis at protocol version 1 takes neither branch. + ## Rules **Do:**