From c83a8efb7ee241e61bf626e9077a09ec615be6af Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 22 Sep 2025 09:41:42 +0200 Subject: [PATCH 01/10] doc: fix redirection latest->version-23 --- docs/_redirects.s3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_redirects.s3 b/docs/_redirects.s3 index 1403d630d9aa..5763cf9e9fd3 100644 --- a/docs/_redirects.s3 +++ b/docs/_redirects.s3 @@ -1,7 +1,7 @@ # This file redirects pages on the S3 bucket using a CloudFront server. # All redirections are relative to the docs/ folder. # Update this one at each MAJOR release of Octez: -/releases/latest.html /releases/version-22.html 302 +/releases/latest.html /releases/version-23.html 302 # These are inherited from the past, don't change: /whitedoc/micheline.html /shell/micheline.html 301 /whitedoc/michelson.html /active/michelson.html 301 -- GitLab From 97fddb2e41add8098b497644f9acdaa5e1c844f9 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Mon, 22 Sep 2025 09:42:39 +0200 Subject: [PATCH 02/10] doc: remove unmaintained site lambsonacid --- docs/user/snapshots.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 05630b2ef12c..581e7db1b674 100644 --- a/docs/user/snapshots.rst +++ b/docs/user/snapshots.rst @@ -209,4 +209,4 @@ of their nodes on a regular basis (usually daily) and make them available for download. These include: * `Tzinit snapshots `_ -* `Lambs on acid `_ +* `Test nets `_ -- GitLab From 0134d694fa70c578a9543c481501d0c4e684c397 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 23 Sep 2025 12:49:04 +0200 Subject: [PATCH 03/10] doc: introduce Finn the bot --- docs/alpha/staking.rst | 4 ++-- docs/seoul/staking.rst | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst index 4446acbf5645..0bd89deba04c 100644 --- a/docs/alpha/staking.rst +++ b/docs/alpha/staking.rst @@ -206,8 +206,8 @@ or more conveniently:: octez-client finalize unstake for -Note that starting with protocol S, not only the staker, but anyone can trigger ``finalize_unstake`` (in any case, the unfrozen funds still go to the staker). -This paves the way for implementing bots that regularly check finalizable unstakes on block explorers and trigger their finalization automatically. +Note that starting with protocol Seoul, not only the staker, but anyone can trigger ``finalize_unstake`` (in any case, the unfrozen funds still go to the staker). +In particular, an off-chain bot (known as Finn) regularly checks finalizable unstakes on block explorers and triggers their finalization automatically. In some circumstances, unstake and finalize can be done implicitly: any call to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending diff --git a/docs/seoul/staking.rst b/docs/seoul/staking.rst index bae4c56f095b..05a397d0d227 100644 --- a/docs/seoul/staking.rst +++ b/docs/seoul/staking.rst @@ -212,6 +212,7 @@ or more conveniently:: octez-client finalize unstake for Note that starting with protocol S, not only the staker, but anyone can trigger ``finalize_unstake`` (in any case, the unfrozen funds still go to the staker). +In particular, an off-chain bot (known as Finn) regularly checks finalizable unstakes on block explorers and triggers their finalization automatically. In some circumstances, unstake and finalize can be done implicitly: any call to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending -- GitLab From 5270a29a57801c144903b1a9bbdeb8d04c3c731e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 25 Sep 2025 16:03:51 +0200 Subject: [PATCH 04/10] doc: remove octezdoc.txt correctly --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index e5eb3da1381c..232fda5c684a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -313,6 +313,6 @@ fmt: black clean: @-rm -Rf "$(BUILDDIR)" "$(BUILDDIRTXT)" linkcheck odoc.log @-rm -f $(ERRDOCEXE) $(RPCDOCEXE) $(P2PDOCEXE) - @-rm -Rf api/errors.rst developer/metrics.csv user/node-config.json alpha/rpc.rst shell/rpc.rst shell/p2p_api.rst user/default-acl.json CHANGES-dev.rst developer/rollup_metrics.csv octezdoc.txt + @-rm -Rf api/errors.rst developer/metrics.csv user/node-config.json alpha/rpc.rst shell/rpc.rst shell/p2p_api.rst user/default-acl.json CHANGES-dev.rst developer/rollup_metrics.csv $(BUILDDIR)/octezdoc.txt @-rm -Rf api/octez-*.html api/octez-*.txt alpha/octez-*.html seoul/octez-*.html @-rm -Rf ../openapi-tmp -- GitLab From 6b173ce53847d81d75c739757609ac3e2c384868 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 25 Sep 2025 18:55:48 +0200 Subject: [PATCH 05/10] doc: mention (re)starting baker after defining the companion key --- docs/user/key-management.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index a36457fad68b..40394f118152 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -328,6 +328,8 @@ possession. This is the signature of the consensus public key using the consensu ensures ownership of the key. This process is done automatically by the client, and the proof is included in the receipt of the update operation. +.. _baking_consensus_key: + Baking With a Consensus Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -396,6 +398,10 @@ It is even possible to register both a consensus key and a companion key, with t octez-client register key as delegate --consensus-key --companion-key +Mind (re)starting the baker and pass the new companion key alias alongside the consensus and/or the delegate's key (the latter is needed only until the new keys become effective):: + + octez-baker run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass + .. _activate_fundraiser_account: Getting keys for fundraiser accounts -- GitLab From 3f826f5fcc05d43a8d5a59ff2e16d40ee600dcf9 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 30 Sep 2025 10:01:29 +0200 Subject: [PATCH 06/10] doc: extend note for breaking changes for operation encodings in S --- docs/introduction/breaking_changes.rst | 10 +++++++--- docs/protocols/023_seoul.rst | 6 +++--- docs/releases/version-23.rst | 3 +-- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index d3c58e816b65..470f4c289c68 100644 --- a/docs/introduction/breaking_changes.rst +++ b/docs/introduction/breaking_changes.rst @@ -14,8 +14,10 @@ that may be breaking. In the particular case of RPC changes, you may consult complementary information on :ref:`RPC versioning `, covering how new versions are introduced, the deprecation policy, and a concrete calendar of RPCs planned to be removed. -Denunciation operations ------------------------ +.. _operation_encodings_s: + +Operation encoding changes in Seoul +----------------------------------- Protocol S adds new operations and changes the encoding of some existing operations, for instance by adding new fields. These changes are related to the support for tz4 BLS addresses and their aggregated signatures. @@ -31,13 +33,15 @@ Most of the changes in the encodings of existing operations are either purely ad format <../shell/p2p_api>` may experience some issues. For example, the ``reveal`` operation has a new boolean field to mark the presence of the optional ``proof`` for tz4 revelation. + Users of such tools should check with their tool provider that their + versions are updated for protocol S, and upgrade them if needed. Breaking changes ~~~~~~~~~~~~~~~~ Starting in protocol S, the ``Double_preattestation_evidence`` and ``Double_attestation_evidence`` operations are replaced with a -new ``Double_consensus_operation_evidence`` operation, +new ``Double_consensus_operation_evidence`` operation, in order to enable denunciations of aggregated consensus operations. This new operation contains a denounced slot and two denounced consensus operations. For the evidence to be valid, the denounced operations diff --git a/docs/protocols/023_seoul.rst b/docs/protocols/023_seoul.rst index 09c537b3c694..e98e4d4f5f4d 100644 --- a/docs/protocols/023_seoul.rst +++ b/docs/protocols/023_seoul.rst @@ -75,14 +75,14 @@ Operations - The ``Reveal`` operation has a new optional ``proof`` field, which is required if (and only if) the manager key is a :ref:`tz4 (BLS - key)`. This results in an increase of gas cost + key)`, and a new boolean field, required for any kind of address to mark + the presence of the optional ``proof`` field. This results in an increase of gas cost per reveal of a tz4 public key. (MR :gl:`!18095`) .. warning:: Introduction of this new optional field might still lead to breaking changes - for tool providers see :doc:`breaking changes - <../introduction/breaking_changes>`. + for tool providers see :ref:`breaking changes `. - The optional ``proof`` field of the ``Update_consensus_key`` operation is now required if (and only if) the new consensus key is diff --git a/docs/releases/version-23.rst b/docs/releases/version-23.rst index 203da006957c..b5cebecd68fb 100644 --- a/docs/releases/version-23.rst +++ b/docs/releases/version-23.rst @@ -53,8 +53,7 @@ See https://forum.tezosagora.org/t/heads-up-native-multisig-accounts-in-protocol .. warning:: - Introduction of this feature needed some breaking changes for tool providers see :doc:`breaking - changes <../introduction/breaking_changes>`. + Introduction of this feature needed some breaking changes for tool providers see :ref:`breaking changes `. .. _snapshot_v23: -- GitLab From 93566859ee2225bd7ee411e374867067336a4d6e Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 1 Oct 2025 07:03:24 +0000 Subject: [PATCH 07/10] doc: fixes from German & Corey --- docs/alpha/staking.rst | 5 +++-- docs/introduction/breaking_changes.rst | 3 +-- docs/protocols/023_seoul.rst | 11 ++++++++--- docs/releases/version-23.rst | 3 ++- docs/user/key-management.rst | 2 +- docs/user/snapshots.rst | 2 +- 6 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst index 0bd89deba04c..94822d60478b 100644 --- a/docs/alpha/staking.rst +++ b/docs/alpha/staking.rst @@ -206,8 +206,9 @@ or more conveniently:: octez-client finalize unstake for -Note that starting with protocol Seoul, not only the staker, but anyone can trigger ``finalize_unstake`` (in any case, the unfrozen funds still go to the staker). -In particular, an off-chain bot (known as Finn) regularly checks finalizable unstakes on block explorers and triggers their finalization automatically. +With the activation of the Seoul protocol on mainnet, anyone can trigger ``finalize_unstake`` operations on behalf of the staker (and not just the staker themselves). In any case, the unfrozen funds always go to the staker, without any ownership transfer. + +In particular, this allows for deploying off-chain finalization bots such as `Finn `__, which regularly checks finalizable unstakes on block explorers and triggers `their finalization operations `__ automatically. In some circumstances, unstake and finalize can be done implicitly: any call to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index 470f4c289c68..42a70afc838d 100644 --- a/docs/introduction/breaking_changes.rst +++ b/docs/introduction/breaking_changes.rst @@ -33,8 +33,7 @@ Most of the changes in the encodings of existing operations are either purely ad format <../shell/p2p_api>` may experience some issues. For example, the ``reveal`` operation has a new boolean field to mark the presence of the optional ``proof`` for tz4 revelation. - Users of such tools should check with their tool provider that their - versions are updated for protocol S, and upgrade them if needed. + Users of such tools should check that they are operating versions compatible with the changes introduced by the Seoul protocol, and upgrade them if needed. Breaking changes ~~~~~~~~~~~~~~~~ diff --git a/docs/protocols/023_seoul.rst b/docs/protocols/023_seoul.rst index e98e4d4f5f4d..201e37c0039e 100644 --- a/docs/protocols/023_seoul.rst +++ b/docs/protocols/023_seoul.rst @@ -60,6 +60,9 @@ Breaking Changes addresses will also have to provide such a proof before sending other operations. This does not change anything about the revelation of new addresses, or non-tz4 addresses. (MR :gl:`!18078`) + However, to handle any address it is recommended to update all the tools producing or + processing reveal operations to a Seoul-compatible version + (see :ref:`breaking changes `). - ``../context/contracts/`` result now contains, when called on an implicit account, a boolean field ``revealed`` that tells if the public key of the @@ -74,9 +77,11 @@ Operations :gl:`!15244`, :gl:`!17485`) - The ``Reveal`` operation has a new optional ``proof`` field, which - is required if (and only if) the manager key is a :ref:`tz4 (BLS - key)`, and a new boolean field, required for any kind of address to mark - the presence of the optional ``proof`` field. This results in an increase of gas cost + is only present if the manager key is a :ref:`tz4 (BLS + key) `. This change requires updating all the tools producing or + processing reveal operations to a Seoul-compatible version + (see :ref:`breaking changes `). + This change also results in an increase of gas cost per reveal of a tz4 public key. (MR :gl:`!18095`) .. warning:: diff --git a/docs/releases/version-23.rst b/docs/releases/version-23.rst index b5cebecd68fb..046dc325b0be 100644 --- a/docs/releases/version-23.rst +++ b/docs/releases/version-23.rst @@ -53,7 +53,8 @@ See https://forum.tezosagora.org/t/heads-up-native-multisig-accounts-in-protocol .. warning:: - Introduction of this feature needed some breaking changes for tool providers see :ref:`breaking changes `. + The introduction of this feature entailed a few :ref:`breaking changes `, so it is recommended to update any tool producing or + processing reveal operations to a Seoul-compatible version… .. _snapshot_v23: diff --git a/docs/user/key-management.rst b/docs/user/key-management.rst index 40394f118152..3103c60609bd 100644 --- a/docs/user/key-management.rst +++ b/docs/user/key-management.rst @@ -398,7 +398,7 @@ It is even possible to register both a consensus key and a companion key, with t octez-client register key as delegate --consensus-key --companion-key -Mind (re)starting the baker and pass the new companion key alias alongside the consensus and/or the delegate's key (the latter is needed only until the new keys become effective):: +Please do (re)start the baker and provide the the new companion key alias alongside the consensus and/or the delegate's key on the command line (the latter is still needed until the new keys become active):: octez-baker run with local node ~/.tezos-node --liquidity-baking-toggle-vote pass diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 581e7db1b674..0d1885ecabd2 100644 --- a/docs/user/snapshots.rst +++ b/docs/user/snapshots.rst @@ -209,4 +209,4 @@ of their nodes on a regular basis (usually daily) and make them available for download. These include: * `Tzinit snapshots `_ -* `Test nets `_ +* `Teztnets (Tezos Testnets) `_ -- GitLab From 58cbfe6e84d3dfbc2132b7afde9b8d0ea0ee151f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 1 Oct 2025 17:20:35 +0200 Subject: [PATCH 08/10] doc: tell how to generate a bls proof --- docs/introduction/breaking_changes.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/introduction/breaking_changes.rst b/docs/introduction/breaking_changes.rst index 42a70afc838d..d9f1e4e11d99 100644 --- a/docs/introduction/breaking_changes.rst +++ b/docs/introduction/breaking_changes.rst @@ -51,6 +51,9 @@ aggregate whose committee includes this slot. The receipts for these operations have also been reworked, see :ref:`seoul_receipts_changes`. All existing tz4 addresses are being unrevealed when protocol S is adopted, and they must provide a proof of possession to be revealed again, see :ref:`seoul_breaking_changes`. +This proof may be generated using the client command:: + + octez-client create bls proof for Attestations ------------ -- GitLab From 1c4dd76c0e151cc133feda4b5d17408843af6f79 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 7 Oct 2025 09:58:57 +0200 Subject: [PATCH 09/10] doc: backport Finn doc to Seoul --- docs/seoul/staking.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/seoul/staking.rst b/docs/seoul/staking.rst index 05a397d0d227..16ec2fe32fbe 100644 --- a/docs/seoul/staking.rst +++ b/docs/seoul/staking.rst @@ -212,7 +212,9 @@ or more conveniently:: octez-client finalize unstake for Note that starting with protocol S, not only the staker, but anyone can trigger ``finalize_unstake`` (in any case, the unfrozen funds still go to the staker). -In particular, an off-chain bot (known as Finn) regularly checks finalizable unstakes on block explorers and triggers their finalization automatically. +With the activation of the Seoul protocol on mainnet, anyone can trigger ``finalize_unstake`` operations on behalf of the staker (and not just the staker themselves). In any case, the unfrozen funds always go to the staker, without any ownership transfer. + +In particular, this allows for deploying off-chain finalization bots such as `Finn `__, which regularly checks finalizable unstakes on block explorers and triggers `their finalization operations `__ automatically. In some circumstances, unstake and finalize can be done implicitly: any call to ``stake`` or ``unstake`` will implicitly finalize all currently finalizable pending -- GitLab From 84cce08bab0258a5538a0a4c526bd72d18076e44 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Wed, 8 Oct 2025 08:26:24 +0000 Subject: [PATCH 10/10] doc: improvements from zettez --- docs/alpha/staking.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst index 94822d60478b..a742403e256d 100644 --- a/docs/alpha/staking.rst +++ b/docs/alpha/staking.rst @@ -42,7 +42,7 @@ abusing the slashing mechanism for profit at the expense of their stakers. :ref:`Participation rewards ` are automatically shared -between delegates and their stakers. Staker's rewards are proportional to their +between delegates and their stakers. Stakers' rewards are proportional to their participation in the delegate's total staked at the time the rewards are given. This means that the staker gets rewards for staked tez as soon as they are staked, and stops receiving rewards as soon as the tez are unstaked, disregarding the @@ -51,14 +51,14 @@ fact that baking rights for the delegate are computed with some delays. policy ` by setting staking parameters which regulate whether they accept stakers (the default being to reject them), and if so, up to which fraction of their total staking balance. -They can also configure which proportion of the staking rewards from other stakers is set -to accrue to their own staked balance instead, thereby collecting an *edge* from the -rewards attributable to their stakers. +They can also configure the proportion of staking rewards from other +stakers that accrues to their own staked balance, which is referred to +as their "edge" on stakers' rewards. Freezing and unfreezing of staked funds is controlled directly by delegates and stakers. This entails that staked funds are frozen until manually -unfrozen by stakers. This is a two step process which spans for at least +unfrozen by stakers. This is a two-step process that spans at least ``UNSTAKE_FINALIZATION_DELAY`` cycles (cf. :ref:`Staked funds management `). @@ -206,7 +206,7 @@ or more conveniently:: octez-client finalize unstake for -With the activation of the Seoul protocol on mainnet, anyone can trigger ``finalize_unstake`` operations on behalf of the staker (and not just the staker themselves). In any case, the unfrozen funds always go to the staker, without any ownership transfer. +With the activation of the Seoul protocol on mainnet, anyone can trigger ``finalize_unstake`` operations on behalf of the staker (and not just the staker themselves). In any case, the unfrozen funds always go to the staker, without any ownership transfer. In particular, this allows for deploying off-chain finalization bots such as `Finn `__, which regularly checks finalizable unstakes on block explorers and triggers `their finalization operations `__ automatically. -- GitLab