diff --git a/docs/README.rst b/docs/README.rst index 3f09839134973aafba7ca4af730bdc5c691c02bf..84290484e6a066bad41abc7ab1bf78fa624f24ad 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 ---------------------------------- diff --git a/docs/alpha/michelson.rst b/docs/alpha/michelson.rst index 8ea390ff3a0c8e3e9bfbd7d79113ac377d56cd69..9af5628fb0d227224a3a1adf875cd91b7f222164 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/alpha/smart_rollups.rst b/docs/alpha/smart_rollups.rst index 38cff3e4fca8fe27c3977daa6ce7b0f0757ac451..0ce439893a42dc6edf7b65d2a8a3b3dbed83409f 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 @@ -910,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/developer/contributing.rst b/docs/developer/contributing.rst index ba0327553213161b0baa3de8a13b77c85e708b7b..81839f446ebe8af9fb2106105cd210c74d1bc82f 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. diff --git a/docs/lima/protocol.rst b/docs/lima/protocol.rst index 0131b8752a321884e41e127464cee30949392107..57a36ccc1b4ae5d27aa1c1976c1e3ae872799c94 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 8a1b6e422f22b7070864ee89f463f93f51fe00e9..0000000000000000000000000000000000000000 --- 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. diff --git a/docs/mumbai/michelson.rst b/docs/mumbai/michelson.rst index f913600d35ed89541f90229719e9afea7e7ebead..f211511ceff8b40bf74a02a2081189bbc199daba 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``). :: diff --git a/docs/mumbai/smart_rollups.rst b/docs/mumbai/smart_rollups.rst index 6aa005e27f7f792a3637e75ef52cc941da72b915..739813b876cd8fb5907c5db8ff91a082cffe056e 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``. @@ -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: