From 83bbad5af37d02c30af128f41b615921e0d85ef0 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 14 Feb 2023 17:15:55 +0100 Subject: [PATCH 1/6] doc: preferably, an MR author assigns to MargeBot --- docs/developer/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer/contributing.rst b/docs/developer/contributing.rst index ba0327553213..81839f446ebe 100644 --- a/docs/developer/contributing.rst +++ b/docs/developer/contributing.rst @@ -182,7 +182,7 @@ You can refer to the following table that summarizes how assignee and When all discussions are resolved, and the MR has got at least two approvals from Octez Merge Team members, the developer should squash any fix-up commits that were applied (remembering to edit the commit -message appropriately). Then anyone can assign the MR to the `Nomadic +message appropriately). Then the developer (or anyone else when not possible) can assign the MR to the `Nomadic Marge-bot `__, which will automatically rebase the branch on top of master and finally merge it. -- GitLab From 8528d966f5cb3b3ff759d7ff0cbfd3a497cfe05d Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 16 Feb 2023 14:50:26 +0100 Subject: [PATCH 2/6] doc: update procedure for viewing the CI doc artifacts --- docs/README.rst | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/docs/README.rst b/docs/README.rst index 3f0983913497..84290484e6a0 100644 --- a/docs/README.rst +++ b/docs/README.rst @@ -15,19 +15,14 @@ You can build the documentation locally or in the CI. Building the documentation in the CI ------------------------------------ -When reviewing a merge request in the Gitlab interface, you may build the documentation in the CI without installing anything locally. Proceed as follows: +When reviewing a merge request (MR) in the Gitlab interface, you may build the documentation in the CI without checking out the source branch of the MR, and without installing Python locally. Proceed as follows: -- if you want the light version of the documentation (RST pages only): ++ trigger the CI if needed in the home page of the MR, and make sure that job ``documentation:build_all`` under the CI stage ``build`` is being executed ++ once the whole CI is finished, check the built documentation in the exposed artifacts on the home page of the MR - + make sure the CI job ``documentation:build`` under the CI stage ``build`` is executed (you may have to trigger it manually) - + once finished, check the light built documentation in the exposed artifacts +If you cannot wait for the whole CI to finish, the artifacts are not yet exposed on the home page of the MR; but click on the CI job ``documentation:build_all``, and in the job's page (once finished), click on ``Browse`` to retrieve only the doc artifacts. -- if you want the full version of the documentation (including CLI manuals and Odoc APIs): - - + trigger the CI job ``documentation:build_all`` under the CI stage ``manual`` - + once finished, check the full built documentation in the exposed artifacts - -If the artifacts are not exposed on the main page of the MR, click on the CI jobs mentioned above, and in the job's page (once finished), click on ``Browse``, then visualize file ``docs/_build/index.html``. +In both cases, visualize file ``docs/_build/index.html``. Building the documentation locally ---------------------------------- -- GitLab From 62accf565ab1d2224f32b3802017fa8475dbecf0 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Thu, 16 Feb 2023 15:31:44 +0100 Subject: [PATCH 3/6] doc: change rollup prefix from scr1 to sr1 in michelson.rst --- docs/alpha/michelson.rst | 8 ++++---- docs/mumbai/michelson.rst | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 8ea390ff3a0c..9af5628fb0d2 100644 --- a/docs/alpha/michelson.rst +++ b/docs/alpha/michelson.rst @@ -50,7 +50,7 @@ From Michelson, they are indistinguishable. A safe way to think about this is to consider that implicit accounts are smart contracts that always succeed to receive tokens, and does nothing else. -Finally, addresses prefixed with ``scr1`` identify smart rollups. +Finally, addresses prefixed with ``sr1`` identify :doc:`smart rollups <./smart_rollups>`. Intra-transaction semantics ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1595,7 +1595,7 @@ Bytes can be converted to natural numbers and integers. - ``NAT``: Convert ``bytes`` to type ``nat`` using big-endian encoding. The ``bytes`` are allowed to have leading zeros. - + :: :: bytes : 'S -> nat : 'S @@ -1605,14 +1605,14 @@ Bytes can be converted to natural numbers and integers. - ``INT``: Convert ``bytes`` to type ``int`` using big-endian two's complement encoding. The ``bytes`` are allowed to have leading zeros for non-negative numbers and leading ones for negative numbers. - + :: :: bytes : 'S -> int : 'S > INT / s : S => z : S iff s is a big-endian encoding of integer z - + - ``BYTES``: Convert a ``nat`` or an ``int`` to type ``bytes`` using big-endian encoding (and two's complement for ``int``). :: diff --git a/docs/mumbai/michelson.rst b/docs/mumbai/michelson.rst index f913600d35ed..f211511ceff8 100644 --- a/docs/mumbai/michelson.rst +++ b/docs/mumbai/michelson.rst @@ -53,7 +53,7 @@ always succeed to receive tokens, and does nothing else. Another kind of addresses, prefixed by ``txr1``, are related to :doc:`transaction rollups <./transaction_rollups>`. -Finally, addresses prefixed with ``scr1`` identify smart rollups. +Finally, addresses prefixed with ``sr1`` identify :doc:`smart rollups <./smart_rollups>`. Intra-transaction semantics ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1920,7 +1920,7 @@ Bytes can be converted to natural numbers and integers. - ``NAT``: Convert ``bytes`` to type ``nat`` using big-endian encoding. The ``bytes`` are allowed to have leading zeros. - + :: :: bytes : 'S -> nat : 'S @@ -1930,14 +1930,14 @@ Bytes can be converted to natural numbers and integers. - ``INT``: Convert ``bytes`` to type ``int`` using big-endian two's complement encoding. The ``bytes`` are allowed to have leading zeros for non-negative numbers and leading ones for negative numbers. - + :: :: bytes : 'S -> int : 'S > INT / s : S => z : S iff s is a big-endian encoding of integer z - + - ``BYTES``: Convert a ``nat`` or an ``int`` to type ``bytes`` using big-endian encoding (and two's complement for ``int``). :: -- GitLab From 981bb139e991a086c294fdcace8627041ed7252f Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 17 Feb 2023 12:11:23 +0100 Subject: [PATCH 4/6] doc: port section "Rollup node in a sandbox" to alpha --- docs/alpha/smart_rollups.rst | 9 +++++++++ docs/mumbai/smart_rollups.rst | 2 +- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 38cff3e4fca8..260e91002748 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -524,6 +524,15 @@ Second, the configured rollup node can be run: The log should show that the rollup node follows the Layer 1 chain and processes the inbox of each level. +Rollup node in a sandbox +"""""""""""""""""""""""" + +The node can also be tested locally with a sandbox environment. (See :doc:`sandbox documentation <../user/sandbox>`.) + +Once you initialized the "sandboxed" client data with ``./src/bin_client/octez-init-sandboxed-client.sh``, you can run a sandboxed rollup node with ``octez-smart-rollup-node-alpha run``. + +A temporary directory ``/tmp/tezos-smart-rollup-node.xxxxxxxx`` will be used. However, a specific data directory can be set with the environment variable ``SCORU_DATA_DIR``. + .. _sending_external_inbox_message_alpha: Sending an external inbox message diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 6aa005e27f7f..942c0d3d32bb 100644 --- a/docs/mumbai/smart_rollups.rst +++ b/docs/mumbai/smart_rollups.rst @@ -514,7 +514,7 @@ Rollup node in a sandbox The node can also be tested locally with a sandbox environment. (See :doc:`sandbox documentation <../user/sandbox>`.) -Once you initialized the "sandboxed" client data with ``./src/bin_client/octez-init-sandboxed-client.sh``, you can run a sandboxed rollup node with ``octez-smart-rollup'node-alpha run``. +Once you initialized the "sandboxed" client data with ``./src/bin_client/octez-init-sandboxed-client.sh``, you can run a sandboxed rollup node with ``octez-smart-rollup-node-PtMumbai run``. A temporary directory ``/tmp/tezos-smart-rollup-node.xxxxxxxx`` will be used. However, a specific data directory can be set with the environment variable ``SCORU_DATA_DIR``. -- GitLab From 67fda29de0550c8384a3888dbf286c6f52343093 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Fri, 17 Feb 2023 12:20:21 +0100 Subject: [PATCH 5/6] doc: remove wrong example of host functions --- docs/alpha/smart_rollups.rst | 5 +---- docs/mumbai/smart_rollups.rst | 5 +---- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 260e91002748..0ce439893a42 100644 --- a/docs/alpha/smart_rollups.rst +++ b/docs/alpha/smart_rollups.rst @@ -919,10 +919,7 @@ At its core, the WASM machine defined in the WASM standard is just a very evolved arithmetic machine. It needs to be enriched with so-called host functions in order to be used for greater purposes. The host functions provide an API to the WASM program to interact with an -“outer world”. In a browser for instance, this API typically allows the WASM -program to interact with the `DOM -`_ -of the webpage. +“outer world”. As for smart rollups, the host functions exposed to a WASM kernel allow it to interact with the components of persistent state: diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 942c0d3d32bb..739813b876cd 100644 --- a/docs/mumbai/smart_rollups.rst +++ b/docs/mumbai/smart_rollups.rst @@ -904,10 +904,7 @@ At its core, the WASM machine defined in the WASM standard is just a very evolved arithmetic machine. It needs to be enriched with so-called host functions in order to be used for greater purposes. The host functions provide an API to the WASM program to interact with an -“outer world”. In a browser for instance, this API typically allows the WASM -program to interact with the `DOM -`_ -of the webpage. +“outer world”. As for smart rollups, the host functions exposed to a WASM kernel allow it to interact with the components of persistent state: -- GitLab From e2f6f1c062208d07cb3ef628e4bfa1f5e02e66f1 Mon Sep 17 00:00:00 2001 From: Nic Volanschi Date: Tue, 21 Feb 2023 18:01:13 +0100 Subject: [PATCH 6/6] doc: remove tickets doc for Lima --- docs/lima/protocol.rst | 5 -- docs/lima/tickets.rst | 152 ----------------------------------------- 2 files changed, 157 deletions(-) delete mode 100644 docs/lima/tickets.rst diff --git a/docs/lima/protocol.rst b/docs/lima/protocol.rst index 0131b8752a32..57a36ccc1b4a 100644 --- a/docs/lima/protocol.rst +++ b/docs/lima/protocol.rst @@ -95,8 +95,3 @@ Sapling, etc), and some details about its implementation. :maxdepth: 2 validation - -.. toctree:: - :maxdepth: 2 - - tickets diff --git a/docs/lima/tickets.rst b/docs/lima/tickets.rst deleted file mode 100644 index 8a1b6e422f22..000000000000 --- a/docs/lima/tickets.rst +++ /dev/null @@ -1,152 +0,0 @@ -Tickets -======= - -Tickets are a special class of assets on Tezos that contracts can construct and store, and that can then be transferred between contracts, implicit accounts, or rollups. -They are useful to model ownership of some digital artefact, existing in a limited number of copies (or instances); this can further serve as a basis for restricting access to the artefact and permissions to use it. -In this document, we will explain the semantics and lifetime of tickets, including creation, transfer, and destruction. - - -Semantics ---------- - -A ticket represents a digital artefact existing in a limited number of copies (or instances). -As such, a ticket has the following four attributes: - -#. ``ticketer`` is the creator of the ticket, which is always a Tezos smart contract. - -#. ``contents`` is the :doc:`Michelson <./michelson>` expression attached to the ticket. - -#. ``content_ty`` is the :doc:`Michelson <./michelson>` type of the ``contents`` data. It can be any comparable type. - -#. ``amount`` is the amount of the ticket. It is a strictly positive whole number. - -Furthermore, a `ticket `__ cannot be duplicated -with the `DUP `__ -or the `DUP n `__ instructions. - - -Operations on tickets ---------------------- - -Creating -~~~~~~~~ - -Tickets can be constructed by smart contracts. To construct tickets, smart contracts use the ``TICKET`` -`instruction `__ with some ticket amount, -ticket content type, and value as inputs. -Smart contracts then may store them in contract storage or transfer them along to either -other contracts, rollups, or implicit accounts. - -Tickets cannot be constructed with instructions for duplication, such as ``DUP``. -Therefore, the issuance of tickets is completely within the control of the ticketer contract by -invoking ``TICKET`` instructions. - -Splitting -~~~~~~~~~ - -A ticket can be split into two tickets with the same ``contents`` and ``ticketer`` values, -as long as the sum of the ``amount`` of the two tickets is equal to that of the original. -This operation allows tickets to be spent across several transactions -by breaking tickets into smaller tickets. -Smart contracts may split tickets by invoking the `SPLIT_TICKET `__ instruction. -The ticket splitting is done automatically when an implicit account transfers part of a ticket. - -Joining -~~~~~~~ - -Tickets issued by the same ``ticketer`` contract with the same ``contents`` data of the -same ``contents_ty`` type are considered of the same kind. -Therefore, two such tickets can be **joined** into one ticket and the output ``amount`` -will be the sum of those of the two input tickets. -Smart contracts can join tickets via the `JOIN_TICKETS `__ instruction. -Tickets of the same kind are automatically joined when they belong to the same implicit account. - -Transferring -~~~~~~~~~~~~ - -Once a ticket has been constructed by a smart contract, it may be transferred to other contracts as follows: - -- *Smart contract to implicit account*: Smart contracts can transfer a ticket to implicit accounts - via `TRANSFER_TOKENS `__. - To do so, the contract needs to cast the address of the target implicit account to type ``contract (ticket cty)`` where ``cty`` is the type of the content of the ticket to be sent. This can be done using ``CONTRACT (ticket cty)``. - The rest is the same as making a contract call. - The following Michelson snippet is an example sending a ticket of amount ``10`` with a ``string`` content - ``"some ticket"`` to an implicit account address made available at the top of the stack. - -:: - - # Stack: address :: S - CONTRACT (ticket string) ; - # Stack: option (contract (ticket string)) :: S - ASSERT_SOME ; - # Stack: contract (ticket string) :: S - PUSH mutez 0 ; - # Stack: mutez :: contract (ticket string) :: S - PUSH nat 10 ; - # Stack: nat :: mutez :: contract (ticket string) :: S - PUSH string "some ticket" ; - # Stack: string :: nat :: mutez :: contract (ticket string) :: S - TICKET ; - # Stack: option (ticket string) :: mutez :: contract (ticket string) :: S - ASSERT_SOME ; - # Stack: ticket string :: mutez :: contract (ticket string) :: S - TRANSFER_TOKENS ; - # Stack: operation :: S - -- *Between smart contracts*: Contracts can send tickets to other contracts via regular contract - calls using the instruction ``TRANFSER_TOKENS``, - as long as target contracts accept tickets of matching content type in their ``parameter``\s. - -- *Between implicit accounts*: Implicit accounts can transfer existing tickets they own to other implicit accounts - with ``Transfer_ticket`` operation from their wallets. - For instance, ``octez-client`` can be invoked in the following way by an implicit account holder ``alice`` - to transfer a ticket of amount ``10``, type ``string``, content ``"some ticket"`` and ticketer ``ticketer`` - to another implicit account held by ``bob``. - -:: - - octez-client transfer 10 tickets from alice to bob with entrypoint default and type string and content '"some ticket"' and ticketer 'ticketer' - -If the amount of the ticket ``"some ticket"`` owned by ``alice`` was greater than 10, -this transfer would cause an automatic ticket split, -after which ``alice`` would continue to own the remaining amount. - -Note that the above command uses the expression "transfer 10 tickets" of the given kind, -instead of "transfer a ticket of amount 10". -Indeed, by virtue of automatic joining of tickets of the same kind belonging to the same implicit account, -this formulation does not introduce any ambiguity: -the implicit account cannot hold several distinct tickets of this kind. -Of course, these expressions would not be interchangeable for tickets belonging to a smart contract. - -- *Implicit account to smart contract*: Using the same ``Transfer_ticket`` operation, implicit accounts - can also send their tickets to smart contracts. - In this case, the entrypoint, as defined by the specification of the target contract, must accept this kind of tickets. - Here is an example using ``octez-client`` to transfer a ticket of amount ``10``, type ``string``, - content ``"some ticket"`` and ticketer ``ticketer`` owned by ``alice`` to a contract ``receiver`` accepting tickets - at the entrypoint ``save``. - -:: - - octez-client transfer 10 tickets from alice to receiver with entrypoint save and type string and content '"some ticket"' and ticketer 'ticketer' - -In this case, too, automatic ticket splitting may happen, under the same circumstances. - -.. note:: - - This page does not cover transfers of tickets to/from rollups. For that, refer to the documentation pages of particular rollups (e.g. :doc:`./transaction_rollups`). - - -Destroying -~~~~~~~~~~~ - -Only smart contracts can destroy tickets, by simply dropping them. -That is, by not storing them anymore -in the contract storage and not sending them to other contracts. -Implicit accounts, on the other hand, cannot destroy any ticket in their possession. - -For instance, an implicit account ``A`` may receive a ``string`` ticket of amount ``2`` with -content ``Lorem ipsum`` created by a smart contract ``B``. -``A`` may send amount ``1`` of it to a smart contract ``C``. This automatically splits the ticket into two tickets of amount ``1``. -Now ``C`` may destroy this ticket by dropping it and ``A`` will still hold a ticket of amount ``1`` -with a ``string`` content ``Lorem ipsum`` created by ``B``. -It will remain in the possession of ``A`` until ``A`` sends it to another implicit account or smart contract. -- GitLab