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..ee0556e0325 100644 --- a/book/src/contributing/coding-conventions.md +++ b/book/src/contributing/coding-conventions.md @@ -84,7 +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. +(`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 ba303a9a835..7a59a994be1 100644 --- a/book/src/versioning/versioned-dispatch.md +++ b/book/src/versioning/versioned-dispatch.md @@ -687,6 +687,27 @@ 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. + +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:**