diff --git a/docs/Makefile b/docs/Makefile index e5eb3da1381c90d625fe3ec4086ee798bf0d6a1d..232fda5c684a114fa435e210837097798284eb41 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 diff --git a/docs/_redirects.s3 b/docs/_redirects.s3 index 1403d630d9aae483f38a0fbd52c9fcb8094e8774..5763cf9e9fd373bd5beaae45b2f5722b7ff8da2d 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 diff --git a/docs/alpha/staking.rst b/docs/alpha/staking.rst index 4446acbf5645b231125462e4f58720571df13766..a742403e256d995c7c4703a06de7493037bc0f5f 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,8 +206,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). -This paves the way for implementing bots that regularly check finalizable unstakes on block explorers and trigger 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 d3c58e816b65d14012201ab22dc1c4a714e50b66..d9f1e4e11d990e08e98d53af243da7a221913ef8 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,14 @@ 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 that they are operating versions compatible with the changes introduced by the Seoul protocol, 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 @@ -48,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 ------------ diff --git a/docs/protocols/023_seoul.rst b/docs/protocols/023_seoul.rst index 09c537b3c6949bf3ea754976d38709c0833f872c..201e37c0039e31af08f84110a0f26905478f6d39 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,15 +77,17 @@ 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)`. 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:: 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 203da006957c6ef42d764b953c73a49c59b41d42..046dc325b0be0c482481edf9f186c8a19aa26b28 100644 --- a/docs/releases/version-23.rst +++ b/docs/releases/version-23.rst @@ -53,8 +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 :doc:`breaking - changes <../introduction/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/seoul/staking.rst b/docs/seoul/staking.rst index bae4c56f095bd0726237cdecceab52e1ca3b9ca4..16ec2fe32fbe7b173b33a12086f092c11e2c3b76 100644 --- a/docs/seoul/staking.rst +++ b/docs/seoul/staking.rst @@ -212,6 +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). +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/user/key-management.rst b/docs/user/key-management.rst index a36457fad68b5e4f00f0194d896e8ae4ce6e68be..3103c60609bdcd37d1e0c0cc34e819a10cbbca01 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 +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 + .. _activate_fundraiser_account: Getting keys for fundraiser accounts diff --git a/docs/user/snapshots.rst b/docs/user/snapshots.rst index 05630b2ef12c3f9b6cb1ddf40f861397c858265a..0d1885ecabd2df32b2c8325d7a8f6e556b467cab 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 `_ +* `Teztnets (Tezos Testnets) `_