";
- close_box ();
- end;
-
- close_box ()
-
-let pp_info_to_rst
- ppf
- (Error_monad.{ title ; _ } as error_info) =
- let open Format in
-
- fprintf ppf "**%s**@\n@\n" (if title = "" then "" else title);
- fprintf ppf "@[%a@ @ @]" pp_print_html_tabs error_info;
-
-module ErrorSet = Set.Make(struct
- type t = Error_monad.error_info
- let compare { Error_monad.id ; _ } { Error_monad.id = id' ; _ } =
- String.compare id id'
- end)
-
-module ErrorPartition = struct
- include Map.Make(struct
- include String
- let titles = List.map snd section_titles
-
- let compare s s' =
- let idx s =
- let rec loop acc = function
- | [] -> assert false
- | h::_ when h = s -> acc
- | _::t -> loop (acc + 1) t
- in loop 0 titles
- in
- Pervasives.compare (idx s) (idx s')
- end)
-
- let add_error (id : key) (error : Error_monad.error_info) (map : 'a t) =
- let title =
- try
- snd
- (List.find
- (fun (id_set, _) ->
- List.exists (fun pattern -> Stringext.find_from id ~pattern = Some 0) id_set)
- section_titles)
- with
- | Not_found -> default_section_title
- in
- let set =
- try find title map with Not_found -> ErrorSet.empty
- in
- add title (ErrorSet.add error set) map
-end
-
-let pp_error_map ppf (map : ErrorSet.t ErrorPartition.t) : unit =
- let open Format in
- ErrorPartition.iter (fun section_title set ->
- fprintf ppf "%a" pp_rst_h2 section_title ;
-
- ErrorSet.iter
- (fun error_repr ->
- fprintf ppf "@[%a@]@\n@\n" pp_info_to_rst error_repr
- ) set
- ) map
-
-let script =
- ""
-
-let style =
- ""
-
-let print_script ppf =
- (* HACK : show/hide JSON schemas + style *)
- fprintf ppf "@[.. raw:: html@\n@\n" ;
- fprintf ppf "@[%s%s@]@\n@\n@]@]@." script style
-
-(* Main *)
-let () =
- let open Format in
- let ppf = std_formatter in
-
- (* Header *)
- let title = "RPC Errors" in
- fprintf ppf "%a" pp_rst_h1 title ;
-
- print_script ppf ;
-
- fprintf ppf
- "This document references possible errors that can come \
- from RPC calls. It is generated from the OCaml source \
- code (master branch).@\n@\n" ;
-
- (* Body *)
- let map =
- let all_errors =
- Error_monad.get_registered_errors () in
- List.fold_left
- (fun acc ( Error_monad.{ id ; _ } as error ) ->
- ErrorPartition.add_error id error acc
- ) ErrorPartition.empty all_errors
- in
-
- fprintf ppf "%a" pp_error_map map
diff --git a/vendors/tezos-modded/docs/doc_gen/node_helpers.ml b/vendors/tezos-modded/docs/doc_gen/node_helpers.ml
deleted file mode 100644
index 213a58d50..000000000
--- a/vendors/tezos-modded/docs/doc_gen/node_helpers.ml
+++ /dev/null
@@ -1,62 +0,0 @@
-(*****************************************************************************)
-(* *)
-(* Open Source License *)
-(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *)
-(* *)
-(* Permission is hereby granted, free of charge, to any person obtaining a *)
-(* copy of this software and associated documentation files (the "Software"),*)
-(* to deal in the Software without restriction, including without limitation *)
-(* the rights to use, copy, modify, merge, publish, distribute, sublicense, *)
-(* and/or sell copies of the Software, and to permit persons to whom the *)
-(* Software is furnished to do so, subject to the following conditions: *)
-(* *)
-(* The above copyright notice and this permission notice shall be included *)
-(* in all copies or substantial portions of the Software. *)
-(* *)
-(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
-(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *)
-(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *)
-(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
-(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *)
-(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *)
-(* DEALINGS IN THE SOFTWARE. *)
-(* *)
-(*****************************************************************************)
-
-let genesis : State.Chain.genesis = {
- time =
- Time.of_notation_exn "2018-04-17T11:46:23Z" ;
- block =
- Block_hash.of_b58check_exn
- "BLockGenesisGenesisGenesisGenesisGenesisa52f8bUWPcg" ;
- protocol =
- Protocol_hash.of_b58check_exn
- "ProtoGenesisGenesisGenesisGenesisGenesisGenesk612im" ;
-}
-
-let with_node f =
- let run dir =
- let (/) = Filename.concat in
- let node_config : Node.config = {
- genesis ;
- patch_context = None ;
- store_root = dir / "store" ;
- context_root = dir / "context" ;
- p2p = None ;
- test_chain_max_tll = None ;
- checkpoint = None ;
- } in
- Node.create
- node_config
- Node.default_peer_validator_limits
- Node.default_block_validator_limits
- Node.default_prevalidator_limits
- Node.default_chain_validator_limits >>=? fun node ->
- f node >>=? fun () ->
- return () in
- Lwt_utils_unix.with_tempdir "tezos_rpcdoc_" run >>= function
- | Ok () ->
- Lwt.return_unit
- | Error err ->
- Format.eprintf "%a@." pp_print_error err ;
- Pervasives.exit 1
diff --git a/vendors/tezos-modded/docs/doc_gen/p2p_doc.ml b/vendors/tezos-modded/docs/doc_gen/p2p_doc.ml
deleted file mode 100644
index 8925b2e71..000000000
--- a/vendors/tezos-modded/docs/doc_gen/p2p_doc.ml
+++ /dev/null
@@ -1,70 +0,0 @@
-(*****************************************************************************)
-(* *)
-(* Open Source License *)
-(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *)
-(* *)
-(* Permission is hereby granted, free of charge, to any person obtaining a *)
-(* copy of this software and associated documentation files (the "Software"),*)
-(* to deal in the Software without restriction, including without limitation *)
-(* the rights to use, copy, modify, merge, publish, distribute, sublicense, *)
-(* and/or sell copies of the Software, and to permit persons to whom the *)
-(* Software is furnished to do so, subject to the following conditions: *)
-(* *)
-(* The above copyright notice and this permission notice shall be included *)
-(* in all copies or substantial portions of the Software. *)
-(* *)
-(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
-(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *)
-(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *)
-(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
-(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *)
-(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *)
-(* DEALINGS IN THE SOFTWARE. *)
-(* *)
-(*****************************************************************************)
-
-let protocols = [
- "Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
-]
-
-let main _node =
- (* Style : hack *)
- Format.printf "%a@." Rst.pp_raw_html Rst.style ;
- (* Script : hack *)
- Format.printf "%a@." Rst.pp_raw_html Rst.script ;
- (* Page title *)
- Format.printf "%a" Rst.pp_h1 "P2P message format" ;
- (* include/copy usage.rst from input *)
- let rec loop () =
- let s = read_line () in
- Format.printf "%s@\n" s ;
- loop () in
- begin try loop () with End_of_file -> () end ;
- Format.printf "@\n" ;
- (* Data *)
- Format.printf "%a@\n@\n%a@\n@."
- Rst.pp_h2 "Block header (shell)"
- Data_encoding.Binary_schema.pp
- (Data_encoding.Binary.describe Block_header.encoding) ;
- Format.printf "%a@\n@\n%a@\n@."
- Rst.pp_h2 "Operation (shell)"
- Data_encoding.Binary_schema.pp
- (Data_encoding.Binary.describe Operation.encoding) ;
- List.iter
- (fun (_name, hash) ->
- let hash = Protocol_hash.of_b58check_exn hash in
- let (module Proto) = Registered_protocol.get_exn hash in
- Format.printf "%a@\n@\n%a@\n@."
- Rst.pp_h2 "Block_header (alpha-specific)"
- Data_encoding.Binary_schema.pp
- (Data_encoding.Binary.describe Proto.block_header_data_encoding) ;
- Format.printf "%a@\n@\n%a@\n@."
- Rst.pp_h2 "Operation (alpha-specific)"
- Data_encoding.Binary_schema.pp
- (Data_encoding.Binary.describe Proto.operation_data_encoding) ;
- )
- protocols ;
- return ()
-
-let () =
- Lwt_main.run (Node_helpers.with_node main)
diff --git a/vendors/tezos-modded/docs/doc_gen/rpc_doc.ml b/vendors/tezos-modded/docs/doc_gen/rpc_doc.ml
deleted file mode 100644
index 81e6b8b2d..000000000
--- a/vendors/tezos-modded/docs/doc_gen/rpc_doc.ml
+++ /dev/null
@@ -1,314 +0,0 @@
-(*****************************************************************************)
-(* *)
-(* Open Source License *)
-(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *)
-(* *)
-(* Permission is hereby granted, free of charge, to any person obtaining a *)
-(* copy of this software and associated documentation files (the "Software"),*)
-(* to deal in the Software without restriction, including without limitation *)
-(* the rights to use, copy, modify, merge, publish, distribute, sublicense, *)
-(* and/or sell copies of the Software, and to permit persons to whom the *)
-(* Software is furnished to do so, subject to the following conditions: *)
-(* *)
-(* The above copyright notice and this permission notice shall be included *)
-(* in all copies or substantial portions of the Software. *)
-(* *)
-(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
-(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *)
-(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *)
-(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
-(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *)
-(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *)
-(* DEALINGS IN THE SOFTWARE. *)
-(* *)
-(*****************************************************************************)
-
-let protocols = [
- "Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
-]
-
-let pp_name ppf = function
- | [] | [""] -> Format.pp_print_string ppf "/"
- | prefix -> Format.pp_print_string ppf (String.concat "/" prefix)
-
-let ref_of_service (prefix, meth) =
- Format.asprintf "%s_%s"
- (Resto.string_of_meth meth)
- (Re.Str.global_replace
- (Re.Str.regexp "<\\([^>]*\\)>")
- "\\1"
- (String.concat "--" prefix))
-
-module Index = struct
-
- let rec pp prefix ppf dir =
- let open Resto.Description in
- match dir with
- | Empty -> Format.fprintf ppf "Empty"
- | Static { services ; subdirs = None } ->
- pp_services prefix ppf services
- | Static { services ; subdirs = Some (Suffixes map) } ->
- Format.fprintf ppf "@[%a@ @ %a@]"
- (pp_services prefix) services
- (Format.pp_print_list
- ~pp_sep:(fun ppf () -> Format.fprintf ppf "@ @ ")
- (pp_suffixes prefix))
- (Resto.StringMap.bindings map)
- | Static { services ; subdirs = Some (Arg (arg, dir)) } ->
- let name = Format.asprintf "<%s>" arg.name in
- Format.fprintf ppf "@[%a@ @ %a@]"
- (pp_services prefix) services
- (pp_suffixes prefix) (name, dir)
- | Dynamic _ ->
- Format.fprintf ppf "* %a ()" pp_name prefix
-
- and pp_suffixes prefix ppf (name, dir) =
- pp (prefix @ [name]) ppf dir
-
- and pp_services prefix ppf services =
- match (Resto.MethMap.bindings services) with
- | [] ->
- Format.fprintf ppf "* %a" pp_name prefix
- | _ :: _ as services ->
- Format.fprintf ppf "* %a (@[%a@])"
- pp_name prefix
- (Format.pp_print_list
- ~pp_sep:Format.pp_print_space
- (pp_service_method prefix)) services
-
- and pp_service_method prefix ppf (meth, _service) =
- Format.fprintf ppf "`%s <%s_>`_"
- (Resto.string_of_meth meth)
- (ref_of_service (prefix, meth))
-
-end
-
-module Description = struct
-
- module Query = struct
-
- let pp_arg fmt =
- let open RPC_arg in
- function { name ; _ } ->
- Format.fprintf fmt "<%s>" name
-
- let pp_title_item ppf =
- let open RPC_description in
- function {name ; kind ; _ } ->
- match kind with
- | Single arg | Optional arg ->
- Format.fprintf ppf "[%s=%a]" name pp_arg arg
- | Flag ->
- Format.fprintf ppf "[%s]" name
- | Multi arg ->
- Format.fprintf ppf "(%s=%a)\\*" name pp_arg arg
-
- let pp_title ppf query =
- Format.fprintf ppf "%s%a"
- (if query = [] then "" else "?")
- (Format.pp_print_list
- ~pp_sep:(fun ppf () -> Format.fprintf ppf "&")
- pp_title_item) query
-
- let pp_html_arg fmt =
- let open RPC_arg in
- function { name ; _ } ->
- Format.fprintf fmt "<%s>" name
-
- let pp_item ppf =
- let open RPC_description in
- function { name ; description ; kind } ->
- begin match kind with
- | Single arg
- | Optional arg
- | Multi arg ->
- Format.fprintf ppf
- "%s = %a"
- name pp_html_arg arg
- | Flag ->
- Format.fprintf ppf
- "%s"
- name
- end ;
- begin match description with
- | None -> ()
- | Some descr -> Format.fprintf ppf " : %s" descr
- end
-
- let pp ppf query =
- match query with
- | [] -> ()
- | _ :: _ as query ->
- Format.fprintf ppf
- "
")
- pp_item)
- query
-
- end
-
- module Tabs = struct
-
- let pp_tab_div ppf f =
- Format.fprintf ppf
- "@[
%a
@]"
- (fun ppf () -> f ppf) ()
-
- let pp_tabcontent_div ~id ~class_ ppf f =
- Format.fprintf ppf
- "@[
@ \
- %a@ \
- @]
@ "
- id class_ (fun ppf () -> f ppf) ()
-
- let pp_button ppf ?(default=false) ~shortlabel ~content target_ref =
- Format.fprintf ppf
- "@ "
- (if default then " defaultOpen" else "")
- (target_ref ^ shortlabel)
- target_ref
- content
-
- let pp_content ppf ~tag ~shortlabel target_ref pp_content content =
- pp_tabcontent_div
- ~id:(target_ref ^ shortlabel) ~class_:target_ref ppf
- begin fun ppf ->
- Format.fprintf ppf "<%s>@ %a%s>" tag pp_content content tag
- end
-
- let pp_description ppf (service : _ RPC_description.service) =
- let open RPC_description in
- (* TODO collect and display arg description (in path and in query) *)
- Format.fprintf ppf "@[%a@]%a"
- Format.pp_print_text (Option.unopt ~default:"" service.description)
- Query.pp service.query
-
- let pp ppf prefix service =
- let open RPC_description in
- let target_ref = ref_of_service (prefix, service.meth) in
- Rst.pp_html ppf begin fun ppf ->
- pp_tab_div ppf begin fun ppf ->
- pp_button ppf
- ~default:true ~shortlabel:"descr" ~content:"Description"
- target_ref ;
- Option.iter service.input ~f: begin fun _ ->
- pp_button ppf
- ~default:false ~shortlabel:"input.json" ~content:"Json input"
- target_ref ;
- pp_button ppf
- ~default:false ~shortlabel:"input.bin" ~content:"Binary input"
- target_ref
- end ;
- pp_button ppf
- ~default:false ~shortlabel:"output.json" ~content:"Json output"
- target_ref ;
- pp_button ppf
- ~default:false ~shortlabel:"output.bin" ~content:"Binary output"
- target_ref ;
- end ;
- pp_content ppf
- ~tag:"p" ~shortlabel:"descr" target_ref
- pp_description service ;
- Option.iter service.input ~f: begin fun (schema, bin_schema) ->
- pp_content ppf
- ~tag:"pre" ~shortlabel:"input.json" target_ref
- Json_schema.pp schema ;
- pp_content ppf
- ~tag:"pre" ~shortlabel:"input.bin" target_ref
- Data_encoding.Binary_schema.pp bin_schema ;
- end ;
- pp_content ppf
- ~tag:"pre" ~shortlabel:"output.json" target_ref
- Json_schema.pp (fst service.output) ;
- pp_content ppf
- ~tag:"pre" ~shortlabel:"output.bin" target_ref
- Data_encoding.Binary_schema.pp (snd service.output) ;
- end
-
- end
-
- let rec pp prefix ppf dir =
- let open Resto.Description in
- match dir with
- | Empty -> ()
- | Static { services ; subdirs = None } ->
- pp_services prefix ppf services
- | Static { services ; subdirs = Some (Suffixes map) } ->
- pp_services prefix ppf services ;
- Format.pp_print_list (pp_suffixes prefix)
- ppf (Resto.StringMap.bindings map)
- | Static { services ; subdirs = Some (Arg (arg, dir)) } ->
- let name = Format.asprintf "<%s>" arg.name in
- pp_services prefix ppf services ;
- pp_suffixes prefix ppf (name, dir)
- | Dynamic _ -> ()
-
- and pp_suffixes prefix ppf (name, dir) =
- pp (prefix @ [name]) ppf dir
-
- and pp_services prefix ppf services =
- List.iter
- (pp_service prefix ppf)
- (Resto.MethMap.bindings services)
-
- and pp_service prefix ppf (meth, service) =
- Rst.pp_ref ppf (ref_of_service (prefix, meth)) ;
- Format.fprintf ppf "**%s %a%a**@\n@\n"
- (Resto.string_of_meth meth)
- pp_name prefix
- Query.pp_title service.query ;
- Tabs.pp ppf prefix service
-
-end
-
-let pp_document ppf descriptions =
- (* Style : hack *)
- Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.style ;
- (* Script : hack *)
- Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.script ;
- (* Index *)
- Format.pp_set_margin ppf 10000 ;
- Format.pp_set_max_indent ppf 9000 ;
- Format.fprintf ppf "%a" Rst.pp_ref "rpc_index" ;
- Rst.pp_h2 ppf "RPCs - Index" ;
- List.iter
- (fun (name, prefix, rpc_dir) ->
- Rst.pp_h3 ppf name ;
- Format.fprintf ppf "%a@\n@\n" (Index.pp prefix) rpc_dir)
- descriptions ;
- (* Full description *)
- Rst.pp_h2 ppf "RPCs - Full description" ;
- Format.pp_print_flush ppf () ;
- Format.pp_set_margin ppf 80 ;
- Format.pp_set_max_indent ppf 76 ;
- List.iter
- (fun (name, prefix, rpc_dir) ->
- Rst.pp_h3 ppf name ;
- Format.fprintf ppf "%a@\n@\n" (Description.pp prefix) rpc_dir)
- descriptions
-
-let main node =
- let shell_dir = Node.build_rpc_directory node in
- let protocol_dirs =
- List.map
- (fun (name, hash) ->
- let hash = Protocol_hash.of_b58check_exn hash in
- let (module Proto) = Registered_protocol.get_exn hash in
- "Protocol " ^ name,
- [".." ; ""] ,
- RPC_directory.map (fun () -> assert false) @@
- Block_directory.build_raw_rpc_directory (module Proto) (module Proto))
- protocols in
- let dirs = ("Shell", [""], shell_dir) :: protocol_dirs in
- Lwt_list.map_p
- (fun (name, path, dir) ->
- RPC_directory.describe_directory ~recurse:true ~arg:() dir >>= fun dir ->
- Lwt.return (name, path, dir))
- dirs >>= fun descriptions ->
- let ppf = Format.std_formatter in
- pp_document ppf descriptions ;
- return ()
-
-let () =
- Lwt_main.run (Node_helpers.with_node main)
diff --git a/vendors/tezos-modded/docs/doc_gen/rst.ml b/vendors/tezos-modded/docs/doc_gen/rst.ml
deleted file mode 100644
index 232a5397a..000000000
--- a/vendors/tezos-modded/docs/doc_gen/rst.ml
+++ /dev/null
@@ -1,120 +0,0 @@
-(*****************************************************************************)
-(* *)
-(* Open Source License *)
-(* Copyright (c) 2018 Dynamic Ledger Solutions, Inc. *)
-(* *)
-(* Permission is hereby granted, free of charge, to any person obtaining a *)
-(* copy of this software and associated documentation files (the "Software"),*)
-(* to deal in the Software without restriction, including without limitation *)
-(* the rights to use, copy, modify, merge, publish, distribute, sublicense, *)
-(* and/or sell copies of the Software, and to permit persons to whom the *)
-(* Software is furnished to do so, subject to the following conditions: *)
-(* *)
-(* The above copyright notice and this permission notice shall be included *)
-(* in all copies or substantial portions of the Software. *)
-(* *)
-(* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR*)
-(* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, *)
-(* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL *)
-(* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER*)
-(* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING *)
-(* FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER *)
-(* DEALINGS IN THE SOFTWARE. *)
-(* *)
-(*****************************************************************************)
-
-let pp_title ~char ppf title =
- let sub = String.map (fun _ -> char) title in
- Format.fprintf ppf "@[%s@ %s@ @ @]" title sub
-
-let pp_h1 = pp_title ~char:'#'
-let pp_h2 = pp_title ~char:'*'
-let pp_h3 = pp_title ~char:'='
-let pp_h4 = pp_title ~char:'`'
-
-let pp_raw_html ppf str =
- Format.fprintf ppf "@[.. raw:: html@ @ %s@ @ @]"
- (Re.Str.global_replace (Re.Str.regexp "\n") "\n " str)
-
-let pp_html ppf f =
- Format.fprintf ppf
- "@[.. raw:: html@ @ %a@]@\n@\n"
- (fun ppf () -> f ppf) ()
-
-let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name
-
-
-
-let style = {css|
-
-|css}
-
-let script = {script|
-
-|script}
diff --git a/vendors/tezos-modded/docs/index.rst b/vendors/tezos-modded/docs/index.rst
deleted file mode 100644
index 595fd5670..000000000
--- a/vendors/tezos-modded/docs/index.rst
+++ /dev/null
@@ -1,160 +0,0 @@
-.. Tezos documentation master file, created by
- sphinx-quickstart on Sat Nov 11 11:08:48 2017.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-
-Welcome to the Tezos Developer Documentation!
-=============================================
-
-The Project
------------
-
-Tezos is a distributed consensus platform with meta-consensus
-capability. Tezos not only comes to consensus about the state of its ledger,
-like Bitcoin or Ethereum. It also attempts to come to consensus about how the
-protocol and the nodes should adapt and upgrade.
-
- - Developer documentation is available online at
- https://tezos.gitlab.io/master . The documentation is automatically
- generated for the master branch, the main network `mainnet
- `_ and the test network `alphanet
- `_.
- Make sure you are consulting the right version.
- - The website https://tezos.com/ contains more information about the project.
- - All development happens on GitLab at https://gitlab.com/tezos/tezos
-
-The source code of Tezos is placed under the MIT Open Source License.
-
-The Community
--------------
-
-- The website of the `Tezos Foundation `_.
-- `Tezos sub-reddit `_ is an
- important meeting point of the community.
-- Several community-built block explorers are available:
-
- - https://tzscan.io
- - https://tezex.info
-
-- A few community-run websites collect useful Tezos links:
-
- - https://www.tezos.help
- - https://tezos.rocks
-
-- More resources can be found in the :ref:`support` page.
-
-The Networks
-------------
-
-.. _mainnet:
-
-Mainnet
-~~~~~~~
-
-The Tezos network is the current incarnation of the Tezos blockchain.
-It runs with real tez that have been allocated to the
-donors of July 2017 ICO (see :ref:`activate_fundraiser_account`).
-
-The Tezos network has been live and open since June 30th 2018.
-
-All the instructions in this documentation are valid for Mainnet
-however we **strongly** encourage users to first try all the
-introduction tutorials on Alphanet to familiarize themselves without
-risks.
-
-.. _alphanet:
-
-Alphanet
-~~~~~~~~
-
-Tezos Alphanet is a test network for the Tezos blockchain with a
-faucet to obtain free tez (see :ref:`faucet`).
-It is updated and rebooted rarely and it is running the same code as
-the Mainnet.
-It is the reference network for developers wanting to test their
-software before going to beta and for users who want to familiarize
-themselves with Tezos before using their real tez.
-
-We offer support for Alphanet on IRC.
-
-The Tezos Alpha (test) network has been live and open since February 2017.
-
-
-.. _zeronet:
-
-Zeronet
-~~~~~~~
-
-Zeronet is the most cutting-edge development network of Tezos. It is
-restarted without notice, possibly several times a day.
-This network is mostly used internally by the Tezos developers and may
-have *different constants* from Alphanet or Mainnet, for example it
-has shorter cycles and a shorter interval between blocks.
-We offer no support for the Zeronet.
-
-
-Getting started
----------------
-
-The best place to start exploring the project is following the How Tos
-in the :ref:`introduction `.
-
-
-.. toctree::
- :maxdepth: 2
- :caption: Introduction:
-
- introduction/howtoget
- introduction/howtouse
- introduction/howtorun
- introduction/various
- introduction/support
- introduction/contributing
-
-.. toctree::
- :maxdepth: 2
- :caption: White doc:
-
- whitedoc/the_big_picture
- whitedoc/p2p
- whitedoc/validation
- whitedoc/michelson
- whitedoc/proof_of_stake
- whitedoc/voting
-
-.. toctree::
- :maxdepth: 2
- :caption: Protocols:
-
- protocols/003_PsddFKi3
-
-.. toctree::
- :maxdepth: 2
- :caption: Developer Tutorials:
-
- tutorials/rpc
- tutorials/data_encoding
- tutorials/error_monad
- tutorials/michelson_anti_patterns
- tutorials/entering_alpha
- tutorials/protocol_environment
- tutorials/profiling
-
-.. toctree::
- :maxdepth: 2
- :caption: APIs:
-
- README
- api/api-inline
- api/cli-commands
- api/rpc
- api/errors
- api/p2p
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/vendors/tezos-modded/docs/introduction/contributing.rst b/vendors/tezos-modded/docs/introduction/contributing.rst
deleted file mode 100644
index 483dfd36b..000000000
--- a/vendors/tezos-modded/docs/introduction/contributing.rst
+++ /dev/null
@@ -1,100 +0,0 @@
-How to contribute
-=================
-
-Introduction
-------------
-
-The purpose of this document is to help contributors get started with
-the Tezos OCaml codebase.
-
-
-Reporting issues
-----------------
-
-The simplest way to contribute to Tezos is to report issues that you may
-find with the software on `gitlab `__.
-If you are unsure about an issue ask on IRC first and always make sure
-to search the existing issues before reporting a new one.
-Some info that are probably important to include in the description:
-the architecture (e.g. *ARM64*), the operating system (e.g. *Debian
-Stretch*), the network you are connected to (e.g. *Alphanet*), the
-binary or component (e.g. *tezos-node crashes* or *rpc X returns Y
-while Z was expected*).
-
-
-First steps
------------
-
-First, make sure that you are proficient enough in OCaml. The community
-Website http://www.ocaml.org below gives a few pointer for that. In
-particular, we use a lot of functors, and a few GADTs in the codebase,
-so you may want to make sure that you master these advanced concepts.
-
-Then, if you don’t know well about the Lwt library, that’s what you want
-to learn. This library is used extensively throughout the code base, as
-that’s the one we use to handle concurrency, and Tezos is a very
-concurrent system. You can use the `online documentation `__. The chapter on concurrency of `Real World
-OCaml `__ has also been ported to Lwt.
-
-After that, it is a good idea to read the tutorials for
-:ref:`error_monad` and
-:ref:`data_encoding `, two homegrown
-libraries that we use pervasively.
-
-Where to start
---------------
-
-While you familiarize yourself with the basics as suggested above, you
-can have a look at the :ref:`software architecture
-` of Tezos. It will
-give you the main components and their interactions, and links to the
-documentations for the various parts.
-
-Our git workflow
-----------------
-
-First, the repository is https://gitlab.com/tezos/tezos, the github one
-is just a clone that exists for historical reasons. So if you want to
-contribute, simply create an account there.
-
-Then, there are many ways to use Git, here is ours.
-
-We use almost only merge requests to push into master. Meaning, nobody
-should push directly into master. Once a merge request is ready, it is
-reviewed and approved, we merge it using the ``--fast-forward`` option
-of Git, in order to maintain a linear history without merge patches.
-
-For that to work, it means that merge requests must be direct suffixes
-of the master branch. So whenever ``origin/master`` changes, you have to
-rebase your branch on it, so that you patches always sit on top of
-master. When that happens, you may have to edit your patches during the
-rebase, and then use ``push -f`` in your branch to rewrite the history.
-
-We also enforce a few hygiene rules, so make sure your MR respects them:
-
-- Prefer small atomic commits over a large one that do many things.
-- Don’t mix refactoring and new features.
-- Never mix reindentation, whitespace deletion, or other style changes
- with actual code changes.
-- Try as much as possible to make every patch compile, not only the
- last.
-- If you add new functions into a documented interface, don’t forget to
- extend the documentation for your addition.
-- For parts whose specification is in the repository (e.g. Michelson),
- make sure to keep it in sync with the implementation.
-- Try and mimic the style of commit messages, and for non trivial
- commits, add an extended commit message.
-
-As per the hygiene of MRs themselves:
-
-- Give appropriate titles to the MRs, and when non trivial add a
- detailed motivated explanation.
-- Give meaningful and consistent names to branches.
-- Don’t forget to put a ``WIP:`` flag when it is a work in progress
-
-Some extra CI tests are only done on demand for branches other that
-master. You can (should) activate these tests by including keywords in
-the branch name.
-
-- If your MR impacts OPAM packaging, use ``opam`` in the branch name.
-- If your MR updates documentation, use ``doc`` in the branch name.
diff --git a/vendors/tezos-modded/docs/introduction/howtoget.rst b/vendors/tezos-modded/docs/introduction/howtoget.rst
deleted file mode 100644
index 2200af25c..000000000
--- a/vendors/tezos-modded/docs/introduction/howtoget.rst
+++ /dev/null
@@ -1,184 +0,0 @@
-.. _howtoget:
-
-How to get Tezos
-================
-
-In this How To we explain how to get up-to-date binaries to run Tezos
-for each network.
-You can either use the docker images, which is easier, or build from
-sources.
-
-
-Docker images
--------------
-
-The recommended way for running an up-to-date Tezos node is to use the
-docker images that are automatically generated from the GitLab
-repository and published on `DockerHub
-`_.
-The script ``alphanet.sh`` is provided to help download the right
-image for each network and run a simple node.
-Its only requirement is a working installation of `Docker
-`__ and docker compose on a machine with
-architecture **x86_64**.
-Although we only officially support Linux, the script has been tested
-with success in the past on windows/mac/linux.
-
-The same script can be used to run Mainnet, Alphanet or Zeronet, it
-suffices to rename it as it downloads a different image based on its
-name.
-For example, to run Alphanet:
-
-::
-
- wget https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
- chmod +x alphanet.sh
-
-Alternatively, to run Mainnet:
-
-::
-
- wget -O mainnet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
- chmod +x mainnet.sh
-
-In the following we assume you are running Alphanet.
-You are now one step away from a working node:
-
-::
-
- ./alphanet.sh start
-
-This will download the right docker image for your chosen network,
-launch 3 docker containers running the node, the baker and the
-endorser.
-The first launch might take a few minutes to download the
-docker images and synchronize the chain.
-
-Every call to ``alphanet.sh`` will check for updates of the node and
-will fail if your node is not up-to-date. For updating the node, simply
-run:
-
-::
-
- ./alphanet.sh restart
-
-If you prefer to temporarily disable automatic updates, you just have to
-set an environment variable:
-
-::
-
- export TEZOS_ALPHANET_DO_NOT_PULL=yes
-
-See ``./alphanet.sh --help`` for more informations about the
-script. In particular see ``./alphanet.sh client --help`` or the
-:ref:`online manual` for more information about
-the client. Every command to the ``tezos-client`` can be
-equivalently executed using ``./alphanet.sh client``.
-
-
-Build from sources
-------------------
-
-**TL;DR**: Typically you want to do:
-
-::
-
- sudo apt install -y rsync git m4 build-essential patch unzip bubblewrap wget
- wget https://github.com/ocaml/opam/releases/download/2.0.1/opam-2.0.1-x86_64-linux
- sudo cp opam-2.0.1-x86_64-linux /usr/local/bin/opam
- sudo chmod a+x /usr/local/bin/opam
- git clone https://gitlab.com/tezos/tezos.git
- cd tezos
- git checkout alphanet
- opam init --bare
- make build-deps
- eval $(opam env)
- make
- export PATH=~/tezos:$PATH
- source ./src/bin_client/bash-completion.sh
- export TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y
-
-
-Environment
-~~~~~~~~~~~
-
-Currently Tezos is being developed for Linux x86_64, mostly for
-Debian/Ubuntu and Archlinux.
-
-The following OSes are reported to work:
-
-- macOS/x86_64
-- Linux/armv7h (32 bits) (Raspberry Pi3, etc.)
-- Linux/aarch64 (64 bits) (Raspberry Pi3, etc.)
-
-A Windows port is feasible and might be developed in the future.
-
-If ``bubblewrap`` is not available in your distribution you can also
-skip it and init opam with ``--disable-sandbox``.
-
-Get the sources
-~~~~~~~~~~~~~~~
-
-Tezos *git* repository is hosted at `GitLab
-`_. All development happens here. Do
-**not** use our `GitHub mirror `_
-which we don't use anymore and only mirrors what happens on GitLab.
-
-You also need to **choose the branch** of the network you want to connect
-to: *alphanet*, *zeronet* or *mainnet*.
-
-The *master* branch is where code is merged, but there is no test
-network using the master branch directly.
-
-
-Install OPAM
-~~~~~~~~~~~~
-
-To compile Tezos, you need the `OPAM `__
-package manager, version *2.0*. The build script will take
-care of setting-up OPAM, download the right version of the OCaml
-compiler, and so on.
-
-Use ``opam init --bare`` to avoid compiling the OCaml compiler now: it
-will be done in the next step.
-
-
-Install Tezos dependencies with OPAM
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Install the OCaml compiler and the libraries which Tezos depends on:
-
-::
-
- make build-deps
-
-Alternatively, if you want to be able to install extra packages
-(development packages such as `merlin`), you may use the following
-command instead:
-
-::
-
- make build-dev-deps
-
-This command creates a local opam switch ``_opam`` where the right
-version of OCaml is compiled and installed (this takes a while but
-it's only done once).
-
-After OCaml it will start with Tezos dependencies, OPAM is able to
-handle correctly the OCaml libraries but it is not always able to
-handle all external C libraries we depend on. On most system, it is
-able to suggest a call to the system package manager but it currently
-does not handle version check.
-
-Once the dependencies are done we can update opam's environment to
-refer to the new switch and compile the project:
-
-::
-
- eval $(opam env)
- make
-
-Lastly you can also add Tezos binaries to your ``PATH`` variable,
-activate bash autocompletion and after reading the Disclaimer a few
-hundred times you are allowed to disable it with
-``TEZOS_CLIENT_UNSAFE_DISABLE_DISCLAIMER=Y``.
diff --git a/vendors/tezos-modded/docs/introduction/howtorun.rst b/vendors/tezos-modded/docs/introduction/howtorun.rst
deleted file mode 100644
index 7322826c4..000000000
--- a/vendors/tezos-modded/docs/introduction/howtorun.rst
+++ /dev/null
@@ -1,302 +0,0 @@
-.. _howtorun:
-
-How to run Tezos
-================
-
-In this section we discuss how to take part in the protocol that runs
-the network.
-There are two main ways to participate in the consensus, delegating
-your coins and running a delegate.
-To learn more about the protocol refer to :ref:`this section `.
-
-
-Delegating your coins
----------------------
-
-If you don't want to deal with the complexity of running your own
-delegate, you can always take part in the protocol by delegating your
-coins to one.
-
-Implicit accounts cannot have a delegate, so the first step is to
-originate an account, transfer your tez there and set a delegate.
-Notice that an originated account is a special case of a contract
-without code, so it is still necessary to pay for its small storage
-(see `originated_account`).
-
-::
-
- tezos-client originate account alice_del for alice \
- transferring 1000 from alice \
- --delegate bob
-
-As done before, we originate a contract *alice_del* with manager
-*alice* and we fund it with 1kꜩ.
-The interesting part is setting the delegate to *bob*, when
-originating a contract the delegate is not set by default.
-If you already own contracts that are delegatable you can change
-the delegate with the command ``set delegate``.
-
-
-Notice that, by default, an originated account is not *delegatable*,
-which means that you can't change the delegate once the contract is
-originated, even if you initially set a delegate.
-To be able to change the delegate latter, add the
-``--delegatable`` flag.
-
-Notice that only implicit accounts can be delegates, so your delegate
-must be a *tz1* address.
-
-Funds in implicit accounts which are not registered as delegates
-do not participate in baking.
-
-
-Running a delegate
-------------------
-
-A delegate is responsible for baking blocks, endorsing blocks and
-accusing other delegates in case they try to double bake or double
-endorse.
-
-In the network, rights for baking and endorsing are randomly assigned
-to delegates proportionally to the number of rolls they have been
-delegated.
-A roll is just a block of 10kꜩ and all computations with rolls are
-rounded to the nearest lower integer e.g. if you have 16kꜩ it amounts
-to 1 roll.
-
-When you obtain coins from :ref:`the faucet`, if you
-are lucky to obtain more than one roll, you can register a delegate
-using this identity.
-Otherwise, you need to ask the faucet for more accounts, originate an
-account for each one and delegate them to the first.
-
-Deposits and over-delegation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When baking or endorsing a block, a *security deposit* (or *bond*) is
-frozen for ``preserved_cycles`` cycles from the account of the
-delegate.
-Hence a delegate must have enough funds to be able to pay security
-deposits for all the blocks it can potentially bake/endorse during
-``preserved_cycles``.
-The current deposits are *512ꜩ* for baked block and *64ꜩ* for
-endorsement.
-Note that being delegated coins doesn't mean that a delegate can spend
-them, they only add up to its rolls count while all the deposits must
-come from the delegate's account.
-
-If a delegate runs out of funds to deposit it won't be able to bake or
-endorse, other than being a missed opportunity for them this has also
-negative consequences on the network.
-Missing baking slots slows the network, as it is necessary to wait one
-minute for the baker at priority 2 to bake, while missing endorsements
-reduce the fitness of the chain, making it more susceptible to forks.
-Running out of funds can happen if a delegate is *over-delegated*,
-that is if the amount of rolls it was delegate is disproportionate
-with respect to its available funds.
-It is the responsibility of every delegator to make sure a delegate is
-not already over-delegated (a delegate cannot refuse a delegation) and
-each delegate should plan carefully its deposits.
-
-.. _expected_rights:
-
-Expected rights, deposits and rewards
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Let's assume we have 1 roll, we want to estimate our chances to bake
-or endorse in order to prepare the funds for our deposits.
-Our chances depend on how many rolls are currently active in the
-network, once we know that we can estimate how many blocks and
-endorsements we could be assigned in a cycle.
-The number of active rolls can be computed with two RPCs, first we
-list all the active delegates with ``delegates?active``, then we sum
-all their ``stacking_balance`` and we simply divide by the size of a
-roll, 10kꜩ.
-At the time of writing, on Betanet the number of active rolls is ~30k
-so for each block we know that the chance that we get selected for
-baking is ``1/30k`` while for endorsing is 32 times that.
-Given that every draw is with replacement, the distribution that
-describes our chances of being selected is the binomial with
-probability of success ``p=1/30k``.
-The distribution has another parameter ``n`` for the number of times
-we draw, in our case in a cycle the draws for baking are ``n_b =
-4096`` while for endorsing are ``n_e = 4096 * 32``.
-Moreover we could extend ``n`` to cover ``preserved_cycles = 5``.
-Once we have ``p`` and ``n``, the expected number of times that we
-might get selected is ``p * n`` (the mean of the distribution).
-Over many cycles our chances will fall around the mean, in some cycles
-we might get unlucky and be assigned fewer rights, but in some cycles we might
-get lucky and be assigned more rights!
-Clearly we would like to plan ahead and have enough deposits to cover
-also the "lucky" cycles so we need to compute a sort of "maximum"
-number of rights that is safe for `most cases`.
-We can compute this maximum using the inverse of Cumulative
-Distribution Function of the Binomial where `most cases` is a value of
-confidence that we can put to 95%.
-There a simple `Python
-script `_
-that does the computation for us and returns the deposits and rewards,
-expected and maximum, for a cycle and for `preserved_cycles`.
-
-::
-
- prob success 3.333333e-05
- confidence 0.95
- ----------one-cycle--------------------
- blocks
- mean 0.14
- max 1.00
- endorsements
- mean 4.37
- max 8.00
- deposits
- mean 69.91 + 279.62
- max 512.00 + 512.00
- rewards
- mean 2.18 + 8.74
- max 16.00 + 16.00
- ----------preserved-cycles-------------
- blocks
- mean 0.68
- max 2.00
- endorsements
- mean 21.85
- max 30.00
- deposits
- mean 349.53 + 1398.10
- max 1024.00 + 1920.00
- rewards
- mean 10.92 + 43.69
- max 32.00 + 60.00
-
-As a rule of thumb if we want to have a very high confidence that we
-won't miss any opportunity we should have around ~3kꜩ for deposits,
-on the other hand the expected returns will probably be around ~10ꜩ per cycle.
-
-After ``preserved_cycles``, not only the delegate takes back control of
-its frozen deposits but it also receives the rewards for its hard work
-which amount to 16ꜩ to bake a block and ``ꜩ2 / `` for
-endorsing a block.
-Additionally a baker also receives the fees of the operations it
-included in its blocks.
-While fees are unfrozen after ``preserved_cycles`` like deposits and
-rewards, they participate in the staking balance of the delegate
-immediately after the block has been baked.
-
-
-Register and check your rights
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In order to run a delegate you first need to register as one using
-your implicit account:
-
-::
-
- tezos-client register key bob as delegate
-
-Once registered, you need to wait ``preserved_cycles + 2 = 7`` cycles
-for your rights to be considered.
-
-There is a simple rpc that can be used to check your rights for every
-cycle, up to 5 cycles in the future.
-
-::
-
- tezos-client rpc get /chains/main/blocks/head/helpers/baking_rights\?cycle=300\&delegate=tz1_xxxxxxxxxxx\&max_priority=2
-
-Sometimes a delegate skips its turn so it is worth considering also
-baking rights at priority 2 like in the example above.
-There is no priority for endorsements, every missed endorsement is
-lost.
-
-Inactive delegates
-~~~~~~~~~~~~~~~~~~
-
-If a delegate doesn't show any sign of activity for `preserved_cycles`
-it is marked **inactive** and its rights are removed.
-This mechanism is important to remove inactive delegates and reallocate
-their rights to the active ones so that the network is always working
-smoothly.
-Normally even a baker with one single roll should perform enough
-operations during 5 cycles to remain active.
-If for some reason you delegate is marked inactive you can reactivate
-it simply by re-registering again like above.
-
-Baker
-~~~~~
-
-The baker is a daemon that once connected to an account, computes the
-baking rights for that account, collects transactions from the mempool
-and bakes a block.
-Note that the baker is the only program that needs direct access to
-the node data directory for performance reasons.
-
-Let's launch the daemon pointing to the standard node directory and
-baking for user *bob*:
-
-::
-
- tezos-baker-alpha run with local node ~/.tezos-node bob
-
-Endorser
-~~~~~~~~
-
-The endorser is a daemon that once connected to an account, computes
-the endorsing rights for that account and, upon reception of a new
-block, verifies the validity of the block and emits an endorsement
-operation.
-It can endorse for a specific account or if omitted it endorses for
-all accounts.
-
-::
-
- tezos-endorser-alpha run
-
-Accuser
-~~~~~~~
-
-The accuser is a daemon that monitors all blocks received on all
-chains and looks for:
-
-* bakers who signed two blocks at the same level
-* endorsers who injected more than one endorsement operation for the
- same baking slot (more details :ref:`here`)
-
-Upon finding such irregularity, it will emit respectively a
-double-baking or double-endorsing denunciation operation, which will
-cause the offender to loose its security deposit.
-
-::
-
- tezos-accuser-alpha run
-
-Remember that having two bakers or endorsers running connected to the
-same account could lead to double baking/endorsing and the loss of all
-your bonds.
-If you are worried about availability of your node when is its turn to
-bake/endorse there are other ways than duplicating your credentials.
-**Never** use the same account on two daemons.
-
-
-Docker
-~~~~~~
-
-The docker image runs the daemons by default for all your keys.
-To know if you baked, just run:
-
-::
-
- ./alphanet.sh baker log
- ./alphanet.sh endorser log
-
-You should see lines such as:
-
-::
-
- Injected block BLxzbB7PBW1axq for bootstrap5 after BLSrg4dXzL2aqq (level 1381, slot 0, fitness 00::0000000000005441, operations 21)
-
-Or:
-
-::
-
- Injected endorsement for block 'BLSrg4dXzL2aqq' (level 1381, slot 3, contract bootstrap5) 'oo524wKiEWBoPD'
diff --git a/vendors/tezos-modded/docs/introduction/howtouse.rst b/vendors/tezos-modded/docs/introduction/howtouse.rst
deleted file mode 100644
index 870450c40..000000000
--- a/vendors/tezos-modded/docs/introduction/howtouse.rst
+++ /dev/null
@@ -1,481 +0,0 @@
-.. _howtouse:
-
-How to use Tezos
-================
-
-This How To illustrates the use of the various Tezos binaries as well
-as some concepts about the network.
-
-The binaries
-------------
-
-After a successful compilation, you should have the following binaries:
-
-- ``tezos-node``: the tezos daemon itself;
-- ``tezos-client``: a command-line client and basic wallet;
-- ``tezos-admin-client``: administration tool for the node;
-- ``tezos-{baker,endorser,accuser}-alpha``: daemons to bake, endorse
- and accuse on the Tezos network (see :ref:`howtorun`);
-- ``tezos-signer``: a client to remotely sign operations or blocks
- (see :ref:`signer`);
-
-Note that Alphanet and Zeronet only support the last version of the
-protocol which is always called `alpha` while Betanet must also
-support all past protocols.
-For this reason the name of the 3 daemons in Betanet contains the
-incremental number and the partial hash of the protocol they are bound
-to, such as ``tezos-{baker,endorser,accuser}-002-PsYLVpVv``.
-
-
-Read The Friendly Manual
-------------------------
-
-The manual of each binary can be obtained with the command ``man`` and
-the verbosity can be increased with ``-v``.
-To use one specific command, type the command without arguments to see
-possible completions and options.
-It is also possible to search a keyword in the manual with ``man
-keyword``.
-The full documentation is also available online :ref:`client_manual`.
-
-::
-
- tezos-client man -v 3
- tezos-client transfer
- tezos-client man set
-
-
-Node
-----
-
-The node is effectively the Tezos blockchain and it has two main
-functions: running the gossip network and the updating the context.
-The gossip network is where all Tezos nodes exchange blocks and
-operations with each other (see :ref:`tezos-admin-client` to monitor
-p2p connections).
-Using this peer-to-peer network an operation originated by a user, can
-hop several times through other nodes until it finds its way in a
-block baked by a baker.
-Using the blocks it receives on the gossip network the shell also
-keeps up to date the current `context`, that is the full state of
-the blockchain shared by all peers.
-Approximately every minute a new block is created and, when the shell
-receives it, it applies each operation in the block to its current
-context and computes a new context.
-The last block received on a chain is also called the `head` of that
-chain.
-Each new head is then advertised by the node to its peers,
-disseminating this information to build a consensus across the
-network.
-
-Other than passively observing the network, your node can also inject
-its own new operations when instructed by the ``tezos-client`` and even
-send new blocks when guided by the ``tezos-baker-alpha``.
-The node has also a view of the multiple chains that may exist
-concurrently and selects the best one based on its fitness (see
-:ref:`proof-of-stake`).
-
-
-Node identity
-~~~~~~~~~~~~~
-
-First we need to generate a new identity in order for the node to
-connect to the network:
-
-::
-
- tezos-node identity generate
-
-The identity comprises a pair of cryptographic
-keys that nodes use to encrypt messages sent to each other, and an
-antispam-PoW stamp proving that enough computing power has been
-dedicated to creating this identity.
-Note that this is merely a network identity and it is not related in
-any way to a Tezos address on the blockchain.
-
-
-Storage
-~~~~~~~
-
-All blockchain data is stored under ``$HOME/.tezos-node/``.
-If for some reason your node is misbehaving or there has been an
-upgrade of the network, it is safe to remove this directory, it just
-means that your node will take some time to resync the chain.
-You can keep ``identity.json`` if it takes a long time for you to
-compute it and only remove the ``store`` and ``context`` directories.
-
-If you are also running a baker make sure that it has access to the
-``.tezos-node`` directory of the node.
-
-
-RPC interface
-~~~~~~~~~~~~~
-
-The only interface to the node is through Json RPC calls and it is disabled by
-default. A more detailed documentation can be found in the :ref:`RPC index.
-` The RPC interface must be enabled in order for the clients
-to communicate with the node, but is should not be publicly accessible on the
-internet. With the following command it is available uniquely on the
-`localhost` address of your machine, on the default port ``8732``.
-
-::
-
- tezos-node run --rpc-addr 127.0.0.1
-
-The node listens by default on port ``19732`` so it is advisable to
-open incoming connections to that port.
-You can read more about the :ref:`node configuration ` and
-its :ref:`private mode `.
-
-
-Client
-------
-
-Tezos client can be used to interact with the node, it can query its
-status or ask the node to perform some actions.
-For example after starting your node you can check if it has finished
-synchronizing using
-
-::
-
- tezos-client bootstrapped
-
-This call will hang and return only when the node is synchronized.
-We can now check what is the current timestamp of the head of the
-chain (time is in UTC so it may differ from your local):
-
-::
-
- tezos-client get timestamp
-
-
-A simple wallet
-~~~~~~~~~~~~~~~
-
-The client is also a basic wallet and after the activation above you
-will notice that the directory ``.tezos-client`` has been populated with
-3 files ``public_key_hashs``, ``public_keys`` and ``secret_keys``.
-The content of each file is in json and keeps the mapping between
-aliases (``alice`` in our case) and what you would expect from the name
-of the file.
-Secret keys are stored on disk encrypted with a password except when
-using a hardware wallet (see :ref:`ledger`).
-An additional file ``contracts`` contains the addresses of `originated
-contracts`, which have the form *KT1…*.
-
-We can for example generate a new pair of keys, which can used locally
-with the alias *bob*:
-
-::
-
- $ tezos-client gen keys bob
-
-Tezos support three different ECC schemes: *Ed25519*, *secp256k1* (the
-one used in Bitcoin), and *P-256* (also called *secp256r1*). The two
-latter curves have been added for interoperability with Bitcoin and
-Hardware Security Modules (*HSMs*) mostly. Unless your use case
-require those, you should probably use *Ed25519*. We use a verified
-library for Ed25519, and it is generally recommended over other curves
-by the crypto community, for performance and security reasons.
-
-Make sure to make a back-up of this directory and that the password
-protecting your secret keys is properly managed.
-
-For more advanced key management we offer :ref:`ledger support
-` and a :ref:`remote signer`.
-
-
-.. _faucet:
-
-Get free tez
-~~~~~~~~~~~~
-
-In order to test the networks and help users get familiar with the
-system, on Zeronet and Alphanet you can obtain free tez from a
-`faucet `__.
-
-This will provide a wallet in the form of a JSON file
-``tz1__xxxxxxxxx__.json``, that can be activated with the following
-command:
-
-::
-
- tezos-client activate account alice with "tz1__xxxxxxxxx__.json"
-
-If you use the ``alphanet.sh`` script, you should prefix the file
-with ``container:`` in order to copy it into the docker image:
-``./alphanet.sh client activate account alice with "container:tz1__xxxxxxxxx__.json"``
-
-Let's check the balance of the new account with:
-
-::
-
- tezos-client get balance for alice
-
-Please preserve the JSON file, after each reset of Zeronet or
-Alphanet, you will have to reactivate the wallet.
-
-Please drink carefully and don't abuse the faucet: it only contains
-30,000 wallets for a total amount of ꜩ760,000,000.
-
-
-Transactions
-~~~~~~~~~~~~
-
-Let's transfer some tez to the new account:
-
-::
-
- tezos-client transfer 1 from alice to bob --fee 0.05
-
-The ``transfer`` command returns a receipt with all the details of the
-transaction, including its hash, and then waits for the operation to
-be included in one block.
-If you want to simulate a transaction without actually sending it to
-the network you can use the ``--dry-run`` option.
-As in any blockchain it is advisable to wait several blocks to
-consider the transaction as final, for an important operation we
-advice to wait 60 blocks.
-We can do that with:
-
-::
-
- tezos-client wait for to be included
-
-In the rare case when an operation is lost, how can we be sure that it
-will not be included in any future block and re-emit it?
-After 60 blocks a transaction is considered invalid and can't be
-included anymore in a block.
-Furthermore each operation has a counter (explained in more detail
-later) that prevents replays so it is usually safe to re-emit an
-operation that seems lost.
-
-
-Receipts for operations and blocks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-After an operation the client prints a `receipt` that recapitulates
-the effects of the operation on the blockchain.
-It is possible to review the receipt of a transaction with:
-
-::
-
- tezos-client rpc get /chains/main/blocks/head/operations
-
-A manager operation, such as a transaction, has 3 important
-parameters: counter, gas and storage limit.
-The counter belongs to each account, it increases at each operation
-signed by that account and enforces some good intuitive properties:
-
-- each operation is unique: for example if we perform twice the same
- transfer from *alice* to *bob*, even if all the data are the
- same the counter will be different.
-- each operation is applied once: for example if the transfer above
- reaches two peers and they both send it to a third peer, it will not
- apply the transaction twice.
-- operations are applied in order.
-- all previous operations have been applied: if we emit operation *n*
- and *n+1*, and *n* gets lost then *n+1* cannot be applied.
-
-Additionally each operation needs to declare a gas and storage limit,
-if an operation consumes more than these limits it will fail.
-Later we'll learn more about the gas and storage model.
-
-Another interesting field of the receipts are the `balance updates`
-showing which account was credited or debited.
-For the transaction above the updates are symmetrical, *alice* is
-debited 1ꜩ and *bob* is credited the same amount.
-The same is true for the fees with the difference that the baker is
-credited and, more importantly, it is not credited immediately on its
-main account but on its frozen fees account, hence the category
-`freezer`.
-Each delegate has 3 frozen accounts: `deposits`, `fees` and `rewards`.
-They are frozen because the delegate can't use them for now, but only
-after a number cycles.
-
-It is also possible to review the receipt of the whole block:
-
-::
-
- tezos-client rpc get /chains/main/blocks/head/metadata
-
-Here we always see the deposit that the baker had to put down to bake
-the block, which is again a debit on its main account paired with a
-credit on its `deposits` account, and the creation of a reward, which
-is a single credit to its `rewards` account.
-
-An interesting block receipt is the one produced at the end of a
-cycle as many delegates receive back part of their unfrozen accounts.
-
-
-.. _originated_accounts:
-
-Originated accounts and Contracts
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In Tezos there are two kinds of accounts: *implicit* and *originated*.
-The implicit accounts are the *tz1* we have used up to now and to
-create them if suffices to have a pair of keys and to transfer some
-funds to the public key hash.
-Originated accounts have addresses *KT1* and are created through an
-origination operation.
-One reason to originate an account is to delegate your tokens
-(see more :ref:`here. `).
-The other main reason is that an originated account can also have
-Michelson code, in which case it is called a *contract*.
-
-Let's originate our first contract and call it *id*:
-
-::
-
- tezos-client originate contract id for alice \
- transferring 1 from alice \
- running ./src/bin_client/test/contracts/id.tz \
- --init '"hello"'
-
-We set *alice* as manager, a 1ꜩ starting balance generously provided
-by *alice* and the code from the ``id.tz`` Michelson program which
-is just the identity.
-Every program declares in its first 2 lines the type of its parameter
-and storage, for *id* they are both strings so we initialize the
-contract with the string ``"hello"`` (the extra quotes are to avoid
-the shell expansion).
-
-Gas and storage cost model
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A quick look at the balance updates on the receipt shows that on top of
-funding the contract with 1ꜩ, *alice* was also charged an extra cost
-that is burnt.
-This cost comes from the *storage* and is shown in the line
-``Paid storage size diff: 46 bytes``, 41 for the contract and 5 for
-the string ``"hello"``.
-Given that a contract saves its data on the public blockchain that
-every node stores, it is necessary to charge a fee per byte to avoid
-abuse and encourage lean programs.
-
-Let's see what calling a program with a new argument would look like
-with the ``--dry-run`` option:
-
-::
-
- tezos-client transfer 0 from alice to id --arg '"world"' --dry-run
-
-The transaction would successfully update the storage but this time it
-wouldn't cost us anything more than the fee, the reason is that the
-storage for ``"world"`` is the same as for ``"hello"``, which has
-already been paid for.
-To store more we'll need to pay more, you can try by passing a longer
-string.
-
-The other cost associated with running contracts is the *gas*, which
-measures *how long* does a program take to compute.
-Contrary to storage there is no cost per gas unit, a transfer can
-require as much gas as it wants, however a baker that has to choose
-among several transactions is much more likely to include a low gas
-one because it's cheaper to run and validate.
-At the same time bakers also give priority to high fee transactions.
-This means that there is an implicit cost for gas that is related to
-the fee offered versus the gas and fees of other transactions.
-
-If you are happy with the gas and storage of your transaction you can
-run it for real, however it is always a good idea to set explicit
-limit for both. The transaction fails if the limits are passed.
-
-::
-
- tezos-client transfer 0 from alice to id --arg '"world"' \
- --gas-limit 1475 \
- --storage-limit 46
-
-A baker is more likely to include an operation with lower gas and
-storage limits because it takes less resources to execute so it is in
-the best interest of the user to pick limits that are as close as
-possible to the actual use.
-
-More test contracts can be found in directory
-:src:`src/bin_client/test/contracts/`.
-An advanced documentation of the smart contract language is available
-:ref:`here`.
-For details and examples, see also https://www.michelson-lang.com/
-
-
-Validation
-~~~~~~~~~~
-
-The node allows to validate an operation before submitting it to the
-network by simply simulating the application of the operation to the
-current context.
-In general if you just send an invalid operation e.g. sending more
-tokens that what you own, the node will broadcast it and when it is
-included in a block you'll have to pay the usual fee even if it won't
-have an affect on the context.
-To avoid this case the client first asks the node to validate the
-transaction and then sends it.
-
-The same validation is used when you pass the option ``--dry-run``,
-the receipt that you see is actually a simulated one.
-
-Another important use of validation is to determine gas and storage
-limits.
-The node first simulates the execution of a Michelson program and
-takes trace of the amount of gas and storage.
-Then the client sends the transaction with the right limits for gas
-and storage based on that indicated by the node.
-This is why we were able to submit transactions without specifying
-this limits, they were computed for us.
-
-More information on validation can be found :ref:`here. `
-
-It's RPCs all the way down
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The client communicates with the node uniquely through RPC calls so
-make sure that the node is listening and that the ports are
-correct.
-For example the ``get timestamp`` command above is a shortcut for:
-
-::
-
- tezos-client rpc get /chains/main/blocks/head/header/shell
-
-The client tries to simplify common tasks as much as possible, however
-if you want to query the node for more specific informations you'll
-have to resort to RPCs.
-For example to check the value of important constants in Tezos, which
-may differ between Betanet, Alphanet and Zeronet, you can use:
-
-::
-
- tezos-client rpc get /chains/main/blocks/head/context/constants | jq
- {
- "proof_of_work_nonce_size": 8,
- "nonce_length": 32,
- "max_revelations_per_block": 32,
- "max_operation_data_length": 16384,
- "preserved_cycles": 5,
- "blocks_per_cycle": 4096,
- "blocks_per_commitment": 32,
- "blocks_per_roll_snapshot": 256,
- "blocks_per_voting_period": 32768,
- "time_between_blocks": [
- "60",
- "75"
- ],
- "endorsers_per_block": 32,
- "hard_gas_limit_per_operation": "400000",
- "hard_gas_limit_per_block": "4000000",
- "proof_of_work_threshold": "70368744177663",
- "tokens_per_roll": "10000000000",
- "michelson_maximum_type_size": 1000,
- "seed_nonce_revelation_tip": "125000",
- "origination_burn": "257000",
- "block_security_deposit": "48000000",
- "endorsement_security_deposit": "6000000",
- "block_reward": "0",
- "endorsement_reward": "0",
- "cost_per_byte": "1000",
- "hard_storage_limit_per_operation": "60000"
- }
-
-You can find more info in the :ref:`RPCs' page. `
diff --git a/vendors/tezos-modded/docs/introduction/support.rst b/vendors/tezos-modded/docs/introduction/support.rst
deleted file mode 100644
index 517467915..000000000
--- a/vendors/tezos-modded/docs/introduction/support.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. _support:
-
-Technical Support
-=================
-
-If you need help understanding how the Tezos protocol works or if you
-have technical questions about the software, here are a few resources
-to find answers.
-
-- `This documentation! `_
- Make sure to go through this technical documentation before asking
- elsewhere, there is also a searchbox on the top left corner.
-- Tezos `Stack Exchange `_ is live
- (still in beta). If you don't find the answers you are looking for,
- feel free to ask questions!
-- There is a sub-reddit at https://www.reddit.com/r/tezos/ that is the
- main meeting point for the Tezos community, for technical,
- economical and just random questions. They also have a nicely
- curated list of resources.
-- For anything baking related `Obsidian Systems
- `_ is running a dedicated Slack channel,
- contact them to get access.
-- There is a *#tezos* IRC channel on *freenode* that is reserved for
- technical discussions and is always very active.
-- There is a matrix channel *Tezos* that you can join `here `_.
diff --git a/vendors/tezos-modded/docs/introduction/various.rst b/vendors/tezos-modded/docs/introduction/various.rst
deleted file mode 100644
index 12e5a24a5..000000000
--- a/vendors/tezos-modded/docs/introduction/various.rst
+++ /dev/null
@@ -1,613 +0,0 @@
-Various
-=======
-
-.. _activate_fundraiser_account:
-
-Activate fundraiser account - Mainnet
--------------------------------------
-
-If you took part in the fundraiser you can activate your account for
-the Mainnet on https://check.tezos.com/.
-This feature is also included in some wallets.
-If you have any question or issue refer to that page or to the `Tezos
-foundation `_ for support.
-
-You may also use ``tezos-client`` to activate your account, **be
-warned that you should have a very good understanding of key
-management in Tezos and be familiar with the command-line.**
-The first step is to recover your private key using the following
-command which will ask for:
-
-- the email address used during the fundraiser
-- the 14 words mnemonic of your paper wallet
-- the password used to protect the paper wallet
-
-::
-
- tezos-client import fundraiser key alice
-
-Once you insert all the required information, the client computes
-your secret key and it asks to create a new password to store your
-secret key on disk encrypted.
-
-If you haven't already activated your account on the website, you can
-use this command with the activation code obtained from the Tezos
-foundation.
-
-::
-
- tezos-client activate fundraiser account alice with
-
-Like explained above, your keys are stored under ``~/.tezos-client``.
-We strongly advice you to first **make a backup** and then
-transfer your tokens to a new pair of keys imported from a ledger (see
-`ledger`).
-
-Check the balance with:
-
-::
-
- tezos-client get balance for alice
-
-
-.. _tezos-admin-client:
-
-Admin Client
-------------
-
-The admin client gives access to more commands to interact with the
-peer-to-peer layer in order to:
-
-- check the status of the connections
-- force connections to known peers
-- ban/unban peers
-
-A useful command to debug a node that is not syncing is:
-
-::
-
- tezos-admin-client p2p stat
-
-
-.. _ledger:
-
-Ledger support
---------------
-
-**Disclaimer:** Ledger support is still in development, **the current app
-doesn't show all the needed information** for signing securely.
-Check frequently for updates.
-
-It is possible and advised to use a hardware wallet to manage your
-keys, Tezos' client supports the Ledger Nano S provided that you have
-the Tezos app installed.
-The app is developed by Obsidian Systems and they provide a comprehensive
-`tutorial on how to install it.
-`_
-
-Ledger Manager
-~~~~~~~~~~~~~~
-
-The preferred way to set up your Ledger is to install `Ledger
-Live
-`_.
-On Linux make sure you correctly set up your `udev` rules as explained
-`here `_.
-Connect your ledger, unlock it and go the dashboard.
-In Ledger Live `install Tezos Wallet` from the applications list and open it on the
-device.
-
-
-Tezos Wallet app
-~~~~~~~~~~~~~~~~
-
-Now on the client we can import the keys (make sure the device is
-in the Tezos Wallet app):
-
-::
-
- ./tezos-client list connected ledgers
-
-You can follow the instructions to import the ledger private key and
-you can choose between the root or a derived address.
-We can confirm the addition by listing known addresses.
-
-::
-
- ./tezos-client import secret key my_ledger ledger://tz1XXXXXXXXXX
- ./tezos-client list known addresses
-
-Optional: we can check that our ledger signs correctly using the
-following command and confirming on the device:
-
-::
-
- tezos-client show ledger path ledger://tz1XXXXXXXXXX
-
-The address can now be used as any other with the exception that
-during an operation the device will prompt you to confirm when it's
-time to sign an operation.
-
-
-Tezos Baking app
-~~~~~~~~~~~~~~~~
-
-In Ledger Live there is also a `Tezos Baking` app which allows a
-delegate to sign non-interactively e.g. there is no need to
-manually sign every block or endorsement.
-The application however is restricted to sign exclusively blocks and
-endorsement operations; it is not possible to sign for example a
-transfer.
-Furthermore the application keeps track of the last level baked and allows
-only to bake for increasing levels.
-This prevents signing blocks at levels below the latest
-block signed.
-
-If you have tried the app on Alphanet or Zeronet and want to change
-network you might need to reset this level with the command:
-
-::
-
- tezos-client set ledger high watermark for ledger://tz1XXXXXXXXXX to 0
-
-
-.. _private-mode:
-
-Private node
-------------
-
-The node can be set in private mode with the option ``--private-mode``
-so that:
-
-- it doesn't connects to any peer other than those provided with
- ``--peer`` or in bootstrap-peers
-- the peers connected to a private node don't include it in the list
- of peers sent to their neighborhood
-
-This feature is especially useful to hide a sensitive node that signs
-operations.
-
-For example we could have a set up with two nodes, a private one
-connected uniquely with a public one.
-The public node runs on a VPS, connects normally to the network and
-keeps an up to date state of the network while the private node runs at
-your home and is in charge of injecting and signing operations with a
-hardware wallet.
-
-::
-
- tezos-node run --rpc-addr [::] --private-mode \
- --no-bootstrap-peers \
- --bootstrap-threshold=1 \
- --connections 1 \
- --peer
-
-
-.. _signer:
-
-Signer
-------
-
-Another solution to decouple the node from the signing process is to
-use the *remote signer*.
-Among the signing scheme supported by the client, that we can list
-with ``tezos-client list signing schemes``, there are ``unix``,
-``tcp``, ``http`` and ``https``.
-These schemes send signing requests over their respective
-communication channel towards the ``tezos-signer``, which can run on a
-different machine that stores the secret key.
-
-In our home server we can generate a new key pair (or import one from a
-:ref:`Ledger`) and launch a signer that signs operations using these
-keys.
-The new keys are store in ``$HOME/.tezos-signer`` in the same format
-as ``tezos-client``.
-On our internet facing vps we can then import a key with the address
-of the signer.
-
-::
-
- home~$ tezos-signer gen keys alice
- home~$ cat ~/.tezos-signer/public_key_hashs
- [ { "name": "alice", "value": "tz1abc..." } ]
- home~$ tezos-signer launch socket signer -a home-ip
-
- vps~$ tezos-client import secret key alice tcp://home-ip:7732/tz1abc...
-
-Every time the client on *vps* needs to sing an operation for
-*alice*, it sends a signature request to the remote signer on
-*home*.
-Note that this setup alone is not secure, **the signer accepts
-requests from anybody and happily signs any transaction!**
-
-Secure the connection
-~~~~~~~~~~~~~~~~~~~~~
-
-Improving the security of the communication channel can be done at the
-system level, setting up a tunnel with ``ssh`` or ``wireguard``
-between *home* and *vps*, otherwise the signer already provides an
-additional protection.
-
-With the option ``--require-authentication`` the signer requires the
-client to authenticate before signing any operation.
-First we create a new key on the *vps* and then import it as an
-authorized key on *home* where it is stored under
-``.tezos-signer/authorized_keys`` (similarly to ``ssh``).
-Note that this key is only used to authenticate the client to the
-signer and it is not used as a Tezos account.
-
-::
-
- vps~$ tezos-client gen keys vps
- vps~$ cat ~/.tezos-client/public_keys
- [ { "name": "vps",
- "value":
- "unencrypted:edpk123456789" } ]
-
- home~$ tezos-signer add authorized key edpk123456789 --name vps
- home~$ tezos-signer --require-authentication launch socket signer -a home-ip
-
-All request are now signed with the *vps* key thus you are
-guaranteed authenticity and integrity.
-This set up **does not guarantee confidentiality**, an evesdropper can
-see the transactions that you sign but on a public blockchain this is
-less of a concern.
-You can still use the ``https`` scheme or the tunnel to encrypt your
-traffic.
-
-
-.. _sandboxed-mode:
-
-Use sandboxed mode
-------------------
-
-To run a ‘localhost-only’ instance of a Tezos network, we provide two
-helper scripts:
-
-- ``./src/bin_node/tezos-sandboxed-node.sh``
-- ``./src/bin_client/tezos-init-sandboxed-client.sh``
-
-
-Run a sandboxed node
-~~~~~~~~~~~~~~~~~~~~
-
-For instance, if you want to run local network with two nodes, in a
-first terminal, the following command will initialize a node listening
-for peers on port ``19731`` and listening for RPC on port ``18731``.
-
-::
-
- ./src/bin_node/tezos-sandboxed-node.sh 1 --connections 1
-
-This node will store its data in a temporary directory
-``/tmp/tezos-node.xxxxxxxx`` which will be removed when the node is
-stopped.
-The option ``--connections`` is just to remove the spurious “Too few
-connections” warnings by lowering the number of expected connection.
-
-To launch the second node, just run the following command, it will
-listen on port ``19739`` and ``18739``:
-
-::
-
- ./src/bin_node/tezos-sandboxed-node.sh 9 --connections 1
-
-You might replace ``1`` or ``9`` by any number in between if you want to
-run more than two nodes.
-
-
-Use the sandboxed client
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once your node is running, open a new terminal and initialize the
-“sandboxed” client data in a temporary directory:
-
-::
-
- eval `./src/bin_client/tezos-init-sandboxed-client.sh 1`
-
-It also define in the current shell session an alias ``tezos-client``
-preconfigured for communicating with the same-numbered node.
-
-When you bootstrap a new network, the network is initialized with a
-dummy economic protocol, called `genesis`. If you want to run the same
-protocol than the alphanet, ``init-sandboxed-client`` also defines an
-alias ``tezos-activate-alpha``, that you need to execute once for
-activating the whole network.
-For instance:
-
-::
-
- $ tezos-client rpc get /chains/main/blocks/head/metadata
- "next_protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"
- $ tezos-activate-alpha
- Injected BMV9KnSPE1yw
- $ tezos-client rpc get /chains/main/blocks/head/metadata
- "protocol": "Ps9mPmXaRzmzk35gbAYNCAw6UXdE2qoABTHbN2oEEc1qM7CwT9P"
-
-We now have the possibility to send transactions to the sandboxed network.
-As the genesis block used to initialize the sandboxed network differs from the
-one used in Alphanet and Zeronet, it is not possible to activate
-accounts obtained from the faucet. However, we can use the
-preconfigured accounts which can be listed with:
-
-::
-
- $ tezos-client list known addresses
-
- activator: tz1TGu6TN5GSez2ndXXeDX6LgUDvLzPLqgYV (unencrypted sk known)
- bootstrap5: tz1ddb9NMYHZi5UzPdzTZMYQQZoMub195zgv (unencrypted sk known)
- bootstrap4: tz1b7tUupMgCNw2cCLpKTkSD1NZzB5TkP2sv (unencrypted sk known)
- bootstrap3: tz1faswCTDciRzE4oJ9jn2Vm2dvjeyA9fUzU (unencrypted sk known)
- bootstrap2: tz1gjaF81ZRRvdzjobyfVNsAeSC6PScjfQwN (unencrypted sk known)
- bootstrap1: tz1KqTpEZ7Yob7QbPE4Hy4Wo8fHG8LhKxZSx (unencrypted sk known)
-
-We can run the following command to transfer some Tez from one account to
-another:
-
-::
-
- $ tezos-client transfer 42 from bootstrap1 to bootstrap2 &
- ...
- Waiting for the operation to be included...
-
-You will notice that this command doesn't terminate (hence the ``&``),
-as usual it is waiting for the network to include the transaction in a
-block.
-Given that we are in a sandbox we need to bake a block ourselves and
-we can do so with the following command:
-
-::
-
- $ tezos-client bake for bootstrap1
-
-If the previous transaction is valid, the operation is included in the
-chain and the transfer terminates returning the usual ticket.
-Note that the ``bake for`` command of the client is exclusively for
-testing purposes, all baking should be done using the ``tezos-baker``
-binary.
-
-
-Tune protocol alpha parameters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The ``tezos-active-alpha`` alias use parameters from
-``scripts/protocol_parameters.json`` to activate protocol alpha. It can
-be useful to tune these parameters when you need to debug something,
-for example, change the number of blocks per cycle, the time between
-blocks, etc.
-
-
-.. _node-conf:
-
-Configuration options for the node
-----------------------------------
-
-::
-
- ./tezos-node config init
-
-This will initialize a configuration file for the node in
-`$HOME/.tezos-node/config.json`, using default values. It only
-specifies that the node will listen to incoming connections on socket
-address ``[::]:9732``.
-
-The easiest way to amend this default configuration is to use
-
-::
-
- # Update the config file
- ./tezos-node config update <…>
- # Start from an empty cfg file
- ./tezos-node config reset <…>
-
-
-All blockchain data is stored under ``$HOME/.tezos-node/``. You can
-change this by doing `./tezos-node config update --data-dir
-`.
-
-To run multiple nodes on the same machine, you can duplicate and edit
-``$HOME/.tezos-node/config.json`` while making sure they don't share
-the same ``data-dir``. Then run your node with `./tezos-node
-run --config-file=`.
-
-Here is an example configuration file with all parameters specified.
-Most of the time it uses default values, except for cases where the
-default is not explanatory enough (i.e. “bootstrap-peers” is an empty
-list by default). Comments are not allowed in JSON, so this
-configuration file would not parse. They are just provided here to help
-writing your own configuration file if needed.
-
-::
-
- {
-
- /* Location of the data dir on disk. */
-
- "data-dir": "/home/tezos/my_data_dir"
-
- /* Configuration of net parameters */
-
- "net": {
-
- /* Floating point number between 0 and 256 that represents a
- difficulty, 24 signifies for example that at least 24 leading
- zeroes are expected in the hash. */
-
- "expected-proof-of-work": 24.5,
-
- /* List of hosts. Tezos can connect to both IPv6 and IPv4
- hosts. If the port is not specified, default port 9732 will be
- assumed. */
-
- "bootstrap-peers": ["::1:10732", "::ffff:192.168.1.3:9733", "mynode.tezos.com"],
-
- /* Specify if the node is in private mode or not. A node in
- private mode only opens outgoing connections to peers whose
- addresses are in [trusted_peers] and only accepts incoming
- connections from trusted peers. In addition, it informs these
- peers that the identity of the node should not be revealed to
- the rest of the network. */
-
- "private-mode": false,
-
- /* Network limits */
-
- "limits": {
-
- /* Delay granted to a peer to perform authentication, in
- seconds. */
-
- "authentication-timeout": 5,
-
- /* Strict minimum number of connections (triggers an urgent
- maintenance). */
-
- "min-connections": 50,
-
- /* Targeted number of connections to reach when bootstrapping /
- maintaining. */
-
- "expected-connections": 100,
-
- /* Maximum number of connections (exceeding peers are
- disconnected). */
-
- "max-connections": 200,
-
- /* Number above which pending incoming connections are
- immediately rejected. */
-
- "backlog": 20,
-
- /* Maximum allowed number of incoming connections that are
- pending authentication. */
-
- "max-incoming-connections": 20,
-
- /* Max download and upload speeds in KiB/s. */
-
- "max-download-speed": 1024,
- "max-upload-speed": 1024,
-
- /* Size of the buffer passed to read(2). */
-
- "read-buffer-size": 16384,
- }
- },
-
- /* Configuration of rpc parameters */
-
- "rpc": {
-
- /* Host to listen to. If the port is not specified, the default
- port 8732 will be assumed. */
-
- "listen-addr": "localhost:8733",
-
- /* Cross Origin Resource Sharing parameters, see
- https://en.wikipedia.org/wiki/Cross-origin_resource_sharing. */
-
- "cors-origin": [],
- "cors-headers": [],
-
- /* Certificate and key files (necessary when TLS is used). */
-
- "crt": "tezos-node.crt",
- "key": "tezos-node.key"
- },
-
- /* Configuration of log parameters */
-
- "log": {
-
- /* Output for the logging function. Either "stdout", "stderr" or
- the name of a log file . */
-
- "output": "tezos-node.log",
-
- /* Verbosity level: one of 'fatal', 'error', 'warn', 'notice',
- 'info', 'debug'. */
-
- "level": "info",
-
- /* Fine-grained logging instructions. Same format as described in
- `tezos-node run --help`, DEBUG section. In the example below,
- sections "net" and all sections starting by "client" will have
- their messages logged up to the debug level, whereas the rest of
- log sections will be logged up to the notice level. */
-
- "rules": "client* -> debug, net -> debug, * -> notice",
-
- /* Format for the log file, see
- http://ocsigen.org/lwt/dev/api/Lwt_log_core#2_Logtemplates. */
-
- "template": "$(date) - $(section): $(message)"
- },
-
- /* Configuration for the validator and mempool parameters */
-
- "shell": {
-
- /* The number of peers to synchronize with
- before declaring the node 'bootstrapped'. */
-
- "bootstrap_threshold": 4
-
- }
- }
-
-
-Environment for writing Michelson contracts
--------------------------------------------
-
-Here is how to setup a practical environment for
-writing, editing and debugging Michelson programs.
-
-Install `Emacs `_ with
-the `deferred `_ and
-`exec-path-from-shell
-`_ packages.
-The packages can be installed from within Emacs with
-``M-x package-install``.
-The last package imports the shell path in Emacs and it is needed
-because we will run a sandboxed node.
-
-Set up the `Michelson mode
-`_ by adding in
-your ``.emacs`` :
-
-::
-
- (load "~/tezos/tezos/emacs/michelson-mode.el" nil t)
- (setq michelson-client-command "tezos-client")
- (setq michelson-alphanet nil)
-
-Note that the Michelson mode will be chosen automatically by Emacs for
-files with a ``.tz`` or ``.tez`` extension.
-
-Run a :ref:`sandboxed node` (and activate the alphanet
-protocol with ``tezos-activate-alpha``) so that useful information
-about the program can be displayed.
-We can now open our favourite contract ``emacs
-./src/bin_client/test/contracts/id.tz`` and, when moving the cursor on
-a Michelson instruction, in the bottom of the windows Emacs should
-display the state of the stack before (left) and after (right) the
-application of the instruction.
-The Emacs mode automatically type-checks your program and reports
-errors; once you are happy with the result you can ask the client to
-run it locally:
-
-::
-
- tezos-client run script ./src/bin_client/test/contracts/id.tz \
- on storage '"hello"' and input '"world"'
-
-
-Debugging
----------
-
-It is possible to set independent log levels for different logging
-sections in Tezos, as well as specifying an output file for logging. See
-the description of log parameters above as well as documentation under
-the DEBUG section displayed by `tezos-node run –-help`.
diff --git a/vendors/tezos-modded/docs/logo.svg b/vendors/tezos-modded/docs/logo.svg
deleted file mode 100644
index 99da1d27a..000000000
--- a/vendors/tezos-modded/docs/logo.svg
+++ /dev/null
@@ -1,129 +0,0 @@
-
-
-
-
diff --git a/vendors/tezos-modded/docs/protocols/003_PsddFKi3.rst b/vendors/tezos-modded/docs/protocols/003_PsddFKi3.rst
deleted file mode 100644
index b3fa704a9..000000000
--- a/vendors/tezos-modded/docs/protocols/003_PsddFKi3.rst
+++ /dev/null
@@ -1,236 +0,0 @@
-.. _proto_003:
-
-Protocol 003_PsddFKi3
-=====================
-
-Description of the patch
-------------------------
-
-Fix to prevent account creation spam
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While creating accounts currently requires a .257 tez burn, there is
-currently no cost to create implicit accounts, despite them occupying
-space in the context.
-This patch adjusts the cost to .257 tez for both regular (KT1) and
-implicit (tz1) accounts.
-
-Error handling for nonce revelation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In cycle 48, a baker who lost their deposits and rewards due to double
-baking also did not inject nonce revelation. The protocol reached an
-error condition after trying to take away rewards from an account for
-which rewards had already been slashed. As a result, no new blocks
-could be accepted unless the nonces were revealed. The patch ensures
-correct handling of this scenario.
-
-Add RPCs for voting
-~~~~~~~~~~~~~~~~~~~
-
-This patch introduces RPCs to query ballot status, functionality
-needed by bakers to interact with proposals to amend the protocol.
-They are the following::
-
- Sum of ballots cast so far during a voting period.
- GET /chains//blocks//votes/ballots
-
- Ballots cast so far during a voting period.
- GET /chains//blocks//votes/ballot_list
-
- Current period kind: proposal, testing_vote, testing, promotion_vote.
- GET /chains//blocks//votes/current_period_kind
-
- Current expected quorum.
- GET /chains//blocks//votes/current_quorum
-
- List of delegates with their voting weight, in number of rolls.
- GET /chains//blocks//votes/listings
-
- List of proposals with number of supporters.
- GET /chains//blocks//votes/proposals
-
- Current proposal under evaluation.
- GET /chains//blocks//votes/current_proposal
-
-Correct accounting for approval voting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The current protocol does not properly count baking rolls during the
-approval voting phase. This is corrected in this version.
-
-
-How to apply the patch
-----------------------
-
-If compiling from source, please pull the latest code from the mainnet
-branch. From a clone of the git repository, a minimal update command
-is ``git checkout mainnet && git pull && eval $(opam env) && make
-build-deps && make``.
-Tezos binaries (node, client, baker, endorser, etc) should not be
-running while you re-compile.
-If using the script ``mainnet.sh`` based on docker provided at
-https://gitlab.com/tezos/tezos, simply do ``./mainnet.sh restart`` as
-every call to mainnet.sh checks for updates and updates if necessary.
-
-The node will automatically switch over to the new protocol at block
-height **204762** expected to occur after 2018-11-26T17:30:00 UTC.
-
-After updating, all processes (the node, baker, endorser, and accuser)
-should be restarted. The updated node handles multiple protocols but
-notice that there are several, protocol-specific, versions of every
-other processes.
-In order not to miss a block or an endorsement, you may run versions
-002_PsYLVpVv and 003_PsddFKi3 of the baker and endorser in parallel.
-Versions 003_PsddFKi3 of the baking and endorsement processes will not
-start baking or endorsing until the target block height. Version
-002_PsYLVpVv will stop by themselves and it will be safe to stop them
-at that time. This has been tested and the processes do not attempt to
-bake at the same height.
-
-However, as an extra precaution, specially if you do not use a
-hardware key or a remote-signer with a high water-mark, you may
-consider waiting until the target block height to shut down the old
-process and start the new one.)
-
-More details on fees and cost model
------------------------------------
-
-Protocol:
-~~~~~~~~~
-
-The creation of a new tz{1,2,3} address now requires a burn of `ꜩ0.257`,
-in-line with the creation of KT account.
-
-Every manager operation now costs at least ``10000`` in gas,
-a transaction has a default cost of ``10100`` in gas.
-
-Example::
-
- Reveal:
- Consumed gas: 10000
- Consumed storage: 0 bytes
-
- Transaction (when the target tz{1,2.3} is empty).
- Consumed gas: 10100
- Consumed storage: 277 bytes
-
- Transaction (when the target tz{1,2.3} is not empty).
- Consumed gas: 10100
- Consumed storage: 0 bytes
-
-
-Baker
-~~~~~
-
-The baker and mempool filters now require a minimal fee to propagate
-and include operations into blocks. This default is not set at the
-protocol level but rather in the configuration of the node and the baker.
-Bakers can thus decide of the settings that work best for them
-
-The minimal fee depends on the operation sent (transaction, origination,
-revelation, etc)
-
-When considering the injection of an operation in a block, the baker
-will check its size and gas and reject it if the associated fees are
-too low.
-The expected fees are computed using this formula::
-
- fees >= (minimal_fees + minimal_nanotez_per_byte * size + minimal_nanotez_per_gas_unit * gas)
-
-Where the size is the number of bytes of the complete serialized
-operation, i.e. including header and signature.
-When sending multiple transactions at once (i.e. packed operations),
-the baker will require the summed fees of all the operations to match
-the summed gas of all the operations and the total size of the packed
-operations, still including header and signature.
-
-By default::
-
- minimal_fees = 0.000 1 ꜩ (100 µꜩ)
- minimal_nanotez_per_gas_unit = 100 nꜩ/gu (0.000 000 1 ꜩ/gu)
- minimal_nanotez_per_byte = 1000 nꜩ/B (0.000 001 ꜩ/B)
-
-For instance, a single transaction to an existing implicit address
-will require a transaction fee of at least `0.001 273 ꜩ`
-to be included by bakers who choose to follow the default settings.
-
-These settings may be changed by passing the following flags to the baker
-(``--minimal-fees ``,
-``--minimal-nanotez-per-gas-unit ``,
-``--minimal-nanotez-per-byte ``).
-
-Delegates distributing rewards should be aware of these thresholds
-for their transactions to be successfully included.
-
-Node
-~~~~
-
-The node also filters operations following the same principles as
-above. If an operation does not carry sufficient fees, a node
-following the default setting will not include it in its mempool.
-Hence an operation without fee won't even propagate through
-the network. The constant can be changed with the following RPC
-call::
-
- ./tezos-client rpc post /chains/main/mempool/filter with '{ "minimal_fees": "0", "minimal_nanotez_per_gas_unit": "0", "minimal_nanotez_per_byte": "0" }'
-
-The constants used by the node and the baker do not need to be equal,
-but the node needs to be less restrictive than the baker, otherwise
-the baker won't even see the operations.
-
-An injection node (i.e. a specific node targeted by wallet for
-injection operation) might deactivate the filter (by using the
-previous RPC call) in order to accept any operation and give them a
-chance to be propagated to a baker that is willing to accept fee-less
-operations.
-
-
-FAQ
----
-
-Q. Who should apply this patch?
-
-A. Anyone running a node needs to update. If you are using a wallet
- that connects to a third party node, you do not need to apply a
- patch, but you can inquire with the wallet developers to make sure
- they are running a patched node. If you are delegating your tez you
- may wish to inquire with your baker that he is running the patched
- node in order not to miss any reward.
-
-Q. What are the risks and impact of account creation spam?
-
-A. Over time, account creation spam can make it uneconomical to run a
- node due to the amount of disk space required. This would make it
- harder for people to participate in the ecosystem.
-
-Q. What happens if I apply the patch early?
-
-A. The patch will automatically activate at a set block-height.
- Specifically, block height 204762 (approximately Monday Nov 26 1730
- UTC)
-
-Q. What happens if I don't apply the patch?
-
-A. Your node will continue tracking a branch with a known bug which
- does not represent the consensus among network participants.
-
-Q. Why not use the governance mechanism to correct these issues?
-
-A. The governance mechanism is a slow, deliberative, procedure for
- deciding on the evolution of the code. It is not a substitute for
- security patches which require quick deployment.
-
-Q. Why not mandate minimal transaction fees in the protocol?
-
-A. Transaction fees solve a slightly different problem, but they can
- help. If bakers wish to filter out transaction with low fees, they
- can run the process by passing the flag::
-
- --minimal-fees (default 0.000 1)
- --minimal-nanotez-per-byte (default 1000)
- --minimal-nanotez-per-gaz-unit (default 100)
-
- 1 mutez is equivalent to 1000 nanotez. The patch does include
- default minimal fees in the mempool, but individual bakers can
- choose to override these.
diff --git a/vendors/tezos-modded/docs/tutorials/data_encoding.rst b/vendors/tezos-modded/docs/tutorials/data_encoding.rst
deleted file mode 100644
index 0ed1e808e..000000000
--- a/vendors/tezos-modded/docs/tutorials/data_encoding.rst
+++ /dev/null
@@ -1,207 +0,0 @@
-.. _data_encoding:
-
-The ``data_encoding`` library
-=============================
-
-Throughout the Tezos protocol, data is serialized so that it can be used
-via RPC, written to disk, or placed in a block. This
-serialization/de-serialization is handled via the :package:`tezos-data-encoding`
-library by providing a set primitive encodings and a variety of combinators.
-
-Examples/Tutorial
------------------
-
-Encoding an integer
-~~~~~~~~~~~~~~~~~~~
-
-Integers are defined as other concrete data types with a generic
-encoding type ``type 'a encoding``. This means that it is an encoding
-to/from type ``int``. There are a variety of ways to encode an integer,
-depending on what binary serialization you want to achieve:
-
-- ``Data_encoding.int8``
-- ``Data_encoding.uint8``
-- ``Data_encoding.int16``
-- ``Data_encoding.uint16``
-- ``Data_encoding.int31``
-- ``Data_encoding.int32``
-- ``Data_encoding.int64``
-
-For example, an encoding that represents a 31 bit integer has type
-``Data_encoding.int31 = int Data_encoding.encoding``.
-
-.. code:: ocaml
-
- let int31_encoding = Data_encoding.int31
-
-Encoding an object
-~~~~~~~~~~~~~~~~~~
-
-Encoding a single integer is fairly uninteresting. The `Data_encoding`
-library provides a number of combinators that can be used to build more
-complicated objects. Consider the type that represents an interval from
-the first number to the second:
-
-.. code:: ocaml
-
- type interval = int64 * int64
-
-We can define an encoding for this type as:
-
-.. code:: ocaml
-
- let interval_encoding =
- Data_encoding.(obj2 (req "min" int64) (req "max" int64))
-
-In the example above we construct a new value ``interval_encoding`` by
-combining two `int64` integers using the ``obj2`` (object with two fields)
-constructor.
-
-The library provides different constructors, i.e. for objects that have
-no data (``Data_encoding.empty``), constructors for object up to 10
-fields, constructors for tuples, list, etc.
-
-These are serialized to binary by converting each internal object to
-binary and placing them in the order of the original object and to JSON
-as a JSON object with field names.
-
-Lists, arrays, and options
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-List, arrays and options types can by built on top of ground data types.
-
-.. code:: ocaml
-
- type interval_list = interval list
-
- type interval_array = interval array
-
- type interval_option = interval option
-
-And the encoders for these types as
-
-.. code:: ocaml
-
- let interval_list_encoding = Data_encoding.list interval_encoding
- let interval_array_encoding = Data_encoding.array interval_encoding
- let interval_option_encoding = Data_encoding.option interval_encoding
-
-Union types
-~~~~~~~~~~~
-
-The Tezos codebase makes heavy use of variant types. Consider the
-following variant type:
-
-.. code:: ocaml
-
- type variant = B of bool
- | S of string
-
-Encoding for this types can be expressed as:
-
-.. code:: ocaml
-
- let variant_encoding =
- Data_encoding.(union ~tag_size:`Uint8
- [ case
- bool
- (function B b -> Some b | _ -> None)
- (fun b -> B b) ;
- case
- string
- (function S s -> Some s | _ -> None)
- (fun s -> S s) ])
-
-This variant encoding is a bit more complicated. Let’s look at the parts
-of the encoding:
-
-- We include an optimization hint to the binary encoding to inform it
- of the number of elements we expect in the tag. In most cases, we can
- use :literal:`\`Uint8`, which allows you to have up to 256 possible
- cases (default).
-- We provide a function to wrap the datatype. The encoding works by
- repeatedly trying to decode the datatype using these functions until
- one returns ``Some payload``. This payload is then encoded using the
- dataencoding specified.
-- We specify a function from the encoded type to the actual datatype.
-
-Since the library does not provide an exhaustive check on these
-constructors, the user must be careful when constructing union types to
-avoid unfortunate runtime failures.
-
-How the Dataencoding module works
----------------------------------
-
-This section is 100% optional. You do not need to understand this
-section to use the library.
-
-The library uses GADTs to provide type-safe
-serialization/de-serialization. From there, a runtime representation of
-JSON objects is parsed into the type-safe version.
-
-First we define an untyped JSON AST:
-
-.. code:: ocaml
-
- type json =
- [ `O of (string * json) list
- | `Bool of bool
- | `Float of float
- | `A of json list
- | `Null
- | `String of string ]
-
-This is then parsed into a typed AST (we eliminate several cases for
-clarity):
-
-.. code:: ocaml
-
- type 'a desc =
- | Null : unit desc
- | Empty : unit desc
- | Bool : bool desc
- | Int64 : Int64.t desc
- | Float : float desc
- | Bytes : Kind.length -> MBytes.t desc
- | String : Kind.length -> string desc
- | String_enum : Kind.length * (string * 'a) list -> 'a desc
- | Array : 'a t -> 'a array desc
- | List : 'a t -> 'a list desc
- | Obj : 'a field -> 'a desc
- | Objs : Kind.t * 'a t * 'b t -> ('a * 'b) desc
- | Tup : 'a t -> 'a desc
- | Union : Kind.t * tag_size * 'a case list -> 'a desc
- | Mu : Kind.enum * string * ('a t -> 'a t) -> 'a desc
- | Conv :
- { proj : ('a -> 'b) ;
- inj : ('b -> 'a) ;
- encoding : 'b t ;
- schema : Json_schema.schema option } -> 'a desc
- | Describe :
- { title : string option ;
- description : string option ;
- encoding : 'a t } -> 'a desc
- | Def : { name : string ;
- encoding : 'a t } -> 'a desc
-
-- The first few constructors define all ground types.
-- The constructors for ``Bytes``, ``String`` and ``String_enum``
- include a length field in order to provide safe binary
- serialization.
-- The constructors for ``Array`` and ``List`` are used by the
- combinators we saw earlier.
-- The ``Obj`` and ``Objs`` constructors create JSON objects. These are
- wrapped in the ``Conv`` constructor to remove nesting that results
- when these constructors are used naively.
-- The ``Mu`` constructor is used to create self-referential
- definitions.
-- The ``Conv`` constructor allows you to clean up a nested definition
- or compute another type from an existing one.
-- The ``Describe`` and ``Def`` constructors are used to add
- documentation
-
-The library also provides various wrappers and convenience functions to
-make constructing these objects easier. Reading the documentation in the
-`mli file
-<../api/odoc/tezos-data-encoding/Tezos_data_encoding/Data_encoding/index.html>`__
-should orient you on how to use these functions.
diff --git a/vendors/tezos-modded/docs/tutorials/entering_alpha.rst b/vendors/tezos-modded/docs/tutorials/entering_alpha.rst
deleted file mode 100644
index fed1ea359..000000000
--- a/vendors/tezos-modded/docs/tutorials/entering_alpha.rst
+++ /dev/null
@@ -1,199 +0,0 @@
-.. _entering_alpha:
-
-How to start reading protocol Alpha
-===================================
-
-Protocol Alpha, whose Alpha has nothing to do with the one in Alphanet,
-is the name of the initial economic protocol. Alpha is a placeholder
-name, while we decide on the naming convention for protocol versions.
-
-Before reading that document, you may want to:
-
-- read the whitepaper,
-- read :ref:`how the economic protocol is
- sandboxed `.
-
-As all protocols, Alpha is made of a series of OCaml interface and
-implementation files, accompanied by a ``TEZOS_PROTOCOL`` file.
-
-The ``TEZOS_PROTOCOL`` structure
---------------------------------
-
-If you look at this file in the repository, you will see that it is
-composed of the hash of the sources, and the list of its modules, in
-linking order.
-
-Protocol Alpha is structured as a tower of abstraction layers, a coding
-discipline that we designed to have OCaml check as many invariants as
-possible at typing time. You will also see empty lines in
-``TEZOS_PROTOCOL`` that denote these layers of abstraction.
-
-These layers follow the linking order: the first modules are the tower’s
-foundation that talk to the raw key-value store, and going forward in
-the module list means climbing up the abstraction tower.
-
-The big abstraction barrier: ``Alpha_context``
-----------------------------------------------
-
-The proof-of-stake algorithm, as described in the white paper, relies on
-an abstract state of the ledger, that is read and transformed during
-validation of a block.
-
-Due to the polymorphic nature of Tezos, the ledger’s state (that we call
-**context** in the code), cannot be specific to protocol Alpha’s need.
-The proof-of-stake is thus implemented over a generic key-value store
-whose keys and associated binary data must implement the abstract
-structure.
-
-The ``Alpha_context`` module enforces the separation of concerns
-between, on one hand, mapping the abstract state of the ledger to the
-concrete structure of the key-value store, and, on the other hand,
-implementing the proof-of-stake algorithm over this state.
-
-In more practical terms, ``Alpha_context`` defines a type ``t`` that
-represents a state of the ledger. This state is an abstracted out
-version of the key-value store that can only be manipulated through the
-use of the few selected manipulations reexported by ``Alpha_context``,
-that always preserve the well-typed aspect and internal consistency
-invariants of the state.
-
-When validating a block, the low-level state that result from the
-predecessor block is read from the disk, then abstracted out to a
-``Alpha_context.t``, which is then only updated by high level operations
-that preserve consistency, and finally, the low level state is extracted
-to be committed on disk.
-
-This way, we have two well separated parts in the code. The code below
-``Alpha_context`` implements the ledger’s state storage, while the code
-on top of it is the proof-of-stake algorithm. Thanks to this barrier,
-the latter can remain nice, readable OCaml that only manipulates plain
-OCaml values.
-
-Below the ``Alpha_context``
----------------------------
-
-For this part, in a first discovery of the source code, you can start by
-relying mostly on this coarse grained description, with a little bit of
-cherry-picking when you’re curious about how a specific invariant is
-enforced.
-
-The ``*_repr`` modules
-~~~~~~~~~~~~~~~~~~~~~~
-
-These modules abstract the values of the raw key-value context by using
-:ref:`Data_encoding`.
-
-These modules define the data types used by the protocol that need to be
-serialized (amounts, contract handles, script expressions, etc.). For
-each type, it also defines its serialization format using
-:ref:`Data_encoding`.
-
-Above this layer, the code should never see the byte sequences in the
-database, the ones of transmitted blocks and operations, or the raw JSON
-of data transmitted via RPCs. It only manipulates OCaml values.
-
-The ``Storage`` module and storage functors
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Even with the concrete formats of values in the context abstracted out,
-type (or consistency) errors can still occur if the code accesses a
-value with a wrong key, or a key bound to another value. The next
-abstraction barrier is a remedy to that.
-
-The storage module is the single place in the protocol where key
-literals are defined. Hence, it is the only module necessary to audit,
-to know that the keys are not colliding.
-
-It also abstracts the keys, so that each kind of key get its own
-accessors. For instance, module ``Storage.Contract.Balance`` contains
-accessors specific to contracts’ balances.
-
-Moreover, the keys bear the type of the values they point to. For
-instance, only values of type ``Tez_repr.t`` can by stored at keys
-``Storage.Contract.Balance``. And in case a key is not a global key, but
-a parametric one, this key is parameterized by an OCaml value, and not the
-raw key part.
-
-So in the end, the only way to be used when accessing a contract balance
-is ``Storage.Contract.Balance.get``, which takes a ``Contract_repr.t``
-and gives a ``Tez_repr.t``.
-
-All these well-typed operations are generated by a set of functors, that
-come just before ``Storage`` in ``TEZOS_CONTEXT``.
-
-The ``*_storage`` modules
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The two previous steps ensure that the ledger’s state is always accessed
-and updated in a well-typed way.
-
-However, it does not enforce that, for instance, when a contract is
-deleted, all of the keys that store its state in the context are indeed
-deleted.
-
-This last series of modules named ``*_storage`` is there to enforce just
-that kind of invariants: ensuring the internal consistency of the
-context structure.
-
-These transaction do not go as far as checking that, for instance, when
-the destination of a transaction is credited, the source is also
-debited, as in some cases, it might not be the case.
-
-Above the ``Alpha_context``
----------------------------
-
-The three next sections describe the main entrypoints to the protocol:
-validation of blocks by the shell (that we often also call application),
-smart contracts, and RPC services.
-
-The ``Main`` module is the entrypoint that’s used by the shell. It
-respects the module type that all protocol must follow. For that, its
-code is mostly plumbing,
-
-Starting from ``Apply``
-~~~~~~~~~~~~~~~~~~~~~~~
-
-This is were you want to start on your first read. Even if some plumbing
-code is woven in, such as error cases declaration and registration, most
-of the proof-of-stake code has been written in a verbose style, to be
-understood with minimum OCaml knowledge.
-
-You want to start from the shell entry points (validation of the block
-header, validation of an operation, finalization of a block validation),
-and follow the control flow until you hit the ``Alpha_context``
-abstraction barrier. This will lead you to reading modules ``Baking``
-and ``Amendment``.
-
-Smart contracts
-~~~~~~~~~~~~~~~
-
-From ``Apply``, you will also end up in modules ``Script_ir_translator``
-and ``Script_interpreter``. The former is the typechecker of Michelson
-that is called when creating a new smart contract, and the latter is the
-interpreter that is called when transferring tokens to a new smart
-contract.
-
-Protocol RPC API
-~~~~~~~~~~~~~~~~
-
-Finally, the RPCs specific to Alpha are also defined above the
-``Alpha_context`` barrier.
-
-Services are defined in a few modules, divided by theme. Each module
-defines the RPC API: URL schemes with the types of parameters, and
-input and output JSON schemas. This interface serves three
-purposes. As it is thoroughly typed, it makes sure that the handlers
-(that are registered in the same file) have the right input and output
-types. It is also used by the client to perform RPC calls, to make
-sure that the URL schemes and JSON formats and consistent between the
-two parties. These two features are extremely useful when refactoring,
-as the OCaml typechecker will help us track the effects of an RPC API
-change on the whole codebase. The third purpose is of course, to make
-automatic documentation generation possible (as in ``tezos client rpc
-list/format``). Each service is also accompanied by a caller function,
-that can be used from the client to perform the calls, and by the
-tests to simulate calls in a fake in-memory context.
-
-It can be useful if you are a third party developer who wants to read
-the OCaml definition of the service hierarchy directly, instead of the
-automatically generated JSON hierarchy.
diff --git a/vendors/tezos-modded/docs/tutorials/error_monad.rst b/vendors/tezos-modded/docs/tutorials/error_monad.rst
deleted file mode 100644
index ddac11f6f..000000000
--- a/vendors/tezos-modded/docs/tutorials/error_monad.rst
+++ /dev/null
@@ -1,366 +0,0 @@
-.. _error_monad:
-
-The Error Monad
-===============
-
-This has been adapted from a blog post on *michelson-lang.com*.
-
-If you’re not familiar with monads, go take a few minutes and read a
-tutorial. I personally got a lot out of this
-`paper `__
-by Philip Wadler, but there are a ton of others available online. Find
-one that works for you. The error monad isn’t terribly scary as Monads
-go, so once you feel like you understand the gist, come on back and see
-if you can understand what’s going on.
-
-I’m going to omit some convenience operations that a lot of monads
-provide in the examples below. If you want to add them, they’re not
-difficult.
-
-Why you want the error monad
-----------------------------
-
-In Tezos, we don’t want to have the node be crashable by an improper
-input. To avoid this possibility, it was decided that the system should
-not use exceptions for error handling. Instead, it uses an error monad.
-This design forces errors to be handled or carried through before an
-output can be used. Exceptions are still occasionally used, but this is
-mostly in the client and only for internal errors.
-
-We also mix in the Lwt library, which we use for concurrency. This is
-combined with the error monad and is once again used pervasively
-throughout the codebase. The Lwt monad is a lot like promises in other
-languages.
-
-Without further ado, let’s write an error monad.
-
-A simple version of the error monad
------------------------------------
-
-Here’s a very simple error monad.
-
-.. code:: ocaml
-
- module Error : sig
- type 'a t
- (* Create a value of type t *)
- val return : 'a -> 'a t
- (* For when a computation fails *)
- val error : 'a t
- (* Apply an operation to a value in the error monad *)
- val (>>?) : 'a t -> ('a -> 'b t) -> 'b t (* bind *)
- end = struct
- type 'a t = Ok of 'a | Error
- let return x = Ok x
- let error = Error
- let (>>?) value func =
- match value with
- | Ok x -> func x
- | Error -> Error
- end
-
-So, is this what Tezos uses? We actually already have a lot of the
-structure that we’ll use later. The basic idea is that you return a
-value that’s correct and return an error if the operation failed.
-Outside of the error module, you can’t actually introspect an error
-value. You can only dispatch on the correctness/incorrectness of the
-value using bind.
-
-What’s wrong here?
-
-- We can’t report any information about an error case
-- We can’t report error traces, something that’s used to improve the
- quality of error messages throughout Tezos
-- We can’t handle some errors and continue executing
-
-A slight improvement
---------------------
-
-Let’s now enhance our error reporting by allowing errors to contain a
-description string. Now we can report messages along with our errors. Is
-this enough of an improvement? Not really. We don’t have any flexibility
-about how the printing works. We still can’t create error traces and we
-can’t handle errors and resume executing the program.
-
-.. code:: ocaml
-
- module Error : sig
- type 'a t
- val return : 'a -> 'a t
- val error : string -> 'a t
- val (>>?) : 'a t -> ('a -> 'b t) -> 'b t (* bind *)
- val print_value : ('a -> string) -> 'a t -> unit
- end = struct
- type 'a t = Ok of 'a | Error of string
- let return x = Ok x
- let error s = Error s
- let (>>?) value func =
- match value with
- | Ok x -> func x
- | Error s -> Error s
- let print_value func = function
- | Ok x -> Printf.printf "Success: %s\n" (func x)
- | Error s -> Printf.printf "Error: %s\n" s
- end
-
-Traces
-------
-
-Now that we have the basic structure down, we can add a mechanism to let
-us include traces. As a note, the error type I had above is exactly the
-``result`` type from the OCaml standard library. The traces are just
-lists of error messages. If you have a call you think might fail, and
-you want to provide a series of errors, you can wrap that result in the
-``trace`` function. If that call fails, an additional error is added.
-
-.. code:: ocaml
-
- module Error : sig
- type 'a t
- val return : 'a -> 'a t
- val error : string -> 'a t
- val (>>?) : 'a t -> ('a -> 'b t) -> 'b t (* bind *)
- val print_value : ('a -> string) -> 'a t -> unit
- val trace : string -> 'a t -> 'a t
- end = struct
- type 'a t = ('a, string list) result
- let return x = Ok x
- let error s = Error [ s ]
- let (>>?) value func =
- match value with
- | Ok x -> func x
- | Error errs -> Error errs
- let print_value func = function
- | Ok x -> Printf.printf "Success: %s\n" (func x)
- | Error [ s ] -> Printf.printf "Error: %s\n" s
- | Error errors -> Printf.printf "Errors:\t%s\n" (String.concat "\n\t" errors)
- let trace error = function
- | Ok x -> Ok x
- | Error errors -> Error (error :: errors)
- end
-
-A more descriptive message
---------------------------
-
-Even though traces are nice, we really want to be able to store more
-interesting data in the messages. We’re going to use an extensible
-variant type to do this. Extensible variants allow us to add a new case
-to a variant type at the cost of exhaustivity checking. We’re going to
-need two new mechanisms to make this work well. The first is an error
-registration scheme. In the actual error monad, this involves the data
-encoding module, which is how all data is encoded/decoded in Tezos. This
-module is another decently complicated part of the codebase that should
-probably the subject of a future post. Since you can declare arbitrary
-new errors, we’ll have a way of adding a printer for each error.
-
-When we add a new error handler, we’ll use the ``register_handler``
-function. This function will take a function that takes an error and
-returns a ``string option``. These functions will look something like
-this:
-
-.. code:: ocaml
-
- type error += Explosion_failure of string * int;;
-
- register_error
- (function
- | Explosion_failure (s, i) ->
- Some (Printf.sprintf "Everything exploded: %s at %d" s i)
- | _ -> None)
-
-I’m also renaming the ``error`` function to ``fail``. This is the
-convention used by the actual `Error_monad` module. I’m also exposing the
-``'a t`` type so that you can dispatch on it if you need to. This is
-used several times in the Tezos codebase.
-
-.. code:: ocaml
-
- module Error : sig
- type error = ..
- type 'a t = ('a, error list) result
- val return : 'a -> 'a t
- val fail : error -> 'a t
- val (>>?) : ('a -> 'b t) -> 'a t -> 'b t (* bind *)
- val print_value : ('a -> string) -> 'a t -> unit
- val trace : error -> 'a t -> 'a t
- end = struct
- type error = ..
- type 'a t = ('a, error list) result
- let fail error = Error [ error ]
- let return x = Ok x
- let (>>?) func = function
- | Ok x -> func x
- | Error errs -> Error errs
- let registered = ref []
- let register_error handler =
- registered := (handler :: !registered)
- let default_handler error =
- "Unregistered error: " ^ Obj.(extension_name @@ extension_constructor error)
- let to_string error =
- let rec find_handler = function
- | [] -> default_handler error
- | handler :: handlers ->
- begin match handler error with
- | None -> find_handler handlers
- | Some s -> s
- end
- in find_handler !registered
- let print_value func = function
- | Ok x -> Printf.printf "Success: %s\n" (func x)
- | Error [ s ] -> Printf.printf "Error: %s\n" (to_string s)
- | Error errors -> Printf.printf "Errors:\t%s\n" (String.concat "\n\t" (List.map to_string errors))
- let trace error = function
- | Ok x -> Ok x
- | Error errors -> Error (error :: errors)
- end
-
-Putting ``Lwt.t`` in the mix
-----------------------------
-
-Tezos uses the `Lwt library `__ for threading.
-The Lwt monad is mixed in with the error monad module. This requires us
-to add some extra combinators and reexport some functions from Lwt.
-
-I’m also renaming the type ``t`` to ``tzresult``, as used in the Tezos
-codebase.
-
-.. code:: ocaml
-
- module Error : sig
- type error = ..
- type 'a tzresult = ('a, error list) result
- val ok : 'a -> 'a tzresult
- val return : 'a -> 'a tzresult Lwt.t
- val error : error -> 'a tzresult
- val fail : error -> 'a tzresult Lwt.t
- val (>>?) : 'a tzresult -> ('a -> 'b tzresult) -> 'b tzresult (* bind *)
- val (>>=?) : 'a tzresult Lwt.t -> ('a -> 'b tzresult Lwt.t) -> 'b tzresult Lwt.t
- val (>>=) : 'a Lwt.t -> ('a -> 'b Lwt.t) -> 'b Lwt.t
- val print_value : ('a -> string) -> 'a tzresult Lwt.t -> unit Lwt.t
- val trace : error -> 'a tzresult Lwt.t -> 'a tzresult Lwt.t
- end = struct
- type error = ..
- type 'a tzresult = ('a, error list) result
- let fail error = Lwt.return (Error [ error ])
- let error error = (Error [ error ])
- let ok x = Ok x
- let return x = Lwt.return (ok x)
- let (>>?) value func =
- match value with
- | Ok x -> func x
- | Error errs -> Error errs
- let (>>=) = Lwt.bind
- let (>>=?) value func =
- value >>= function
- | Ok x -> func x
- | Error errs -> Lwt.return (Error errs)
- let registered = ref []
- let register_error handler =
- registered := (handler :: !registered)
- let default_handler error =
- "Unregistered error: " ^ Obj.(extension_name @@ extension_constructor error)
- let to_string error =
- let rec find_handler = function
- | [] -> default_handler error
- | handler :: handlers ->
- begin match handler error with
- | None -> find_handler handlers
- | Some s -> s
- end
- in find_handler !registered
- let print_value func value =
- value >>= fun value ->
- begin match value with
- | Ok x -> Printf.printf "Success: %s\n" (func x)
- | Error [ s ] -> Printf.printf "Error: %s\n" (to_string s)
- | Error errors -> Printf.printf "Errors:\t%s\n" (String.concat "\n\t" (List.map to_string errors))
- end; Lwt.return ()
- let trace error value =
- value >>= function
- | Ok x -> return x
- | Error errors -> Lwt.return (Error (error :: errors))
- end
-
-The actual Tezos error monad
-----------------------------
-
-The actual Tezos error monad adds a few things. Firstly, there are three
-categories of errors:
-
-- :literal:`\`Temporary` - An error resulting from an operation that
- might be valid in the future, for example, a contract’s balance being
- too low to execute the intended operation. This can be fixed by
- adding more to the contract’s balance.
-- :literal:`\`Branch` - An error that occurs in one branch of the
- chain, but may not occur in a different one. For example, receiving
- an operation for an old or future protocol version.
-- :literal:`\`Permanent` - An error that is not recoverable because the
- operation is never going to be valid. For example, an invalid ꜩ
- notation.
-
-The registration scheme also uses data encodings. Here’s an example from
-the `validator <../api/odoc/tezos-node-shell/Tezos_node_shell/Validator/index.html>`__:
-
-.. code:: ocaml
-
- register_error_kind
- `Permanent
- ~id:"validator.wrong_level"
- ~title:"Wrong level"
- ~description:"The block level is not the expected one"
- ~pp:(fun ppf (e, g) ->
- Format.fprintf ppf
- "The declared level %ld is not %ld" g e)
- Data_encoding.(obj2
- (req "expected" int32)
- (req "provided" int32))
- (function Wrong_level (e, g) -> Some (e, g) | _ -> None)
- (fun (e, g) -> Wrong_level (e, g))
-
-An error takes a category, id, title, description, and encoding. You
-must specify a function to take an error to an optional value of the
-encoding type and a function to take a value of the encoded type and
-create an error value. A pretty printer can optionally be specified, but
-may also be omitted.
-
-The actual error monad and its tracing features can be seen in this
-function which parses contracts:
-
-.. code:: ocaml
-
- let parse_script
- : ?type_logger: (int * (Script.expr list * Script.expr list) -> unit) ->
- context -> Script.storage -> Script.code -> ex_script tzresult Lwt.t
- = fun ?type_logger ctxt
- { storage; storage_type = init_storage_type }
- { code; arg_type; ret_type; storage_type } ->
- trace
- (Ill_formed_type (Some "parameter", arg_type))
- (Lwt.return (parse_ty arg_type)) >>=? fun (Ex_ty arg_type) ->
- trace
- (Ill_formed_type (Some "return", ret_type))
- (Lwt.return (parse_ty ret_type)) >>=? fun (Ex_ty ret_type) ->
- trace
- (Ill_formed_type (Some "initial storage", init_storage_type))
- (Lwt.return (parse_ty init_storage_type)) >>=? fun (Ex_ty init_storage_type) ->
- trace
- (Ill_formed_type (Some "storage", storage_type))
- (Lwt.return (parse_ty storage_type)) >>=? fun (Ex_ty storage_type) ->
- let arg_type_full = Pair_t (arg_type, storage_type) in
- let ret_type_full = Pair_t (ret_type, storage_type) in
- Lwt.return (ty_eq init_storage_type storage_type) >>=? fun (Eq _) ->
- trace
- (Ill_typed_data (None, storage, storage_type))
- (parse_data ?type_logger ctxt storage_type storage) >>=? fun storage ->
- trace
- (Ill_typed_contract (code, arg_type, ret_type, storage_type, []))
- (parse_returning (Toplevel { storage_type }) ctxt ?type_logger arg_type_full ret_type_full code)
- >>=? fun code ->
- return (Ex_script { code; arg_type; ret_type; storage; storage_type })
-
-Each specific type error from the typechecking process is wrapped in a
-more general error that explains which part of the program was
-malformed. This improves the error reporting. You can also see the bind
-operator used between functions to continue only if an error does not
-occur. This function also operates in the ``Lwt`` monad, which is
-largely hidden via the error monad.
diff --git a/vendors/tezos-modded/docs/tutorials/michelson_anti_patterns.rst b/vendors/tezos-modded/docs/tutorials/michelson_anti_patterns.rst
deleted file mode 100644
index bf6ad897e..000000000
--- a/vendors/tezos-modded/docs/tutorials/michelson_anti_patterns.rst
+++ /dev/null
@@ -1,203 +0,0 @@
-Michelson Anti-Patterns
-=======================
-
-Even though Michelson is designed to make it easy to write secure
-contracts and difficult to write vulnerable ones, it is still possible
-to write buggy contracts that leak data and funds. This is a list of
-mistakes that you can make when writing or interacting with contracts on
-the Tezos blockchain and alternative ways to write code that avoid these
-problems.
-
-Note: We are currently reworking the concurrency model of Michelson (how
-and when sub-transactions are made), so that some of these patterns will
-be prevented by the language itself.
-
-Refunding to a list of contracts
---------------------------------
-
-One common pattern in contracts is to refund a group of people’s funds
-at once. This is problematic if you accepted arbitrary contracts as a
-malicious user can do cause various issues for you.
-
-Possible issues:
-~~~~~~~~~~~~~~~~
-
-- One contract swallows all the gas through a series of callbacks
-- One contract writes transactions until the block is full
-- Reentrancy bugs. Michelson intentionally makes these difficult to
- write, but it is still possible if you try.
-- A contract calls the \`FAIL\` instruction, stopping all computation.
-
-Alternatives/Solutions:
-~~~~~~~~~~~~~~~~~~~~~~~
-
-- Create a default account from people’s keys. Default accounts cannot
- execute code, avoiding the bugs above. Have people submit keys rather
- than contracts.
-- Have people pull their funds individually. Each user can break their
- own withdrawal only. **This does not protect against reentrancy
- bugs.**
-
-Avoid batch operations when users can increase the size of the batch
---------------------------------------------------------------------
-
-Contracts that rely on linear or super-linear operations are vulnerable
-to malicious users supplying values until the contract cannot finish
-without running into fuel limits. This can deadlock your contract.
-
-.. _possible-issues-1:
-
-Possible issues:
-~~~~~~~~~~~~~~~~
-
-- Malicious users can force your contract into a pathological worst
- case, stopping it from finishing with available gas. Note that in the
- absence of hard gas limits, this can still be disabling as node
- operators may not want to run contracts that take more than a certain
- amount of gas.
-- You may hit the slow case of an amortized algorithm or data structure
- at an inopportune time, using up all of your contract’s available
- gas.
-
-.. _alternativessolutions-1:
-
-Alternatives/Solutions:
-~~~~~~~~~~~~~~~~~~~~~~~
-
-- Avoid data structures and algorithms that rely on amortized
- operations, especially when users may add data.
-- Restrict the amount of data your contract can store to a level that
- will not overwhelm the available gas.
-- Write your contract so that it may pause and resume batch operations.
- This would complicate these sequences and require constant checking
- of available gas, but it prevents various attacks.
-
-\*Do not assume an attack will be prohibitively expensive\*
-Cryptocurrencies have extreme price fluctuations frequently and an
-extremely motivated attacker may decide that an enormous expense is
-justified. Remember, an attack that disables a contract is not just
-targeted at the authors, but also the users of that contract.
-
-Signatures alone do not prevent replay attacks
-----------------------------------------------
-
-If your contract uses signatures to authenticate messages, beware of
-replay attacks. If a user ever signs a piece of data, you *must* make
-sure that that piece of data is never again a valid message to the
-contract. If you do not do this, anyone else can call your contract with
-the same input and piggyback on the earlier approval.
-
-.. _possible-issues-2:
-
-Possible issues:
-~~~~~~~~~~~~~~~~
-
-- A previously approved action can be replayed.
-
-.. _alternativessolutions-2:
-
-Alternatives/Solutions
-~~~~~~~~~~~~~~~~~~~~~~
-
-- Use an internal counter to make the data you ask users to sign
- unique. This counter should be per key so that users can find out
- what they need to approve. This should be paired with a signed hash
- of your contract to prevent cross-contract replays.
-- Use the ``SENDER`` instruction to verify that the expected sender is
- the source of the message.
-
-Do not assume users will use a unique key for every smart contract
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Users should always use a different key for every contract with which
-they interact. If this is not the case, a message the user signed for
-another contract can be sent to your contract. An internal counter alone
-does not protect against this attack. It *must* be paired with a hash of
-your contract. You must verify the source of the message.
-
-Storing/transferring private data
----------------------------------
-
-Once data is published to anyone, including broadcasting a transaction,
-that data is public. Never transmit secret information via any part of
-the blockchain ecosystem. As soon as you have broadcast a transaction
-including that piece of information, anyone can see it. Furthermore,
-malicious nodes in the system can manipulate unsigned transactions by
-delaying, modifying, or reordering them.
-
-.. _possible-issues-3:
-
-Possible Issues
-~~~~~~~~~~~~~~~
-
-- If data is not signed, it can be modified
-- Transactions can be delayed
-- Secret information will become public
-
-.. _alternativessolutions-3:
-
-Alternatives/Solutions
-~~~~~~~~~~~~~~~~~~~~~~
-
-- Do not store private information on the blockchain or broadcast it in
- transactions.
-- Sign all transactions that contain information that, if manipulated,
- could be abused.
-- Use counters to enforce transaction orders.
-
-This will at least create a logical clock on messages sent to your
-contract.
-
-Not setting all state before a transfer
----------------------------------------
-
-Reentrancy is a potential issue on the blockchain. When a contract makes
-a transfer to another contract, that contract can execute its own code,
-and can make arbitrary further transfers, including back to the original
-contract. If state has not been updated before the transfer is made, a
-contract can call back in and execute actions based on old state.
-
-.. _possible-issues-4:
-
-Possible Issues
-~~~~~~~~~~~~~~~
-
-- Multiple withdrawals/actions
-- Generating illegal state if state is updated twice later
-
-.. _alternativessolutions-4:
-
-Alternatives/Solutions
-~~~~~~~~~~~~~~~~~~~~~~
-
-- Forbid reentrancy by means of a flag in your storage, unless you have
- a good reason to allow users to reenter your contract, this is likely
- the best option.
-- Only make transfers to trusted contracts or default accounts. Default
- accounts cannot execute code, so it is always safe to transfer to
- them. Before trusting a contract, make sure that its behavior cannot
- be modified and that you have an extremely high degree of confidence
- in it.
-
-Do not store funds for others in spendable contracts
-----------------------------------------------------
-
-Tezos allows contracts to be marked as spendable. Managers of spendable
-contracts can make transfers using the funds stored inside the contract.
-This can subvert guarantees about the contract’s behavior that are
-visible in the code.
-
-.. _possible-issues-5:
-
-Possible Issues
-~~~~~~~~~~~~~~~
-
-- The funds of a contract can be removed.
-- A contract may not be able to meet its obligations
-
-.. _alternativessolutions-5:
-
-Alternatives/Solutions
-~~~~~~~~~~~~~~~~~~~~~~
-
-- Do not store funds in spendable contracts that you do not control.
diff --git a/vendors/tezos-modded/docs/tutorials/profiling.rst b/vendors/tezos-modded/docs/tutorials/profiling.rst
deleted file mode 100644
index 4508e1635..000000000
--- a/vendors/tezos-modded/docs/tutorials/profiling.rst
+++ /dev/null
@@ -1,79 +0,0 @@
-Profiling the Tezos node
-========================
-
-Memory profiling the OCaml heap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- Install an OCaml switch with the `statmemprof` patch:
-
- ``4.04.2+statistical-memprof`` or ``4.06.0+statistical-memprof``
-
-- Install ``statmemprof-emacs``.
-
-- Enable loading `statmemprof` into the node.
-
- Add the ``statmemprof-emacs`` package as a dependency to the main package, and add
- ``let () = Statmemprof_emacs.start 1E-4 30 5`` to the ``node_main.ml`` file.
-
- Arguments:
-
- - ``sampling_rate`` is the sampling rate of the profiler. Good value: ``1e-4``.
- - ``callstack_size`` is the size of the fragment of the call stack which is captured for each sampled allocation.
- - ``min_sample_print`` is the minimum number of samples under which the location of an allocation is not displayed.
-
-- Load sturgeon into emacs, by adding this to your ``.emacs``:
-
-::
-
- (let ((opam-share (ignore-errors (car (process-lines "opam" "config" "var" "share")))))
- (when (and opam-share (file-directory-p opam-share))
- (add-to-list 'load-path (expand-file-name "emacs/site-lisp" opam-share))))
-
- (require 'sturgeon)
-
-- Launch the node then connect to it with sturgeon.
-
- If the process is launched with pid ``1234`` then
-
-::
-
- M-x sturgeon-connect
- tezos-nodememprof.1234.sturgeon
-
- (tab-completion works for finding the socket name)
-
-Memory profiling the C heap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- Install ``valgrind`` and ``massif-visualizer``
-
-::
-
- valgrind --tool=massif tezos-node run ...
-
-- Stop with `Ctrl-C` then display with
-
-::
-
- massif-visualizer massif.out.pid
-
-
-Performance profiling
-~~~~~~~~~~~~~~~~~~~~~
-
-- Install `perf` (the ``linux-perf`` package for debian).
-
- If the package does not exist for your current kernel, a previous
- version can be used. Substitute the ``perf`` command to ``perf_4.9``
- if your kernel is 4.9).
-
-- Run the node, find the pid.
-
-- Attach `perf` with ``perf record -p pid --call-stack dwarf``.
-
- Then stop capturing with ``Ctrl-C``. This can represent a lot of
- data. Don't do that for too long. If this is too much you can remove
- the ``--call-stack dwarf`` to get something more manageable, but
- interpreting the information can be harder.
-
-- display the result with ``perf report``
diff --git a/vendors/tezos-modded/docs/tutorials/protocol_environment.rst b/vendors/tezos-modded/docs/tutorials/protocol_environment.rst
deleted file mode 100644
index 31be8eeda..000000000
--- a/vendors/tezos-modded/docs/tutorials/protocol_environment.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-.. _protocol_environment:
-
-Economic protocol sandboxing
-============================
-
-In Alpha, as in any sound future protocols, updates are approved by
-voting. That way, the responsibility of switching to a new protocol code
-is the responsibility of voters, and one could argue that it is up to
-them to check that the code does not call, for instance, unsafe array
-access functions.
-
-Yet, we decided to introduce a minimum level of machine checks, by
-compiling with a specific compiler that checks that no known-unsafe
-function is used. This static form of sandboxing is performed by the
-OCaml typechecker: we simply compile protocols in a restricted set of
-modules with restricted interfaces that hide any unsafe, non wanted
-feature.
-
-Another goal of that specific environment is maintaining a stable OCaml
-API for protocol development. Imagine that at some point, the OCaml
-standard library changes (a function is added or removed, a type is
-changed), then we will be able to upgrade to the new OCaml while still
-remaining compatible with past protocols, by providing an adapter layer.
-
-Here is a quick description of each file in this environment:
-
-- Files ``array.mli``, ``buffer.mli``, ``bytes.mli``, ``format.mli``,
- ``int32.mli``, ``int64.mli``, ``list.mli``, ``map.mli``,
- ``pervasives.mli``, ``set.mli`` and ``string.mli`` are stripped down
- interfaces to the OCaml standard library modules. The removed
- elements are: effects on toplevel references or channels, unsafe
- functions, functions that are known sources of bugs, and anything
- deprecated.
-- As we removed polymorphic comparison operators, ``compare.mli``
- implements monomorphic operators for standard OCaml and Tezos types.
- An example use is ``Compare.Int.(3 = 4)`` instead of plain OCaml
- ``(3 = 4)``.
-- Files ``lwt*`` is the stripped down interface to Lwt, of which we
- removed any non deterministic functions, since we only use Lwt for
- asynchronous access to the storage.
-- Files ``data_encoding.mli``, ``error_monad.mli``, ``mBytes.mli``,
- ``hash.mli``, ``base58.mli``, ``blake2B.mli``, ``ed25519.mli``,
- ``hex_encode.mli``, ``json.mli``, ``time.mli``, ``z.mli``,
- ``micheline.mli`` and files ``RPC_*`` are stripped down versions of
- the Tezos standard library.
-- Files ``tezos_data.mli``, ``context.mli``, ``fitness.mli`` and
- ``updater.mli`` are interfaces to the shell’s data definitions and
- storage accessors that are accessible to the protocol.
diff --git a/vendors/tezos-modded/docs/tutorials/rpc.rst b/vendors/tezos-modded/docs/tutorials/rpc.rst
deleted file mode 100644
index 686d03f51..000000000
--- a/vendors/tezos-modded/docs/tutorials/rpc.rst
+++ /dev/null
@@ -1,73 +0,0 @@
-.. _rpc:
-
-
-JSON/RPC interface
-==================
-
-The Tezos node provides a JSON/RPC interface. Note that it is an RPC,
-and it is JSON based, but it does not follow the “JSON-RPC” protocol. It
-is not active by default and it must be explicitly activated with the
-``--rpc-addr`` option. Typically, if you are not trying to run a local
-network and just want to explore the RPC, you would run:
-
-::
-
- ./tezos-node run --rpc-addr localhost
-
-The RPC interface is self-documented and the ``tezos-client`` executable
-is able to pretty-print the RPC API. For instance, to see the API
-provided by the Tezos Shell:
-
-::
-
- ./tezos-client rpc list
-
-To get API attached to the “genesis” block, including the remote
-procedures provided by the associated economic protocol version:
-
-::
-
- ./tezos-client rpc list /chains/main/blocks/genesis
-
-You might also want the JSON schema describing the expected input and
-output of a RPC. For instance:
-
-::
-
- ./tezos-client rpc schema get /chains/main/blocks/genesis/hash
-
-Note: you can get the same information, but as a raw JSON object, with a
-simple HTTP request:
-
-::
-
- curl -s localhost:8732/chains/main/blocks/head~10
- wget -O - http://localhost:8732/describe?recurse=true
- wget -O - http://localhost:8732/describe/chains/main/blocks/genesis?recurse=true
- wget -O - http://localhost:8732/describe/chains/main/blocks/genesis/hash
-
-
-An online :ref:`index ` of RPC calls is also available.
-
-The general call of an RPC from the client is ``tezos-admin-client rpc
-(get|post) ``.
-For instance, if you wish to request the current balance of a given
-block and contract, you can call the associated RPC via the command :
-``$ tezos-admin-client rpc get
-/blocks//proto/context/contracts//balance``.
-
-An RPC may take an *input* and generate an *output* both in JSON
-format. For example, the previous RPC call, that does not require an
-input, would display on the standard output : ``{ "balance":
-"4000000000000" }``. When calling a RPC that requires an input
-through command-line, you will be prompted to provide the JSON input
-in your default configured text editor. Alternatively, you can provide
-the JSON input using command
-``$ tezos-admin-client rpc post with ``. Don't forget to quote
-the JSON according to your shell rules.
-
-If you want to learn more about the exchange of RPCs between node and
-client you can pass the option `-l` and the client will print all the
-calls with their input/output.
-
-A useful util to manipulate JSON is `jq `_.
diff --git a/vendors/tezos-modded/docs/whitedoc/michelson.rst b/vendors/tezos-modded/docs/whitedoc/michelson.rst
deleted file mode 100644
index a309def41..000000000
--- a/vendors/tezos-modded/docs/whitedoc/michelson.rst
+++ /dev/null
@@ -1,3115 +0,0 @@
-.. _michelson:
-
-Michelson: the language of Smart Contracts in Tezos
-===================================================
-
-The language is stack based, with high level data types and primitives
-and strict static type checking. Its design cherry picks traits from
-several language families. Vigilant readers will notice direct
-references to Forth, Scheme, ML and Cat.
-
-A Michelson program is a series of instructions that are run in
-sequence: each instruction receives as input the stack resulting of the
-previous instruction, and rewrites it for the next one. The stack
-contains both immediate values and heap allocated structures. All values
-are immutable and garbage collected.
-
-A Michelson program receives as input a single element stack containing
-an input value and the contents of a storage space. It must return a
-single element stack containing an output value, a list of internal
-operations, and the new contents of the storage space. Alternatively,
-a Michelson program can fail, explicitly using a specific opcode,
-or because something went wrong that could not be caught by the type
-system (e.g. division by zero, gas exhaustion).
-
-The types of the input, output and storage are fixed and monomorphic,
-and the program is typechecked before being introduced into the system.
-No smart contract execution can fail because an instruction has been
-executed on a stack of unexpected length or contents.
-
-This specification gives the complete instruction set, type system and
-semantics of the language. It is meant as a precise reference manual,
-not an easy introduction. Even though, some examples are provided at the
-end of the document and can be read first or at the same time as the
-specification.
-
-Table of contents
------------------
-
-- I - Semantics
-- II - Type system
-- III - Core data types
-- IV - Core instructions
-- V - Operations
-- VI - Domain specific data types
-- VII - Domain specific operations
-- VIII - Macros
-- IX - Concrete syntax
-- X - JSON syntax
-- XI - Examples
-- XII - Full grammar
-- XIII - Reference implementation
-
-I - Semantics
--------------
-
-This specification gives a detailed formal semantics of the Michelson
-language. It explains in a symbolic way the computation performed by the
-Michelson interpreter on a given program and initial stack to produce
-the corresponding resulting stack. The Michelson interpreter is a pure
-function: it only builds a result stack from the elements of an initial
-one, without affecting its environment. This semantics is then naturally
-given in what is called a big step form: a symbolic definition of a
-recursive reference interpreter. This definition takes the form of a
-list of rules that cover all the possible inputs of the interpreter
-(program and stack), and describe the computation of the corresponding
-resulting stacks.
-
-Rules form and selection
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-The rules have the main following form.
-
-::
-
- > (syntax pattern) / (initial stack pattern) => (result stack pattern)
- iff (conditions)
- where (recursions)
- and (more recursions)
-
-The left hand side of the ``=>`` sign is used for selecting the rule.
-Given a program and an initial stack, one (and only one) rule can be
-selected using the following process. First, the toplevel structure of
-the program must match the syntax pattern. This is quite simple since
-there is only a few non trivial patterns to deal with instruction
-sequences, and the rest is made of trivial pattern that match one
-specific instruction. Then, the initial stack must match the initial
-stack pattern. Finally, some rules add extra conditions over the values
-in the stack that follow the ``iff`` keyword. Sometimes, several rules
-may apply in a given context. In this case, the one that appears first
-in this specification is to be selected. If no rule applies, the result
-is equivalent to the one for the explicit ``FAILWITH`` instruction. This
-case does not happen on well-typed programs, as explained in the next
-section.
-
-The right hand side describes the result of the interpreter if the rule
-applies. It consists in a stack pattern, whose part are either
-constants, or elements of the context (program and initial stack) that
-have been named on the left hand side of the ``=>`` sign.
-
-Recursive rules (big step form)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Sometimes, the result of interpreting a program is derived from the
-result of interpreting another one (as in conditionals or function
-calls). In these cases, the rule contains a clause of the following
-form.
-
-::
-
- where (intermediate program) / (intermediate stack) => (partial result)
-
-This means that this rules applies in case interpreting the intermediate
-state on the left gives the pattern on the right.
-
-The left hand sign of the ``=>`` sign is constructed from elements of
-the initial state or other partial results, and the right hand side
-identify parts that can be used to build the result stack of the rule.
-
-If the partial result pattern does not actually match the result of the
-interpretation, then the result of the whole rule is equivalent to the
-one for the explicit ``FAILWITH`` instruction. Again, this case does not
-happen on well-typed programs, as explained in the next section.
-
-Format of patterns
-~~~~~~~~~~~~~~~~~~
-
-Code patterns are of one of the following syntactical forms.
-
-- ``INSTR`` (an uppercase identifier) is a simple instruction (e.g.
- ``DROP``);
-- ``INSTR (arg) ...`` is a compound instruction, whose arguments can be
- code, data or type patterns (e.g. ``PUSH nat 3``) ;
-- ``{ (instr) ; ... }`` is a possibly empty sequence of instructions,
- (e.g. ``IF { SWAP ; DROP } { DROP }``), nested sequences can drop the
- braces ;
-- ``name`` is a pattern that matches any program and names a part of
- the matched program that can be used to build the result ;
-- ``_`` is a pattern that matches any instruction.
-
-Stack patterns are of one of the following syntactical forms.
-
-- ``[FAILED]`` is the special failed state ;
-- ``[]`` is the empty stack ;
-- ``(top) : (rest)`` is a stack whose top element is matched by the
- data pattern ``(top)`` on the left, and whose remaining elements are
- matched by the stack pattern ``(rest)`` on the right (e.g.
- ``x : y : rest``) ;
-- ``name`` is a pattern that matches any stack and names it in order to
- use it to build the result ;
-- ``_`` is a pattern that matches any stack.
-
-Data patterns are of one of the following syntactical forms.
-
-- integer/natural number literals, (e.g. ``3``) ;
-- string literals, (e.g. ``"contents"``) ;
-- raw byte sequence literals (e.g. ``0xABCDEF42``)
-- ``Tag`` (capitalized) is a symbolic constant, (e.g. ``Unit``,
- ``True``, ``False``) ;
-- ``(Tag (arg) ...)`` tagged constructed data, (e.g. ``(Pair 3 4)``) ;
-- a code pattern for first class code values ;
-- ``name`` to name a value in order to use it to build the result ;
-- ``_`` to match any value.
-
-The domain of instruction names, symbolic constants and data
-constructors is fixed by this specification. Michelson does not let the
-programmer introduce its own types.
-
-Be aware that the syntax used in the specification may differ a bit from
-the concrete syntax, which is presented in Section IX. In particular,
-some instructions are annotated with types that are not present in the
-concrete language because they are synthesized by the typechecker.
-
-Shortcuts
-~~~~~~~~~
-
-Sometimes, it is easier to think (and shorter to write) in terms of
-program rewriting than in terms of big step semantics. When it is the
-case, and when both are equivalents, we write rules of the form:
-
-::
-
- p / S => S''
- where p' / S' => S''
-
-using the following shortcut:
-
-::
-
- p / S => p' / S'
-
-The concrete language also has some syntax sugar to group some common
-sequences of operations as one. This is described in this specification
-using a simple regular expression style recursive instruction rewriting.
-
-II - Introduction to the type system and notations
---------------------------------------------------
-
-This specification describes a type system for Michelson. To make things
-clear, in particular to readers that are not accustomed to reading
-formal programming language specifications, it does not give a
-typechecking or inference algorithm. It only gives an intentional
-definition of what we consider to be well-typed programs. For each
-syntactical form, it describes the stacks that are considered well-typed
-inputs, and the resulting outputs.
-
-The type system is sound, meaning that if a program can be given a type,
-then if run on a well-typed input stack, the interpreter will never
-apply an interpretation rule on a stack of unexpected length or
-contents. Also, it will never reach a state where it cannot select an
-appropriate rule to continue the execution. Well-typed programs do not
-block, and do not go wrong.
-
-Type notations
-~~~~~~~~~~~~~~
-
-The specification introduces notations for the types of values, terms
-and stacks. Apart from a subset of value types that appear in the form
-of type annotations in some places throughout the language, it is
-important to understand that this type language only exists in the
-specification.
-
-A stack type can be written:
-
-- ``[]`` for the empty stack ;
-- ``(top) : (rest)`` for the stack whose first value has type ``(top)``
- and queue has stack type ``(rest)``.
-
-Instructions, programs and primitives of the language are also typed,
-their types are written:
-
-::
-
- (type of stack before) -> (type of stack after)
-
-The types of values in the stack are written:
-
-- ``identifier`` for a primitive data-type (e.g. ``bool``),
-- ``identifier (arg)`` for a parametric data-type with one parameter
- type ``(arg)`` (e.g. ``list nat``),
-- ``identifier (arg) ...`` for a parametric data-type with several
- parameters (e.g. ``map string int``),
-- ``[ (type of stack before) -> (type of stack after) ]`` for a code
- quotation, (e.g. ``[ int : int : [] -> int : [] ]``),
-- ``lambda (arg) (ret)`` is a shortcut for
- ``[ (arg) : [] -> (ret) : [] ]``.
-
-Meta type variables
-~~~~~~~~~~~~~~~~~~~
-
-The typing rules introduce meta type variables. To be clear, this has
-nothing to do with polymorphism, which Michelson does not have. These
-variables only live at the specification level, and are used to express
-the consistency between the parts of the program. For instance, the
-typing rule for the ``IF`` construct introduces meta variables to
-express that both branches must have the same type.
-
-Here are the notations for meta type variables:
-
-- ``'a`` for a type variable,
-- ``'A`` for a stack type variable,
-- ``_`` for an anonymous type or stack type variable.
-
-Typing rules
-~~~~~~~~~~~~
-
-The system is syntax directed, which means here that it defines a single
-typing rule for each syntax construct. A typing rule restricts the type
-of input stacks that are authorized for this syntax construct, links the
-output type to the input type, and links both of them to the
-subexpressions when needed, using meta type variables.
-
-Typing rules are of the form:
-
-::
-
- (syntax pattern)
- :: (type of stack before) -> (type of stack after) [rule-name]
- iff (premises)
-
-Where premises are typing requirements over subprograms or values in the
-stack, both of the form ``(x) :: (type)``, meaning that value ``(x)``
-must have type ``(type)``.
-
-A program is shown well-typed if one can find an instance of a rule that
-applies to the toplevel program expression, with all meta type variables
-replaced by non variable type expressions, and of which all type
-requirements in the premises can be proven well-typed in the same
-manner. For the reader unfamiliar with formal type systems, this is
-called building a typing derivation.
-
-Here is an example typing derivation on a small program that computes
-``(x+5)*10`` for a given input ``x``, obtained by instantiating the
-typing rules for instructions ``PUSH``, ``ADD`` and for the sequence, as
-found in the next sections. When instantiating, we replace the ``iff``
-with ``by``.
-
-::
-
- { PUSH nat 5 ; ADD ; PUSH nat 10 ; SWAP ; MUL }
- :: [ nat : [] -> nat : [] ]
- by { PUSH nat 5 ; ADD }
- :: [ nat : [] -> nat : [] ]
- by PUSH nat 5
- :: [ nat : [] -> nat : nat : [] ]
- by 5 :: nat
- and ADD
- :: [ nat : nat : [] -> nat : [] ]
- and { PUSH nat 10 ; SWAP ; MUL }
- :: [ nat : [] -> nat : [] ]
- by PUSH nat 10
- :: [ nat : [] -> nat : nat : [] ]
- by 10 :: nat
- and { SWAP ; MUL }
- :: [ nat : nat : [] -> nat : [] ]
- by SWAP
- :: [ nat : nat : [] -> nat : nat : [] ]
- and MUL
- :: [ nat : nat : [] -> nat : [] ]
-
-Producing such a typing derivation can be done in a number of manners,
-such as unification or abstract interpretation. In the implementation of
-Michelson, this is done by performing a recursive symbolic evaluation of
-the program on an abstract stack representing the input type provided by
-the programmer, and checking that the resulting symbolic stack is
-consistent with the expected result, also provided by the programmer.
-
-Side note
-~~~~~~~~~
-
-As with most type systems, it is incomplete. There are programs that
-cannot be given a type in this type system, yet that would not go wrong
-if executed. This is a necessary compromise to make the type system
-usable. Also, it is important to remember that the implementation of
-Michelson does not accept as many programs as the type system describes
-as well-typed. This is because the implementation uses a simple single
-pass typechecking algorithm, and does not handle any form of
-polymorphism.
-
-III - Core data types and notations
------------------------------------
-
-- ``string``, ``nat``, ``int`` and ``bytes``: The core primitive
- constant types.
-
-- ``bool``: The type for booleans whose values are ``True`` and
- ``False``
-
-- ``unit``: The type whose only value is ``Unit``, to use as a
- placeholder when some result or parameter is non necessary. For
- instance, when the only goal of a contract is to update its storage.
-
-- ``list (t)``: A single, immutable, homogeneous linked list, whose
- elements are of type ``(t)``, and that we note ``{}`` for the empty
- list or ``{ first ; ... }``. In the semantics, we use chevrons to
- denote a subsequence of elements. For instance ``{ head ; }``.
-
-- ``pair (l) (r)``: A pair of values ``a`` and ``b`` of types ``(l)``
- and ``(r)``, that we write ``(Pair a b)``.
-
-- ``option (t)``: Optional value of type ``(t)`` that we note ``None``
- or ``(Some v)``.
-
-- ``or (l) (r)``: A union of two types: a value holding either a value
- ``a`` of type ``(l)`` or a value ``b`` of type ``(r)``, that we write
- ``(Left a)`` or ``(Right b)``.
-
-- ``set (t)``: Immutable sets of values of type ``(t)`` that we note as
- lists ``{ item ; ... }``, of course with their elements unique, and
- sorted.
-
-- ``map (k) (t)``: Immutable maps from keys of type ``(k)`` of values
- of type ``(t)`` that we note ``{ Elt key value ; ... }``, with keys
- sorted.
-- ``big_map (k) (t)``: Lazily deserialized maps from keys of type
- ``(k)`` of values of type ``(t)`` that we note ``{ Elt key value ; ... }``,
- with keys sorted. These maps should be used if you intend to store
- large amounts of data in a map. They have higher gas costs than
- standard maps as data is lazily deserialized. You are limited to a
- single ``big_map`` per program, which must appear on the left hand
- side of a pair in the contract's storage.
-
-IV - Core instructions
-----------------------
-
-Control structures
-~~~~~~~~~~~~~~~~~~
-
-- ``FAILWITH``: Explicitly abort the current program.
-
- 'a :: \_ -> \_
-
- This special instruction aborts the current program exposing the top
- of the stack in its error message (first rule below). It makes the
- output useless since all subsequent instructions will simply ignore
- their usual semantics to propagate the failure up to the main result
- (second rule below). Its type is thus completely generic.
-
-::
-
- > FAILWITH / a : _ => [FAILED]
- > _ / [FAILED] => [FAILED]
-
-- ``{}``: Empty sequence.
-
-::
-
- :: 'A -> 'A
-
- > {} / SA => SA
-
-- ``{ I ; C }``: Sequence.
-
-::
-
- :: 'A -> 'C
- iff I :: [ 'A -> 'B ]
- C :: [ 'B -> 'C ]
-
- > I ; C / SA => SC
- where I / SA => SB
- and C / SB => SC
-
-- ``IF bt bf``: Conditional branching.
-
-::
-
- :: bool : 'A -> 'B
- iff bt :: [ 'A -> 'B ]
- bf :: [ 'A -> 'B ]
-
- > IF bt bf / True : S => bt / S
- > IF bt bf / False : S => bf / S
-
-- ``LOOP body``: A generic loop.
-
-::
-
- :: bool : 'A -> 'A
- iff body :: [ 'A -> bool : 'A ]
-
- > LOOP body / True : S => body ; LOOP body / S
- > LOOP body / False : S => S
-
-- ``LOOP_LEFT body``: A loop with an accumulator
-
-::
-
- :: (or 'a 'b) : 'A -> 'b : 'A
- iff body :: [ 'a : 'A -> (or 'a 'b) : 'A ]
-
- > LOOP_LEFT body / (Left a) : S => body ; LOOP_LEFT body / a : S
- > LOOP_LEFT body / (Right b) : S => b : S
-
-- ``DIP code``: Runs code protecting the top of the stack.
-
-::
-
- :: 'b : 'A -> 'b : 'C
- iff code :: [ 'A -> 'C ]
-
- > DIP code / x : S => x : S'
- where code / S => S'
-
-- ``EXEC``: Execute a function from the stack.
-
-::
-
- :: 'a : lambda 'a 'b : 'C -> 'b : 'C
-
- > EXEC / a : f : S => r : S
- where f / a : [] => r : []
-
-Stack operations
-~~~~~~~~~~~~~~~~
-
-- ``DROP``: Drop the top element of the stack.
-
-::
-
- :: _ : 'A -> 'A
-
- > DROP / _ : S => S
-
-- ``DUP``: Duplicate the top of the stack.
-
-::
-
- :: 'a : 'A -> 'a : 'a : 'A
-
- > DUP / x : S => x : x : S
-
-- ``SWAP``: Exchange the top two elements of the stack.
-
-::
-
- :: 'a : 'b : 'A -> 'b : 'a : 'A
-
- > SWAP / x : y : S => y : x : S
-
-- ``PUSH 'a x``: Push a constant value of a given type onto the stack.
-
-::
-
- :: 'A -> 'a : 'A
- iff x :: 'a
-
- > PUSH 'a x / S => x : S
-
-- ``UNIT``: Push a unit value onto the stack.
-
-::
-
- :: 'A -> unit : 'A
-
- > UNIT / S => Unit : S
-
-- ``LAMBDA 'a 'b code``: Push a lambda with given parameter and return
- types onto the stack.
-
-::
-
- :: 'A -> (lambda 'a 'b) : 'A
-
- > LAMBDA _ _ code / S => code : S
-
-Generic comparison
-~~~~~~~~~~~~~~~~~~
-
-Comparison only works on a class of types that we call comparable. A
-``COMPARE`` operation is defined in an ad hoc way for each comparable
-type, but the result of compare is always an ``int``, which can in turn
-be checked in a generic manner using the following combinators. The
-result of ``COMPARE`` is ``0`` if the top two elements of the stack are
-equal, negative if the first element in the stack is less than the
-second, and positive otherwise.
-
-- ``EQ``: Checks that the top of the stack EQuals zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > EQ / 0 : S => True : S
- > EQ / v : S => False : S
- iff v <> 0
-
-- ``NEQ``: Checks that the top of the stack does Not EQual zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > NEQ / 0 : S => False : S
- > NEQ / v : S => True : S
- iff v <> 0
-
-- ``LT``: Checks that the top of the stack is Less Than zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > LT / v : S => True : S
- iff v < 0
- > LT / v : S => False : S
- iff v >= 0
-
-- ``GT``: Checks that the top of the stack is Greater Than zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > GT / v : S => C / True : S
- iff v > 0
- > GT / v : S => C / False : S
- iff v <= 0
-
-- ``LE``: Checks that the top of the stack is Less Than of Equal to
- zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > LE / v : S => True : S
- iff v <= 0
- > LE / v : S => False : S
- iff v > 0
-
-- ``GE``: Checks that the top of the stack is Greater Than of Equal to
- zero.
-
-::
-
- :: int : 'S -> bool : 'S
-
- > GE / v : S => True : S
- iff v >= 0
- > GE / v : S => False : S
- iff v < 0
-
-V - Operations
---------------
-
-Operations on booleans
-~~~~~~~~~~~~~~~~~~~~~~
-
-- ``OR``
-
-::
-
- :: bool : bool : 'S -> bool : 'S
-
- > OR / x : y : S => (x | y) : S
-
-- ``AND``
-
-::
-
- :: bool : bool : 'S -> bool : 'S
-
- > AND / x : y : S => (x & y) : S
-
-- ``XOR``
-
-::
-
- :: bool : bool : 'S -> bool : 'S
-
- > XOR / x : y : S => (x ^ y) : S
-
-- ``NOT``
-
-::
-
- :: bool : 'S -> bool : 'S
-
- > NOT / x : S => ~x : S
-
-Operations on integers and natural numbers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Integers and naturals are arbitrary-precision, meaning the only size
-limit is fuel.
-
-- ``NEG``
-
-::
-
- :: int : 'S -> int : 'S
- :: nat : 'S -> int : 'S
-
- > NEG / x : S => -x : S
-
-- ``ABS``
-
-::
-
- :: int : 'S -> nat : 'S
-
- > ABS / x : S => abs (x) : S
-
-- ``ADD``
-
-::
-
- :: int : int : 'S -> int : 'S
- :: int : nat : 'S -> int : 'S
- :: nat : int : 'S -> int : 'S
- :: nat : nat : 'S -> nat : 'S
-
- > ADD / x : y : S => (x + y) : S
-
-- ``SUB``
-
-::
-
- :: int : int : 'S -> int : 'S
- :: int : nat : 'S -> int : 'S
- :: nat : int : 'S -> int : 'S
- :: nat : nat : 'S -> int : 'S
-
- > SUB / x : y : S => (x - y) : S
-
-- ``MUL``
-
-::
-
- :: int : int : 'S -> int : 'S
- :: int : nat : 'S -> int : 'S
- :: nat : int : 'S -> int : 'S
- :: nat : nat : 'S -> nat : 'S
-
- > MUL / x : y : S => (x * y) : S
-
-- ``EDIV`` Perform Euclidian division
-
-::
-
- :: int : int : 'S -> option (pair int nat) : 'S
- :: int : nat : 'S -> option (pair int nat) : 'S
- :: nat : int : 'S -> option (pair int nat) : 'S
- :: nat : nat : 'S -> option (pair nat nat) : 'S
-
- > EDIV / x : 0 : S => None : S
- > EDIV / x : y : S => Some (Pair (x / y) (x % y)) : S
- iff y <> 0
-
-Bitwise logical operators are also available on unsigned integers.
-
-- ``OR``
-
-::
-
- :: nat : nat : 'S -> nat : 'S
-
- > OR / x : y : S => (x | y) : S
-
-- ``AND`` (also available when the top operand is signed)
-
-::
-
- :: nat : nat : 'S -> nat : 'S
- :: int : nat : 'S -> nat : 'S
-
- > AND / x : y : S => (x & y) : S
-
-- ``XOR``
-
-::
-
- :: nat : nat : 'S -> nat : 'S
-
- > XOR / x : y : S => (x ^ y) : S
-
-- ``NOT`` The return type of ``NOT`` is an ``int`` and not a ``nat``.
- This is because the sign is also negated. The resulting integer is
- computed using two's complement. For instance, the boolean negation
- of ``0`` is ``-1``. To get a natural back, a possibility is to use
- ``AND`` with an unsigned mask afterwards.
-
-::
-
- :: nat : 'S -> int : 'S
- :: int : 'S -> int : 'S
-
- > NOT / x : S => ~x : S
-
-- ``LSL``
-
-::
-
- :: nat : nat : 'S -> nat : 'S
-
- > LSL / x : s : S => (x << s) : S
- iff s <= 256
- > LSL / x : s : S => [FAILED]
- iff s > 256
-
-- ``LSR``
-
-::
-
- :: nat : nat : 'S -> nat : 'S
-
- > LSR / x : s : S => (x >> s) : S
-
-- ``COMPARE``: Integer/natural comparison
-
-::
-
- :: int : int : 'S -> int : 'S
- :: nat : nat : 'S -> int : 'S
-
- > COMPARE / x : y : S => -1 : S
- iff x < y
- > COMPARE / x : y : S => 0 : S
- iff x = y
- > COMPARE / x : y : S => 1 : S
- iff x > y
-
-Operations on strings
-~~~~~~~~~~~~~~~~~~~~~
-
-Strings are mostly used for naming things without having to rely on
-external ID databases. They are restricted to the printable subset of
-7-bit ASCII, plus some escaped characters (see section on
-constants). So what can be done is basically use string constants as
-is, concatenate or splice them, and use them as keys.
-
-
-- ``CONCAT``: String concatenation.
-
-::
-
- :: string : string : 'S -> string : 'S
-
- > CONCAT / s : t : S => (s ^ t) : S
-
- :: string list : 'S -> string : 'S
-
- > CONCAT / {} : S => "" : S
- > CONCAT / { s ; } : S => (s ^ r) : S
- where CONCAT / { } : S => r : S
-
-- ``SIZE``: number of characters in a string.
-
-::
-
- :: string : 'S -> nat : 'S
-
-- ``SLICE``: String access.
-
-::
-
- :: nat : nat : string : 'S -> option string : 'S
-
- > SLICE / offset : length : s : S => Some ss : S
- where ss is the substring of s at the given offset and of the given length
- iff offset and (offset + length) are in bounds
- > SLICE / offset : length : s : S => None : S
- iff offset or (offset + length) are out of bounds
-
-- ``COMPARE``: Lexicographic comparison.
-
-::
-
- :: string : string : 'S -> int : 'S
-
- > COMPARE / s : t : S => -1 : S
- iff s < t
- > COMPARE / s : t : S => 0 : S
- iff s = t
- > COMPARE / s : t : S => 1 : S
- iff s > t
-
-Operations on pairs
-~~~~~~~~~~~~~~~~~~~
-
-- ``PAIR``: Build a pair from the stack's top two elements.
-
-::
-
- :: 'a : 'b : 'S -> pair 'a 'b : 'S
-
- > PAIR / a : b : S => (Pair a b) : S
-
-- ``CAR``: Access the left part of a pair.
-
-::
-
- :: pair 'a _ : 'S -> 'a : 'S
-
- > CAR / (Pair a _) : S => a : S
-
-- ``CDR``: Access the right part of a pair.
-
-::
-
- :: pair _ 'b : 'S -> 'b : 'S
-
- > CDR / (Pair _ b) : S => b : S
-
-Operations on sets
-~~~~~~~~~~~~~~~~~~
-
-- ``EMPTY_SET 'elt``: Build a new, empty set for elements of a given
- type.
-
- The ``'elt`` type must be comparable (the ``COMPARE``
- primitive must be defined over it).
-
-::
-
- :: 'S -> set 'elt : 'S
-
- > EMPTY_SET _ / S => {} : S
-
-- ``MEM``: Check for the presence of an element in a set.
-
-::
-
- :: 'elt : set 'elt : 'S -> bool : 'S
-
- > MEM / x : {} : S => false : S
- > MEM / x : { hd ; } : S => r : S
- iff COMPARE / x : hd : [] => 1 : []
- where MEM / x : { } : S => r : S
- > MEM / x : { hd ; } : S => true : S
- iff COMPARE / x : hd : [] => 0 : []
- > MEM / x : { hd ; } : S => false : S
- iff COMPARE / x : hd : [] => -1 : []
-
-- ``UPDATE``: Inserts or removes an element in a set, replacing a
- previous value.
-
-::
-
- :: 'elt : bool : set 'elt : 'S -> set 'elt : 'S
-
- > UPDATE / x : false : {} : S => {} : S
- > UPDATE / x : true : {} : S => { x } : S
- > UPDATE / x : v : { hd ; } : S => { hd ; } : S
- iff COMPARE / x : hd : [] => 1 : []
- where UPDATE / x : v : { } : S => { } : S
- > UPDATE / x : false : { hd ; } : S => { } : S
- iff COMPARE / x : hd : [] => 0 : []
- > UPDATE / x : true : { hd ; } : S => { hd ; } : S
- iff COMPARE / x : hd : [] => 0 : []
- > UPDATE / x : false : { hd ; } : S => { hd ; } : S
- iff COMPARE / x : hd : [] => -1 : []
- > UPDATE / x : true : { hd ; } : S => { x ; hd ; } : S
- iff COMPARE / x : hd : [] => -1 : []
-
-- ``ITER body``: Apply the body expression to each element of a set.
- The body sequence has access to the stack.
-
-::
-
- :: (set 'elt) : 'A -> 'A
- iff body :: [ 'elt : 'A -> 'A ]
-
- > ITER body / {} : S => S
- > ITER body / { hd ; } : S => body; ITER body / hd : { } : S
-
-- ``SIZE``: Get the cardinality of the set.
-
-::
-
- :: set 'elt : 'S -> nat : 'S
-
- > SIZE / {} : S => 0 : S
- > SIZE / { _ ; } : S => 1 + s : S
- where SIZE / { } : S => s : S
-
-Operations on maps
-~~~~~~~~~~~~~~~~~~
-
-- ``EMPTY_MAP 'key 'val``: Build a new, empty map from keys of a
- given type to values of another given type.
-
- The ``'key`` type must be comparable (the ``COMPARE`` primitive must
- be defined over it).
-
-::
-
- :: 'S -> map 'key 'val : 'S
-
- > EMPTY_MAP _ _ / S => {} : S
-
-
-- ``GET``: Access an element in a map, returns an optional value to be
- checked with ``IF_SOME``.
-
-::
-
- :: 'key : map 'key 'val : 'S -> option 'val : 'S
-
- > GET / x : {} : S => None : S
- > GET / x : { Elt k v ; } : S => opt_y : S
- iff COMPARE / x : k : [] => 1 : []
- where GET / x : { } : S => opt_y : S
- > GET / x : { Elt k v ; } : S => Some v : S
- iff COMPARE / x : k : [] => 0 : []
- > GET / x : { Elt k v ; } : S => None : S
- iff COMPARE / x : k : [] => -1 : []
-
-- ``MEM``: Check for the presence of a binding for a key in a map.
-
-::
-
- :: 'key : map 'key 'val : 'S -> bool : 'S
-
- > MEM / x : {} : S => false : S
- > MEM / x : { Elt k v ; } : S => r : S
- iff COMPARE / x : k : [] => 1 : []
- where MEM / x : { } : S => r : S
- > MEM / x : { Elt k v ; } : S => true : S
- iff COMPARE / x : k : [] => 0 : []
- > MEM / x : { Elt k v ; } : S => false : S
- iff COMPARE / x : k : [] => -1 : []
-
-- ``UPDATE``: Assign or remove an element in a map.
-
-::
-
- :: 'key : option 'val : map 'key 'val : 'S -> map 'key 'val : 'S
-
- > UPDATE / x : None : {} : S => {} : S
- > UPDATE / x : Some y : {} : S => { Elt x y } : S
- > UPDATE / x : opt_y : { Elt k v ; } : S => { Elt k v ; } : S
- iff COMPARE / x : k : [] => 1 : []
- where UPDATE / x : opt_y : { } : S => { } : S
- > UPDATE / x : None : { Elt k v ; } : S => { } : S
- iff COMPARE / x : k : [] => 0 : []
- > UPDATE / x : Some y : { Elt k v ; } : S => { Elt k y ; } : S
- iff COMPARE / x : k : [] => 0 : []
- > UPDATE / x : None : { Elt k v ; } : S => { Elt k v ; } : S
- iff COMPARE / x : k : [] => -1 : []
- > UPDATE / x : Some y : { Elt k v ; } : S => { Elt x y ; Elt k v ; } : S
- iff COMPARE / x : k : [] => -1 : []
-
-- ``MAP body``: Apply the body expression to each element of a map. The
- body sequence has access to the stack.
-
-::
-
- :: (map 'key 'val) : 'A -> (map 'key 'b) : 'A
- iff body :: [ (pair 'key 'val) : 'A -> 'b : 'A ]
-
- > MAP body / {} : S => {} : S
- > MAP body / { Elt k v ; } : S => { Elt k (body (Pair k v)) ; } : S
- where MAP body / { } : S => { } : S
-
-- ``ITER body``: Apply the body expression to each element of a map.
- The body sequence has access to the stack.
-
-::
-
- :: (map 'elt 'val) : 'A -> 'A
- iff body :: [ (pair 'elt 'val : 'A) -> 'A ]
-
- > ITER body / {} : S => S
- > ITER body / { Elt k v ; } : S => body ; ITER body / (Pair k v) : { } : S
-
-- ``SIZE``: Get the cardinality of the map.
-
-::
-
- :: map 'key 'val : 'S -> nat : 'S
-
- > SIZE / {} : S => 0 : S
- > SIZE / { _ ; } : S => 1 + s : S
- where SIZE / { } : S => s : S
-
-
-Operations on ``big_maps``
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The behavior of these operations is the same as if they were normal
-maps, except that under the hood, the elements are loaded and
-deserialized on demand.
-
-
-- ``GET``: Access an element in a ``big_map``, returns an optional value to be
- checked with ``IF_SOME``.
-
-::
-
- :: 'key : big_map 'key 'val : 'S -> option 'val : 'S
-
-- ``MEM``: Check for the presence of an element in a ``big_map``.
-
-::
-
- :: 'key : big_map 'key 'val : 'S -> bool : 'S
-
-- ``UPDATE``: Assign or remove an element in a ``big_map``.
-
-::
-
- :: 'key : option 'val : big_map 'key 'val : 'S -> big_map 'key 'val : 'S
-
-
-Operations on optional values
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- ``SOME``: Pack a present optional value.
-
-::
-
- :: 'a : 'S -> option 'a : 'S
-
- > SOME / v : S => (Some v) : S
-
-- ``NONE 'a``: The absent optional value.
-
-::
-
- :: 'S -> option 'a : 'S
-
- > NONE / v : S => None : S
-
-- ``IF_NONE bt bf``: Inspect an optional value.
-
-::
-
- :: option 'a : 'S -> 'b : 'S
- iff bt :: [ 'S -> 'b : 'S]
- bf :: [ 'a : 'S -> 'b : 'S]
-
- > IF_NONE bt bf / (None) : S => bt / S
- > IF_NONE bt bf / (Some a) : S => bf / a : S
-
-Operations on unions
-~~~~~~~~~~~~~~~~~~~~
-
-- ``LEFT 'b``: Pack a value in a union (left case).
-
-::
-
- :: 'a : 'S -> or 'a 'b : 'S
-
- > LEFT / v : S => (Left v) : S
-
-- ``RIGHT 'a``: Pack a value in a union (right case).
-
-::
-
- :: 'b : 'S -> or 'a 'b : 'S
-
- > RIGHT / v : S => (Right v) : S
-
-- ``IF_LEFT bt bf``: Inspect a value of a union.
-
-::
-
- :: or 'a 'b : 'S -> 'c : 'S
- iff bt :: [ 'a : 'S -> 'c : 'S]
- bf :: [ 'b : 'S -> 'c : 'S]
-
- > IF_LEFT bt bf / (Left a) : S => bt / a : S
- > IF_LEFT bt bf / (Right b) : S => bf / b : S
-
-- ``IF_RIGHT bt bf``: Inspect a value of a union.
-
-::
-
- :: or 'a 'b : 'S -> 'c : 'S
- iff bt :: [ 'b : 'S -> 'c : 'S]
- bf :: [ 'a : 'S -> 'c : 'S]
-
- > IF_RIGHT bt bf / (Right b) : S => bt / b : S
- > IF_RIGHT bt bf / (Left a) : S => bf / a : S
-
-Operations on lists
-~~~~~~~~~~~~~~~~~~~
-
-- ``CONS``: Prepend an element to a list.
-
-::
-
- :: 'a : list 'a : 'S -> list 'a : 'S
-
- > CONS / a : { } : S => { a ; } : S
-
-- ``NIL 'a``: The empty list.
-
-::
-
- :: 'S -> list 'a : 'S
-
- > NIL / S => {} : S
-
-- ``IF_CONS bt bf``: Inspect a list.
-
-::
-
- :: list 'a : 'S -> 'b : 'S
- iff bt :: [ 'a : list 'a : 'S -> 'b : 'S]
- bf :: [ 'S -> 'b : 'S]
-
- > IF_CONS bt bf / { a ; } : S => bt / a : { } : S
- > IF_CONS bt bf / {} : S => bf / S
-
-- ``MAP body``: Apply the body expression to each element of the list.
- The body sequence has access to the stack.
-
-::
-
- :: (list 'elt) : 'A -> (list 'b) : 'A
- iff body :: [ 'elt : 'A -> 'b : 'A ]
-
- > MAP body / { a ; } : S => { body a ; } : S
- where MAP body / { } : S => { } : S
- > MAP body / {} : S => {} : S
-
-- ``SIZE``: Get the number of elements in the list.
-
-::
-
- :: list 'elt : 'S -> nat : 'S
-
- > SIZE / { _ ; } : S => 1 + s : S
- where SIZE / { } : S => s : S
- > SIZE / {} : S => 0 : S
-
-
-- ``ITER body``: Apply the body expression to each element of a list.
- The body sequence has access to the stack.
-
-::
-
- :: (list 'elt) : 'A -> 'A
- iff body :: [ 'elt : 'A -> 'A ]
- > ITER body / { a ; } : S => body ; ITER body / a : { } : S
- > ITER body / {} : S => S
-
-
-VI - Domain specific data types
--------------------------------
-
-- ``timestamp``: Dates in the real world.
-
-- ``mutez``: A specific type for manipulating tokens.
-
-- ``contract 'param``: A contract, with the type of its code.
-
-- ``address``: An untyped contract address.
-
-- ``operation``: An internal operation emitted by a contract.
-
-- ``key``: A public cryptography key.
-
-- ``key_hash``: The hash of a public cryptography key.
-
-- ``signature``: A cryptographic signature.
-
-VII - Domain specific operations
---------------------------------
-
-Operations on timestamps
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-Current Timestamps can be obtained by the ``NOW`` operation, or
-retrieved from script parameters or globals.
-
-- ``ADD`` Increment / decrement a timestamp of the given number of
- seconds.
-
-::
-
- :: timestamp : int : 'S -> timestamp : 'S
- :: int : timestamp : 'S -> timestamp : 'S
-
- > ADD / seconds : nat (t) : S => (seconds + t) : S
- > ADD / nat (t) : seconds : S => (t + seconds) : S
-
-- ``SUB`` Subtract a number of seconds from a timestamp.
-
-::
-
- :: timestamp : int : 'S -> timestamp : 'S
-
- > SUB / seconds : nat (t) : S => (seconds - t) : S
-
-- ``SUB`` Subtract two timestamps.
-
-::
-
- :: timestamp : timestamp : 'S -> int : 'S
-
- > SUB / seconds(t1) : seconds(t2) : S => (t1 - t2) : S
-
-- ``COMPARE``: Timestamp comparison.
-
-::
-
- :: timestamp : timestamp : 'S -> int : 'S
-
- > COMPARE / seconds(t1) : seconds(t2) : S => -1 : S
- iff t1 < t2
- > COMPARE / seconds(t1) : seconds(t2) : S => 0 : S
- iff t1 = t2
- > COMPARE / seconds(t1) : seconds(t2) : S => 1 : S
- iff t1 > t2
-
-
-Operations on Mutez
-~~~~~~~~~~~~~~~~~~~
-
-Mutez (micro-Tez) are internally represented by a 64 bit signed
-integers. There are restrictions to prevent creating a negative amount
-of mutez. Operations are limited to prevent overflow and mixing them
-with other numerical types by mistake. They are also mandatory checked
-for under/overflows.
-
-- ``ADD``:
-
-::
-
- :: mutez : mutez : 'S -> mutez : 'S
-
- > ADD / x : y : S => [FAILED] on overflow
- > ADD / x : y : S => (x + y) : S
-
-- ``SUB``:
-
-::
-
- :: mutez : mutez : 'S -> mutez : 'S
-
- > SUB / x : y : S => [FAILED]
- iff x < y
- > SUB / x : y : S => (x - y) : S
-
-- ``MUL``
-
-::
-
- :: mutez : nat : 'S -> mutez : 'S
- :: nat : mutez : 'S -> mutez : 'S
-
- > MUL / x : y : S => [FAILED] on overflow
- > MUL / x : y : S => (x * y) : S
-
-- ``EDIV``
-
-::
-
- :: mutez : nat : 'S -> option (pair mutez mutez) : 'S
- :: mutez : mutez : 'S -> option (pair nat mutez) : 'S
-
- > EDIV / x : 0 : S => None
- > EDIV / x : y : S => Some (Pair (x / y) (x % y)) : S
- iff y <> 0
-
-- ``COMPARE``
-
-::
-
- :: mutez : mutez : 'S -> int : 'S
-
- > COMPARE / x : y : S => -1 : S
- iff x < y
- > COMPARE / x : y : S => 0 : S
- iff x = y
- > COMPARE / x : y : S => 1 : S
- iff x > y
-
-Operations on contracts
-~~~~~~~~~~~~~~~~~~~~~~~
-
-- ``CREATE_CONTRACT``: Forge a contract creation operation.
-
-::
-
- :: key_hash : option key_hash : bool : bool : mutez : lambda (pair 'p 'g) (pair (list operation) 'g) : 'g : 'S
- -> operation : address : 'S
-
-As with non code-emitted originations the contract code takes as
-argument the transferred amount plus an ad-hoc argument and returns an
-ad-hoc value. The code also takes the global data and returns it to be
-stored and retrieved on the next transaction. These data are initialized
-by another parameter. The calling convention for the code is as follows:
-``(Pair arg globals) -> (Pair operations globals)``, as extrapolated from
-the instruction type. The first parameters are the manager, optional
-delegate, then spendable and delegatable flags and finally the initial
-amount taken from the currently executed contract. The contract is
-returned as a first class value (to be dropped, passed as parameter or stored).
-The ``CONTRACT 'p`` instruction will fail until it is actually originated.
-
-- ``CREATE_CONTRACT { storage 'g ; parameter 'p ; code ... }``:
- Forge a new contract from a literal.
-
-::
-
- :: key_hash : option key_hash : bool : bool : mutez : 'g : 'S
- -> operation : address : 'S
-
-Originate a contract based on a literal. This is currently the only way
-to include transfers inside of an originated contract. The first
-parameters are the manager, optional delegate, then spendable and
-delegatable flags and finally the initial amount taken from the
-currently executed contract.
-
-- ``CREATE_ACCOUNT``: Forge an account (a contract without code) creation operation.
-
-::
-
- :: key_hash : option key_hash : bool : mutez : 'S
- -> operation : address : 'S
-
-Take as argument the manager, optional delegate, the delegatable flag
-and finally the initial amount taken from the currently executed
-contract.
-
-- ``TRANSFER_TOKENS``: Forge a transaction.
-
-::
-
- :: 'p : mutez : contract 'p : 'S -> operation : S
-
-The parameter must be consistent with the one expected by the
-contract, unit for an account.
-
-- ``SET_DELEGATE``: Forge a delegation.
-
-::
-
- :: option key_hash : 'S -> operation : S
-
-- ``BALANCE``: Push the current amount of mutez of the current contract.
-
-::
-
- :: 'S -> mutez : 'S
-
-- ``ADDRESS``: Push the address of a contract.
-
-::
-
- :: contract _ : 'S -> address : 'S
-
-- ``CONTRACT 'p``: Push the untyped version of a contract.
-
-::
-
- :: address : 'S -> option (contract 'p) : 'S
-
- > CONTRACT / addr : S => Some addr : S
- iff addr exists and is a contract of parameter type 'p
- > CONTRACT / addr : S => Some addr : S
- iff 'p = unit and addr is an implicit contract
- > CONTRACT / addr : S => None : S
- otherwise
-
-- ``SOURCE``: Push the contract that initiated the current
- transaction, i.e. the contract that paid the fees and
- storage cost, and whose manager signed the operation
- that was sent on the blockchain. Note that since
- ``TRANSFER_TOKENS`` instructions can be chained,
- ``SOURCE`` and ``SENDER`` are not necessarily the same.
-
-::
-
- :: 'S -> address : 'S
-
-- ``SENDER``: Push the contract that initiated the current
- internal transaction. It may be the ``SOURCE``, but may
- also not if the source sent an order to an intermediate
- smart contract, which then called the current contract.
-
-::
-
- :: 'S -> address : 'S
-
-- ``SELF``: Push the current contract.
-
-::
-
- :: 'S -> contract 'p : 'S
- where contract 'p is the type of the current contract
-
-- ``AMOUNT``: Push the amount of the current transaction.
-
-::
-
- :: 'S -> mutez : 'S
-
-- ``IMPLICIT_ACCOUNT``: Return a default contract with the given
- public/private key pair. Any funds deposited in this contract can
- immediately be spent by the holder of the private key. This contract
- cannot execute Michelson code and will always exist on the
- blockchain.
-
-::
-
- :: key_hash : 'S -> contract unit : 'S
-
-Special operations
-~~~~~~~~~~~~~~~~~~
-
-- ``STEPS_TO_QUOTA``: Push the remaining steps before the contract
- execution must terminate.
-
-::
-
- :: 'S -> nat : 'S
-
-- ``NOW``: Push the timestamp of the block whose validation triggered
- this execution (does not change during the execution of the
- contract).
-
-::
-
- :: 'S -> timestamp : 'S
-
-Operations on bytes
-~~~~~~~~~~~~~~~~~~~
-
-Bytes are used for serializing data, in order to check signatures and
-compute hashes on them. They can also be used to incorporate data from
-the wild and untyped outside world.
-
-- ``PACK``: Serializes a piece of data to its optimized
- binary representation.
-
-::
-
- :: 'a : 'S -> bytes : 'S
-
-- ``UNPACK 'a``: Deserializes a piece of data, if valid.
-
-::
-
- :: bytes : 'S -> option 'a : 'S
-
-- ``CONCAT``: Byte sequence concatenation.
-
-::
-
- :: bytes : bytes : 'S -> bytes : 'S
-
- > CONCAT / s : t : S => (s ^ t) : S
-
- :: bytes list : 'S -> bytes : 'S
-
- > CONCAT / {} : S => 0x : S
- > CONCAT / { s ; } : S => (s ^ r) : S
- where CONCAT / { } : S => r : S
-
-- ``SIZE``: size of a sequence of bytes.
-
-::
-
- :: bytes : 'S -> nat : 'S
-
-- ``SLICE``: Bytes access.
-
-::
-
- :: nat : nat : bytes : 'S -> option bytes : 'S
-
- > SLICE / offset : length : s : S => Some ss : S
- where ss is the substring of s at the given offset and of the given length
- iff offset and (offset + length) are in bounds
- > SLICE / offset : length : s : S => None : S
- iff offset or (offset + length) are out of bounds
-
-- ``COMPARE``: Lexicographic comparison.
-
-::
-
- :: bytes : bytes : 'S -> int : 'S
-
- > COMPARE / s : t : S => -1 : S
- iff s < t
- > COMPARE / s : t : S => 0 : S
- iff s = t
- > COMPARE / s : t : S => 1 : S
- iff s > t
-
-
-Cryptographic primitives
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-- ``HASH_KEY``: Compute the b58check of a public key.
-
-::
-
- :: key : 'S -> key_hash : 'S
-
-- ``BLAKE2B``: Compute a cryptographic hash of the value contents using the
- Blake2B cryptographic hash function.
-
-::
-
- :: bytes : 'S -> bytes : 'S
-
-- ``SHA256``: Compute a cryptographic hash of the value contents using the
- Sha256 cryptographic hash function.
-
-::
-
- :: bytes : 'S -> bytes : 'S
-
-- ``SHA512``: Compute a cryptographic hash of the value contents using the
- Sha512 cryptographic hash function.
-
-::
-
- :: bytes : 'S -> bytes : 'S
-
-- ``CHECK_SIGNATURE``: Check that a sequence of bytes has been signed
- with a given key.
-
-::
-
- :: key : signature : bytes : 'S -> bool : 'S
-
-- ``COMPARE``:
-
-::
-
- :: key_hash : key_hash : 'S -> int : 'S
-
- > COMPARE / x : y : S => -1 : S
- iff x < y
- > COMPARE / x : y : S => 0 : S
- iff x = y
- > COMPARE / x : y : S => 1 : S
- iff x > y
-
-VIII - Macros
--------------
-
-In addition to the operations above, several extensions have been added
-to the language's concrete syntax. If you are interacting with the node
-via RPC, bypassing the client, which expands away these macros, you will
-need to desugar them yourself.
-
-These macros are designed to be unambiguous and reversible, meaning that
-errors are reported in terms of desugared syntax. Below you'll see
-these macros defined in terms of other syntactic forms. That is how
-these macros are seen by the node.
-
-Compare
-~~~~~~~
-
-Syntactic sugar exists for merging ``COMPARE`` and comparison
-combinators, and also for branching.
-
-- ``CMP{EQ|NEQ|LT|GT|LE|GE}``
-
-::
-
- > CMP(\op) / S => COMPARE ; (\op) / S
-
-- ``IF{EQ|NEQ|LT|GT|LE|GE} bt bf``
-
-::
-
- > IF(\op) bt bf / S => (\op) ; IF bt bf / S
-
-- ``IFCMP{EQ|NEQ|LT|GT|LE|GE} bt bf``
-
-::
-
- > IFCMP(\op) / S => COMPARE ; (\op) ; IF bt bf / S
-
-Fail
-~~~~
-
-The ``FAIL`` macros is equivalent to ``UNIT; FAILWITH`` and is callable
-in any context since it does not use its input stack.
-
-- ``FAIL``
-
-::
-
- > FAIL / S => UNIT; FAILWITH / S
-
-Assertion Macros
-~~~~~~~~~~~~~~~~
-
-All assertion operations are syntactic sugar for conditionals with a
-``FAIL`` instruction in the appropriate branch. When possible, use them
-to increase clarity about illegal states.
-
-- ``ASSERT``:
-
-::
-
- > ASSERT => IF {} {FAIL}
-
-- ``ASSERT_{EQ|NEQ|LT|LE|GT|GE}``:
-
-::
-
- > ASSERT_(\op) => IF(\op) {} {FAIL}
-
-- ``ASSERT_CMP{EQ|NEQ|LT|LE|GT|GE}``:
-
-::
-
- > ASSERT_CMP(\op) => IFCMP(\op) {} {FAIL}
-
-- ``ASSERT_NONE``
-
-::
-
- > ASSERT_NONE => IF_NONE {} {FAIL}
-
-- ``ASSERT_SOME``
-
-::
-
- > ASSERT_SOME => IF_NONE {FAIL} {}
-
-- ``ASSERT_LEFT``:
-
-::
-
- > ASSERT_LEFT => IF_LEFT {} {FAIL}
-
-- ``ASSERT_RIGHT``:
-
-::
-
- > ASSERT_RIGHT => IF_LEFT {FAIL} {}
-
-Syntactic Conveniences
-~~~~~~~~~~~~~~~~~~~~~~
-
-These are macros are simply more convenient syntax for various common
-operations.
-
-- ``DII+P code``: A syntactic sugar for working deeper in the stack.
-
-::
-
- > DII(\rest=I*)P code / S => DIP (DI(\rest)P code) / S
-
-- ``DUU+P``: A syntactic sugar for duplicating the ``n``\ th element of
- the stack.
-
-::
-
- > DUU(\rest=U*)P / S => DIP (DU(\rest)P) ; SWAP / S
-
-- ``P(\left=A|P(\left)(\right))(\right=I|P(\left)(\right))R``: A syntactic sugar
- for building nested pairs.
-
-::
-
- > PA(\right)R / S => DIP ((\right)R) ; PAIR / S
- > P(\left)IR / S => PAIR ; (\left)R / S
- > P(\left)(\right)R => (\right)R ; (\left)R ; PAIR / S
-
-A good way to quickly figure which macro to use is to mentally parse the
-macro as ``P`` for pair constructor, ``A`` for left leaf and ``I`` for
-right leaf. The macro takes as many elements on the stack as there are
-leaves and constructs a nested pair with the shape given by its name.
-
-Take the macro ``PAPPAIIR`` for instance:
-
-::
-
- P A P P A I I R
- ( l, ( ( l, r ), r ))
-
-A typing rule can be inferred:
-
-::
-
- PAPPAIIR
- :: 'a : 'b : 'c : 'd : 'S -> (pair 'a (pair (pair 'b 'c) 'd))
-
-- ``UNP(\left=A|P(\left)(\right))(\right=I|P(\left)(\right))R``: A syntactic sugar
- for destructing nested pairs. These macros follow the same convention
- as the previous one.
-
-::
-
- > UNPAIR / S => DUP ; CAR ; DIP { CDR } / S
- > UNPA(\right)R / S => UNPAIR ; DIP (UN(\right)R) / S
- > UNP(\left)IR / S => UNPAIR ; UN(\left)R / S
- > UNP(\left)(\right)R => UNPAIR ; UN(\left)R ; UN(\right)R / S
-
-- ``C[AD]+R``: A syntactic sugar for accessing fields in nested pairs.
-
-::
-
- > CA(\rest=[AD]+)R / S => CAR ; C(\rest)R / S
- > CD(\rest=[AD]+)R / S => CDR ; C(\rest)R / S
-
-- ``IF_SOME bt bf``: Inspect an optional value.
-
-::
-
- :: option 'a : 'S -> 'b : 'S
- iff bt :: [ 'a : 'S -> 'b : 'S]
- bf :: [ 'S -> 'b : 'S]
-
- > IF_SOME / (Some a) : S => bt / a : S
- > IF_SOME / (None) : S => bf / S
-
-- ``SET_CAR``: Set the left field of a pair.
-
-::
-
- > SET_CAR => CDR ; SWAP ; PAIR
-
-- ``SET_CDR``: Set the right field of a pair.
-
-::
-
- > SET_CDR => CAR ; PAIR
-
-- ``SET_C[AD]+R``: A syntactic sugar for setting fields in nested
- pairs.
-
-::
-
- > SET_CA(\rest=[AD]+)R / S =>
- { DUP ; DIP { CAR ; SET_C(\rest)R } ; CDR ; SWAP ; PAIR } / S
- > SET_CD(\rest=[AD]+)R / S =>
- { DUP ; DIP { CDR ; SET_C(\rest)R } ; CAR ; PAIR } / S
-
-- ``MAP_CAR`` code: Transform the left field of a pair.
-
-::
-
- > MAP_CAR code => DUP ; CDR ; DIP { CAR ; code } ; SWAP ; PAIR
-
-- ``MAP_CDR`` code: Transform the right field of a pair.
-
-::
-
- > MAP_CDR code => DUP ; CDR ; code ; SWAP ; CAR ; PAIR
-
-- ``MAP_C[AD]+R`` code: A syntactic sugar for transforming fields in
- nested pairs.
-
-::
-
- > MAP_CA(\rest=[AD]+)R code / S =>
- { DUP ; DIP { CAR ; MAP_C(\rest)R code } ; CDR ; SWAP ; PAIR } / S
- > MAP_CD(\rest=[AD]+)R code / S =>
- { DUP ; DIP { CDR ; MAP_C(\rest)R code } ; CAR ; PAIR } / S
-
-IX - Concrete syntax
---------------------
-
-The concrete language is very close to the formal notation of the
-specification. Its structure is extremely simple: an expression in the
-language can only be one of the four following constructs.
-
-1. An integer.
-2. A character string.
-3. The application of a primitive to a sequence of expressions.
-4. A sequence of expressions.
-
-This simple four cases notation is called Micheline.
-
-The encoding of a Micheline source file must be UTF-8, and non-ASCII
-characters can only appear in comments and strings.
-
-Constants
-~~~~~~~~~
-
-There are three kinds of constants:
-
-1. Integers or naturals in decimal notation.
-2. Strings, with usual escape sequences: ``\n``, ``\t``, ``\b``,
- ``\r``, ``\\``, ``\"``. Unescaped line-breaks (both ``\n`` and ``\r``)
- cannot appear in the middle of a string.
-3. Byte sequences in hexadecimal notation, prefixed with ``0x``.
-
-The current version of Michelson restricts strings to be the printable
-subset of 7-bit ASCII, plus the escaped characters mentioned above.
-
-Primitive applications
-~~~~~~~~~~~~~~~~~~~~~~
-
-A primitive application is a name followed by arguments
-
-::
-
- prim arg1 arg2
-
-When a primitive application is the argument to another primitive
-application, it must be wrapped with parentheses.
-
-::
-
- prim (prim1 arg11 arg12) (prim2 arg21 arg22)
-
-Sequences
-~~~~~~~~~
-
-Successive expression can be grouped as a single sequence expression
-using curly braces as delimiters and semicolon as separators.
-
-::
-
- { expr1 ; expr2 ; expr3 ; expr4 }
-
-A sequence can be passed as argument to a primitive.
-
-::
-
- prim arg1 arg2 { arg3_expr1 ; arg3_expr2 }
-
-Primitive applications right inside a sequence cannot be wrapped.
-
-::
-
- { (prim arg1 arg2) } # is not ok
-
-Indentation
-~~~~~~~~~~~
-
-To remove ambiguities for human readers, the parser enforces some
-indentation rules.
-
-- For sequences:
-
- - All expressions in a sequence must be aligned on the same column.
- - An exception is made when consecutive expressions fit on the same
- line, as long as the first of them is correctly aligned.
- - All expressions in a sequence must be indented to the right of the
- opening curly brace by at least one column.
- - The closing curly brace cannot be on the left of the opening one.
-
-- For primitive applications:
-
- - All arguments in an application must be aligned on the same
- column.
- - An exception is made when consecutive arguments fit on the same
- line, as long as the first of them is correctly aligned.
- - All arguments in a sequence must be indented to the right of the
- primitive name by at least one column.
-
-Differences with the formal notation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The concrete syntax follows the same lexical conventions as the
-specification: instructions are represented by uppercase identifiers,
-type constructors by lowercase identifiers, and constant constructors
-are Capitalized.
-
-All domain specific constants are Micheline constants with specific
-formats. Some have two variants accepted by the data type checker: a
-readable one in a string and an optimized.
-
-- ``mutez`` amounts are written as naturals.
-- ``timestamp``\ s are written either using ``RFC3339`` notation
- in a string (readable), or as the number of seconds since Epoch
- in a natural (optimized).
-- ``contract``\ s, ``address``\ es, ``key``\ s and ``signature``\ s
- are written as strings, in their usual Base58 encoded versions
- (readable), or as their raw bytes (optimized).
-
-The optimized versions should not reach the RPCs, the protocol code
-will convert to optimized by itself when forging operations, storing
-to the database, and before hashing to get a canonical representation
-of a datum for a given type.
-
-To prevent errors, control flow primitives that take instructions as
-parameters require sequences in the concrete syntax.
-
-::
-
- IF { instr1_true ; instr2_true ; ... }
- { instr1_false ; instr2_false ; ... }
-
-Main program structure
-~~~~~~~~~~~~~~~~~~~~~~
-
-The toplevel of a smart contract file must be an un-delimited sequence
-of four primitive applications (in no particular order) that provide its
-``code``, ``parameter`` and ``storage`` fields.
-
-See the next section for a concrete example.
-
-Comments
-~~~~~~~~
-
-A hash sign (``#``) anywhere outside of a string literal will make the
-rest of the line (and itself) completely ignored, as in the following
-example.
-
-::
-
- { PUSH nat 1 ; # pushes 1
- PUSH nat 2 ; # pushes 2
- ADD } # computes 2 + 1
-
-Comments that span on multiple lines or that stop before the end of the
-line can also be written, using C-like delimiters (``/* ... */``).
-
-X - Annotations
----------------
-
-The annotation mechanism of Michelson provides ways to better track data
-on the stack and to give additional type constraints. Annotations are
-only here to add constraints, *i.e.* they cannot turn an otherwise
-rejected program into an accepted one.
-
-Stack visualization tools like the Michelson's Emacs mode print
-annotations associated with each type in the program, as propagated by
-the typechecker as well as variable annotations on the types of elements
-in the stack. This is useful as a debugging aid.
-
-We distinguish three kinds of annotations:
-- type annotations, written ``:type_annot``,
-- variable annotations, written ``@var_annot``,
-- and field or constructors annotations, written ``%field_annot``.
-
-Type Annotations
-~~~~~~~~~~~~~~~~
-
-Each type can be annotated with at most one type annotation. They are
-used to give names to types. For types to be equal, their unnamed
-version must be equal and their names must be the same or at least one
-type must be unnamed.
-
-For instance, the following Michelson program which put its integer
-parameter in the storage is not well typed:
-
-::
-
- parameter (int :p) ;
- storage (int :s) ;
- code { UNPAIR ; SWAP ; DROP ; NIL operation ; PAIR }
-
-Whereas this one is:
-
-::
-
- parameter (int :p) ;
- storage int ;
- code { UNPAIR ; SWAP ; DROP ; NIL operation ; PAIR }
-
-Inner components of composed typed can also be named.
-
-::
-
- (pair :point (int :x_pos) (int :y_pos))
-
-Push-like instructions, that act as constructors, can also be given a
-type annotation. The stack type will then have a correspondingly named
-type on top.
-
-::
-
- UNIT :t
- :: 'A -> (unit :t) : 'A
-
- PAIR :t
- :: 'a : 'b : 'S -> (pair :t 'a 'b) : 'S
-
- SOME :t
- :: 'a : 'S -> (option :t 'a) : 'S
-
- NONE :t 'a
- :: 'S -> (option :t 'a) : 'S
-
- LEFT :t 'b
- :: 'a : 'S -> (or :t 'a 'b) : 'S
-
- RIGHT :t 'a
- :: 'b : 'S -> (or :t 'a 'b) : 'S
-
- NIL :t 'a
- :: 'S -> (list :t 'a) : 'S
-
- EMPTY_SET :t 'elt
- :: 'S -> (set :t 'elt) : 'S
-
- EMPTY_MAP :t 'key 'val
- :: 'S -> (map :t 'key 'val) : 'S
-
-
-A no-op instruction ``CAST`` ensures the top of the stack has the
-specified type, and change its type if it is compatible. In particular,
-this allows to change or remove type names explicitly.
-
-::
-
- CAST 'b
- :: 'a : 'S -> 'b : 'S
- iff 'a = 'b
-
- > CAST t / a : S => a : S
-
-
-Variable Annotations
-~~~~~~~~~~~~~~~~~~~~
-
-Variable annotations can only be used on instructions that produce
-elements on the stack. An instruction that produces ``n`` elements on
-the stack can be given at most ``n`` variable annotations.
-
-The stack type contains both the types of each element in the stack, as
-well as an optional variable annotation for each element. In this
-sub-section we note:
-- ``[]`` for the empty stack ;
-- ``@annot (top) : (rest)`` for the stack whose first value has type ``(top)`` and is annotated with variable annotation ``@annot`` and whose queue has stack type ``(rest)``.
-
-The instructions which do not accept any variable annotations are:
-
-::
-
- DROP
- SWAP
- IF_NONE
- IF_LEFT
- IF_CONS
- ITER
- IF
- LOOP
- LOOP_LEFT
- DIP
- FAILWITH
-
-The instructions which accept at most one variable annotation are:
-
-::
-
- DUP
- PUSH
- UNIT
- SOME
- NONE
- PAIR
- CAR
- CDR
- LEFT
- RIGHT
- NIL
- CONS
- SIZE
- MAP
- MEM
- EMPTY_SET
- EMPTY_MAP
- UPDATE
- GET
- LAMBDA
- EXEC
- ADD
- SUB
- CONCAT
- MUL
- OR
- AND
- XOR
- NOT
- ABS
- IS_NAT
- INT
- NEG
- EDIV
- LSL
- LSR
- COMPARE
- EQ
- NEQ
- LT
- GT
- LE
- GE
- ADDRESS
- CONTRACT
- SET_DELEGATE
- IMPLICIT_ACCOUNT
- NOW
- AMOUNT
- BALANCE
- HASH_KEY
- CHECK_SIGNATURE
- BLAKE2B
- STEPS_TO_QUOTA
- SOURCE
- SENDER
- SELF
- CAST
- RENAME
-
-The instructions which accept at most two variable annotations are:
-
-::
-
- CREATE_ACCOUNT
- CREATE_CONTRACT
-
-Annotations on instructions that produce multiple elements on the stack
-will be used in order, where the first variable annotation is given to
-the top-most element on the resulting stack. Instructions that produce
-``n`` elements on the stack but are given less than ``n`` variable
-annotations will see only their top-most stack type elements annotated.
-
-::
-
- CREATE_ACCOUNT @op @addr
- :: key_hash : option key_hash : bool : mutez : 'S
- -> @op operation : @addr address : 'S
-
- CREATE_ACCOUNT @op
- :: key_hash : option key_hash : bool : mutez : 'S
- -> @op operation : address : 'S
-
-A no-op instruction ``RENAME`` allows to rename variables in the stack
-or to erase variable annotations in the stack.
-
-::
-
- RENAME @new
- :: @old 'a ; 'S -> @new 'a : 'S
-
- RENAME
- :: @old 'a ; 'S -> 'a : 'S
-
-
-Field and Constructor Annotations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Components of pair types, option types and or types can be annotated
-with a field or constructor annotation. This feature is useful to encode
-records fields and constructors of sum types.
-
-::
-
- (pair :point
- (int %x)
- (int %y))
-
-The previous Michelson type can be used as visual aid to represent the
-record type (given in OCaml-like syntax):
-
-::
-
- type point = { x : int ; y : int }
-
-Similarly,
-
-::
-
- (or :t
- (int %A)
- (or
- (bool %B)
- (pair %C
- (nat %n1)
- (nat %n2))))
-
-can be used to represent the algebraic data type (in OCaml-like syntax):
-
-::
-
- type t =
- | A of int
- | B of bool
- | C of { n1 : nat ; n2 : nat }
-
-
-Field annotations are part of the type (at the same level as type name
-annotations), and so types with differing field names (if present) are
-not considered equal.
-
-Instructions that construct elements of composed types can also be
-annotated with one or multiple field annotations (in addition to type
-and variable annotations).
-
-::
-
- PAIR %fst %snd
- :: 'a : 'b : 'S -> (pair ('a %fst) ('b %snd)) : 'S
-
- LEFT %left %right 'b
- :: 'a : 'S -> (or ('a %left) ('b %right)) : 'S
-
- RIGHT %left %right 'a
- :: 'b : 'S -> (or ('a %left) ('b %right)) : 'S
-
- NONE %some 'a
- :: 'S -> (option ('a %some))
-
- Some %some
- :: 'a : 'S -> (option ('a %some))
-
-To improve readability and robustness, instructions ``CAR`` and ``CDR``
-accept one field annotation. For the contract to type check, the name of
-the accessed field in the destructed pair must match the one given here.
-
-::
-
- CAR %fst
- :: (pair ('a %fst) 'b) : S -> 'a : 'S
-
- CDR %snd
- :: (pair 'a ('b %snd)) : S -> 'b : 'S
-
-
-Syntax
-~~~~~~
-
-Primitive applications can receive one or many annotations.
-
-An annotation is a sequence of characters that matches the regular
-expression ``[@:%](|@|%|%%|[_a-zA-Z][_0-9a-zA-Z\.]*)``. They come after
-the primitive name and before its potential arguments.
-
-::
-
- (prim @v :t %x arg1 arg2 ...)
-
-
-Ordering between different kinds of annotations is not significant, but
-ordering among annotations of the same kind is. Annotations of a same
-kind must be grouped together.
-
-For instance these two annotated instructions are equivalent:
-
-::
-
- PAIR :t @my_pair %x %y
-
- PAIR %x %y :t @my_pair
-
-An annotation can be empty, in this case is will mean *no annotation*
-and can be used as a wildcard. For instance, it is useful to annotate
-only the right field of a pair instruction ``PAIR % %right`` or to
-ignore field access constraints, *e.g.* in the macro ``UNPPAIPAIR %x1 %
-%x3 %x4``.
-
-Annotations and Macros
-~~~~~~~~~~~~~~~~~~~~~~
-
-Macros also support annotations, which are propagated on their expanded
-forms. As with instructions, macros that produce ``n`` values on the
-stack accept ``n`` variable annotations.
-
-::
-
- DUU+P @annot
- > DUU(\rest=U*)P @annot / S => DIP (DU(\rest)P @annot) ; SWAP / S
-
- C[AD]+R @annot %field_name
- > CA(\rest=[AD]+)R @annot %field_name / S => CAR ; C(\rest)R @annot %field_name / S
- > CD(\rest=[AD]+)R @annot %field_name / S => CDR ; C(\rest)R @annot %field_name / S
-
- ``CMP{EQ|NEQ|LT|GT|LE|GE}`` @annot
- > CMP(\op) @annot / S => COMPARE ; (\op) @annot / S
-
-The variable annotation on ``SET_C[AD]+R`` and ``MAP_C[AD]+R`` annotates
-the resulting toplevel pair while its field annotation is used to check
-that the modified field is the expected one.
-
-::
-
- SET_C[AD]+R @var %field
- > SET_CAR @var %field => CDR %field ; SWAP ; PAIR @var
- > SET_CDR @var %field => CAR %field ; PAIR @var
- > SET_CA(\rest=[AD]+)R @var %field / S =>
- { DUP ; DIP { CAR ; SET_C(\rest)R %field } ; CDR ; SWAP ; PAIR @var } / S
- > SET_CD(\rest=[AD]+)R @var %field/ S =>
- { DUP ; DIP { CDR ; SET_C(\rest)R %field } ; CAR ; PAIR @var } / S
-
- MAP_C[AD]+R @var %field code
- > MAP_CAR code => DUP ; CDR ; DIP { CAR %field ; code } ; SWAP ; PAIR @var
- > MAP_CDR code => DUP ; CDR %field ; code ; SWAP ; CAR ; PAIR @var
- > MAP_CA(\rest=[AD]+)R @var %field code / S =>
- { DUP ; DIP { CAR ; MAP_C(\rest)R %field code } ; CDR ; SWAP ; PAIR @var} / S
- > MAP_CD(\rest=[AD]+)R @var %field code / S =>
- { DUP ; DIP { CDR ; MAP_C(\rest)R %field code } ; CAR ; PAIR @var} / S
-
-Macros for nested ``PAIR`` and ``UNPAIR`` accept multiple
-annotations. Field annotations for ``PAIR`` give names to leaves of the
-constructed nested pair, in order. Variable annotations for ``UNPAIR``
-give names to deconstructed components on the stack. This next snippet
-gives examples instead of generic rewrite rules for readability
-purposes.
-
-::
-
- PAPPAIIR @p %x1 %x2 %x3 %x4
- :: 'a : 'b : 'c : 'd : 'S
- -> @p (pair ('a %x1) (pair (pair ('b %x) ('c %x3)) ('d %x4))) : 'S
-
- PAPAIR @p %x1 %x2 %x3
- :: 'a : 'b : 'c : 'S -> @p (pair ('a %x1) (pair ('b %x) ('c %x3))) : 'S
-
- UNPAIR @x @y
- :: (pair 'a 'b) : 'S -> @x 'a : @y 'b : 'S
-
- UNPAPPAIIR @x1 @x2 @x3 @x4
- :: (pair 'a (pair (pair 'b 'c) 'd )) : 'S
- -> @x1 'a : @x2 'b : @x3 'c : @x4 'd : 'S
-
-Automatic Variable and Field Annotations Inferring
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When no annotation is provided by the Michelson programmer, the
-typechecker infers some annotations in specific cases. This greatly
-helps users track information in the stack for bare contracts.
-
-For unannotated accesses with ``CAR`` and ``CDR`` to fields that are
-named will be appended (with an additional ``.`` character) to the pair
-variable annotation.
-
-::
-
- CDAR
- :: @p (pair ('a %foo) (pair %bar ('b %x) ('c %y))) : 'S -> @p.bar.x 'b : 'S
-
-If fields are not named but the pair is still named in the stack then
-``.car`` or ``.cdr`` will be appended.
-
-::
-
- CDAR
- :: @p (pair 'a (pair 'b 'c)) : 'S -> @p.cdr.car 'b : 'S
-
-If the original pair is not named in the stack, but a field annotation
-is present in the pair type the accessed value will be annotated with a
-variable annotation corresponding to the field annotation alone.
-
-::
-
- CDAR
- :: (pair ('a %foo) (pair %bar ('b %x) ('c %y))) : 'S -> @bar.x 'b : 'S
-
-A similar mechanism is used for context dependent instructions:
-
-::
-
- ADDRESS :: @c contract _ : 'S -> @c.address address : 'S
-
- CONTRACT 'p :: @a address : 'S -> @a.contract contract 'p : 'S
-
- BALANCE :: 'S -> @balance mutez : 'S
-
- SOURCE :: 'S -> @source address : 'S
-
- SENDER :: 'S -> @sender address : 'S
-
- SELF :: 'S -> @self contract 'p : 'S
-
- AMOUNT :: 'S -> @amount mutez : 'S
-
- STEPS_TO_QUOTA :: 'S -> @steps nat : 'S
-
- NOW :: 'S -> @now timestamp : 'S
-
-Inside nested code blocks, bound items on the stack will be given a
-default variable name annotation depending on the instruction and stack
-type (which can be changed). For instance the annotated typing rule for
-``ITER`` on lists is:
-
-::
-
- ITER body
- :: @l (list 'e) : 'A -> 'A
- iff body :: [ @l.elt e' : 'A -> 'A ]
-
-Special Annotations
-~~~~~~~~~~~~~~~~~~~
-
-The special variable annotations ``@%%`` can be used on instructions
-``CAR`` and ``CDR``. It means to use the accessed field name (if any) as
-a name for the value on the stack. The following typing rule
-demonstrates their use for instruction ``CAR``.
-
-::
-
- CAR @%
- :: @p (pair ('a %fst) ('b %snd)) : 'S -> @fst 'a : 'S
-
- CAR @%%
- :: @p (pair ('a %fst) ('b %snd)) : 'S -> @p.fst 'a : 'S
-
-The special variable annotation ``%@`` can be used on instructions
-``PAIR``, ``SOME``, ``LEFT``, ``RIGHT``. It means to use the variable
-name annotation in the stack as a field name for the constructed
-element. Two examples with ``PAIR`` follows, notice the special
-treatment of annotations with `.`.
-
-::
-
- PAIR %@ %@
- :: @x 'a : @y 'b : 'S -> (pair ('a %x) ('b %y)) : 'S
-
- PAIR %@ %@
- :: @p.x 'a : @p.y 'b : 'S -> @p (pair ('a %x) ('b %y)) : 'S
- :: @p.x 'a : @q.y 'b : 'S -> (pair ('a %x) ('b %y)) : 'S
-
-XI - JSON syntax
-----------------
-
-Micheline expressions are encoded in JSON like this:
-
-- An integer ``N`` is an object with a single field ``"int"`` whose
- value is the decimal representation as a string.
-
- ``{ "int": "N" }``
-
-- A string ``"contents"`` is an object with a single field ``"string"``
- whose value is the decimal representation as a string.
-
- ``{ "string": "contents" }``
-
-- A sequence is a JSON array.
-
- ``[ expr, ... ]``
-
-- A primitive application is an object with two fields ``"prim"`` for
- the primitive name and ``"args"`` for the arguments (that must
- contain an array). A third optional field ``"annots"`` contains a
- list of annotations, including their leading ``@``, ``%`` or ``%``
- sign.
-
- ``{ "prim": "pair", "args": [ { "prim": "nat", "args": [] }, { "prim": "nat", "args": [] } ], "annots": [":t"] }``
-
-As in the concrete syntax, all domain specific constants are encoded as
-strings.
-
-XII - Examples
---------------
-
-Contracts in the system are stored as a piece of code and a global data
-storage. The type of the global data of the storage is fixed for each
-contract at origination time. This is ensured statically by checking on
-origination that the code preserves the type of the global data. For
-this, the code of the contract is checked to be of type
-``lambda (pair 'arg 'global) -> (pair (list operation) 'global)`` where
-``'global`` is the type of the original global store given on origination.
-The contract also takes a parameter and returns a list of internal operations,
-hence the complete calling convention above. The internal operations are
-queued for execution when the contract returns.
-
-Empty contract
-~~~~~~~~~~~~~~
-
-The simplest contract is the contract for which the ``parameter`` and
-``storage`` are all of type ``unit``. This contract is as follows:
-
-::
-
- code { CDR ; # keep the storage
- NIL operation ; # return no internal operation
- PAIR }; # respect the calling convention
- storage unit;
- parameter unit;
-
-Reservoir contract
-~~~~~~~~~~~~~~~~~~
-
-We want to create a contract that stores tez until a timestamp ``T`` or
-a maximum amount ``N`` is reached. Whenever ``N`` is reached before
-``T``, all tokens are reversed to an account ``B`` (and the contract is
-automatically deleted). Any call to the contract's code performed after
-``T`` will otherwise transfer the tokens to another account ``A``.
-
-We want to build this contract in a reusable manner, so we do not
-hard-code the parameters. Instead, we assume that the global data of the
-contract are ``(Pair (Pair T N) (Pair A B))``.
-
-Hence, the global data of the contract has the following type
-
-::
-
- 'g =
- pair
- (pair timestamp mutez)
- (pair (contract unit) (contract unit))
-
-Following the contract calling convention, the code is a lambda of type
-
-::
-
- lambda
- (pair unit 'g)
- (pair (list operation) 'g)
-
-written as
-
-::
-
- lambda
- (pair
- unit
- (pair
- (pair timestamp mutez)
- (pair (contract unit) (contract unit))))
- (pair
- (list operation)
- (pair
- (pair timestamp mutez)
- (pair (contract unit) (contract unit))))
-
-The complete source ``reservoir.tz`` is:
-
-::
-
- parameter unit ;
- storage
- (pair
- (pair (timestamp %T) (mutez %N)) # T N
- (pair (contract %A unit) (contract %B unit))) ; # A B
- code
- { CDR ; DUP ; CAAR %T; # T
- NOW ; COMPARE ; LE ;
- IF { DUP ; CADR %N; # N
- BALANCE ;
- COMPARE ; LE ;
- IF { NIL operation ; PAIR }
- { DUP ; CDDR %B; # B
- BALANCE ; UNIT ;
- TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS ;
- PAIR } }
- { DUP ; CDAR %A; # A
- BALANCE ;
- UNIT ;
- TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS ;
- PAIR } }
-
-Reservoir contract (variant with broker and status)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-We basically want the same contract as the previous one, but instead of
-leaving it empty, we want to keep it alive, storing a flag ``S`` so that we
-can tell afterwards if the tokens have been transferred to ``A`` or
-``B``. We also want a broker ``X`` to get some fee ``P`` in any case.
-
-We thus add variables ``P`` and ``S`` and ``X`` to the global data of
-the contract, now
-``(Pair (S, Pair (T, Pair (Pair P N) (Pair X (Pair A B)))))``. ``P`` is
-the fee for broker ``A``, ``S`` is the state, as a string ``"open"``,
-``"timeout"`` or ``"success"``.
-
-At the beginning of the transaction:
-
-::
-
- S is accessible via a CDAR
- T via a CDDAR
- P via a CDDDAAR
- N via a CDDDADR
- X via a CDDDDAR
- A via a CDDDDDAR
- B via a CDDDDDDR
-
-The complete source ``scrutable_reservoir.tz`` is:
-
-::
-
- parameter unit ;
- storage
- (pair
- string # S
- (pair
- timestamp # T
- (pair
- (pair mutez mutez) # P N
- (pair
- (contract unit) # X
- (pair (contract unit) (contract unit)))))) ; # A B
- code
- { DUP ; CDAR ; # S
- PUSH string "open" ;
- COMPARE ; NEQ ;
- IF { FAIL } # on "success", "timeout" or a bad init value
- { DUP ; CDDAR ; # T
- NOW ;
- COMPARE ; LT ;
- IF { # Before timeout
- # We compute (P + N) mutez
- PUSH mutez 0 ;
- DIP { DUP ; CDDDAAR } ; ADD ; # P
- DIP { DUP ; CDDDADR } ; ADD ; # N
- # We compare to the cumulated amount
- BALANCE ;
- COMPARE; LT ;
- IF { # Not enough cash, we just accept the transaction
- # and leave the global untouched
- CDR ; NIL operation ; PAIR }
- { # Enough cash, successful ending
- # We update the global
- CDDR ; PUSH string "success" ; PAIR ;
- # We transfer the fee to the broker
- DUP ; CDDAAR ; # P
- DIP { DUP ; CDDDAR } ; # X
- UNIT ; TRANSFER_TOKENS ;
- # We transfer the rest to A
- DIP { DUP ; CDDADR ; # N
- DIP { DUP ; CDDDDAR } ; # A
- UNIT ; TRANSFER_TOKENS } ;
- NIL operation ; SWAP ; CONS ; SWAP ; CONS ;
- PAIR } }
- { # After timeout, we refund
- # We update the global
- CDDR ; PUSH string "timeout" ; PAIR ;
- # We try to transfer the fee to the broker
- BALANCE ; # available
- DIP { DUP ; CDDAAR } ; # P
- COMPARE ; LT ; # available < P
- IF { BALANCE ; # available
- DIP { DUP ; CDDDAR } ; # X
- UNIT ; TRANSFER_TOKENS }
- { DUP ; CDDAAR ; # P
- DIP { DUP ; CDDDAR } ; # X
- UNIT ; TRANSFER_TOKENS } ;
- # We transfer the rest to B
- DIP { BALANCE ; # available
- DIP { DUP ; CDDDDDR } ; # B
- UNIT ; TRANSFER_TOKENS } ;
- NIL operation ; SWAP ; CONS ; SWAP ; CONS ;
- PAIR } } }
-
-Forward contract
-~~~~~~~~~~~~~~~~
-
-We want to write a forward contract on dried peas. The contract takes as
-global data the tons of peas ``Q``, the expected delivery date ``T``,
-the contract agreement date ``Z``, a strike ``K``, a collateral ``C``
-per ton of dried peas, and the accounts of the buyer ``B``, the seller
-``S`` and the warehouse ``W``.
-
-These parameters as grouped in the global storage as follows:
-
-::
-
- Pair
- (Pair (Pair Q (Pair T Z)))
- (Pair
- (Pair K C)
- (Pair (Pair B S) W))
-
-of type
-
-::
-
- pair
- (pair nat (pair timestamp timestamp))
- (pair
- (pair mutez mutez)
- (pair (pair account account) account))
-
-The 24 hours after timestamp ``Z`` are for the buyer and seller to store
-their collateral ``(Q * C)``. For this, the contract takes a string as
-parameter, matching ``"buyer"`` or ``"seller"`` indicating the party for
-which the tokens are transferred. At the end of this day, each of them
-can send a transaction to send its tokens back. For this, we need to
-store who already paid and how much, as a ``(pair mutez mutez)`` where the
-left component is the buyer and the right one the seller.
-
-After the first day, nothing can happen until ``T``.
-
-During the 24 hours after ``T``, the buyer must pay ``(Q * K)`` to the
-contract, minus the amount already sent.
-
-After this day, if the buyer didn't pay enough then any transaction will
-send all the tokens to the seller.
-
-Otherwise, the seller must deliver at least ``Q`` tons of dried peas to
-the warehouse, in the next 24 hours. When the amount is equal to or
-exceeds ``Q``, all the tokens are transferred to the seller.
-For storing the quantity of peas already
-delivered, we add a counter of type ``nat`` in the global storage. For
-knowing this quantity, we accept messages from W with a partial amount
-of delivered peas as argument.
-
-After this day, any transaction will send all the tokens to the buyer
-(not enough peas have been delivered in time).
-
-Hence, the global storage is a pair, with the counters on the left, and
-the constant parameters on the right, initially as follows.
-
-::
-
- Pair
- (Pair 0 (Pair 0_00 0_00))
- (Pair
- (Pair (Pair Q (Pair T Z)))
- (Pair
- (Pair K C)
- (Pair (Pair B S) W)))
-
-of type
-
-::
-
- pair
- (pair nat (pair mutez mutez))
- (pair
- (pair nat (pair timestamp timestamp))
- (pair
- (pair mutez mutez)
- (pair (pair account account) account)))
-
-The parameter of the transaction will be either a transfer from the
-buyer or the seller or a delivery notification from the warehouse of
-type ``(or string nat)``.
-
-At the beginning of the transaction:
-
-::
-
- Q is accessible via a CDDAAR
- T via a CDDADAR
- Z via a CDDADDR
- K via a CDDDAAR
- C via a CDDDADR
- B via a CDDDDAAR
- S via a CDDDDADR
- W via a CDDDDDR
- the delivery counter via a CDAAR
- the amount versed by the seller via a CDADDR
- the argument via a CAR
-
-The complete source ``forward.tz`` is:
-
-::
-
- parameter
- (or string nat) ;
- storage
- (pair
- (pair nat (pair mutez mutez)) # counter from_buyer from_seller
- (pair
- (pair nat (pair timestamp timestamp)) # Q T Z
- (pair
- (pair mutez mutez) # K C
- (pair
- (pair (contract unit) (contract unit)) # B S
- (contract unit))))) ; # W
- code
- { DUP ; CDDADDR ; # Z
- PUSH int 86400 ; SWAP ; ADD ; # one day in second
- NOW ; COMPARE ; LT ;
- IF { # Before Z + 24
- DUP ; CAR ; # we must receive (Left "buyer") or (Left "seller")
- IF_LEFT
- { DUP ; PUSH string "buyer" ; COMPARE ; EQ ;
- IF { DROP ;
- DUP ; CDADAR ; # amount already versed by the buyer
- DIP { AMOUNT } ; ADD ; # transaction
- # then we rebuild the globals
- DIP { DUP ; CDADDR } ; PAIR ; # seller amount
- PUSH nat 0 ; PAIR ; # delivery counter at 0
- DIP { CDDR } ; PAIR ; # parameters
- # and return Unit
- NIL operation ; PAIR }
- { PUSH string "seller" ; COMPARE ; EQ ;
- IF { DUP ; CDADDR ; # amount already versed by the seller
- DIP { AMOUNT } ; ADD ; # transaction
- # then we rebuild the globals
- DIP { DUP ; CDADAR } ; SWAP ; PAIR ; # buyer amount
- PUSH nat 0 ; PAIR ; # delivery counter at 0
- DIP { CDDR } ; PAIR ; # parameters
- # and return Unit
- NIL operation ; PAIR }
- { FAIL } } } # (Left _)
- { FAIL } } # (Right _)
- { # After Z + 24
- # if balance is emptied, just fail
- BALANCE ; PUSH mutez 0 ; IFCMPEQ { FAIL } {} ;
- # test if the required amount is reached
- DUP ; CDDAAR ; # Q
- DIP { DUP ; CDDDADR } ; MUL ; # C
- PUSH nat 2 ; MUL ;
- BALANCE ; COMPARE ; LT ; # balance < 2 * (Q * C)
- IF { # refund the parties
- CDR ; DUP ; CADAR ; # amount versed by the buyer
- DIP { DUP ; CDDDAAR } ; # B
- UNIT ; TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS ; SWAP ;
- DUP ; CADDR ; # amount versed by the seller
- DIP { DUP ; CDDDADR } ; # S
- UNIT ; TRANSFER_TOKENS ; SWAP ;
- DIP { CONS } ;
- DUP ; CADAR ; DIP { DUP ; CADDR } ; ADD ;
- BALANCE ; SUB ; # bonus to the warehouse
- DIP { DUP ; CDDDDR } ; # W
- UNIT ; TRANSFER_TOKENS ;
- DIP { SWAP } ; CONS ;
- # leave the storage as-is, as the balance is now 0
- PAIR }
- { # otherwise continue
- DUP ; CDDADAR ; # T
- NOW ; COMPARE ; LT ;
- IF { FAIL } # Between Z + 24 and T
- { # after T
- DUP ; CDDADAR ; # T
- PUSH int 86400 ; ADD ; # one day in second
- NOW ; COMPARE ; LT ;
- IF { # Between T and T + 24
- # we only accept transactions from the buyer
- DUP ; CAR ; # we must receive (Left "buyer")
- IF_LEFT
- { PUSH string "buyer" ; COMPARE ; EQ ;
- IF { DUP ; CDADAR ; # amount already versed by the buyer
- DIP { AMOUNT } ; ADD ; # transaction
- # The amount must not exceed Q * K
- DUP ;
- DIIP { DUP ; CDDAAR ; # Q
- DIP { DUP ; CDDDAAR } ; MUL ; } ; # K
- DIP { COMPARE ; GT ; # new amount > Q * K
- IF { FAIL } { } } ; # abort or continue
- # then we rebuild the globals
- DIP { DUP ; CDADDR } ; PAIR ; # seller amount
- PUSH nat 0 ; PAIR ; # delivery counter at 0
- DIP { CDDR } ; PAIR ; # parameters
- # and return Unit
- NIL operation ; PAIR }
- { FAIL } } # (Left _)
- { FAIL } } # (Right _)
- { # After T + 24
- # test if the required payment is reached
- DUP ; CDDAAR ; # Q
- DIP { DUP ; CDDDAAR } ; MUL ; # K
- DIP { DUP ; CDADAR } ; # amount already versed by the buyer
- COMPARE ; NEQ ;
- IF { # not reached, pay the seller
- BALANCE ;
- DIP { DUP ; CDDDDADR } ; # S
- DIIP { CDR } ;
- UNIT ; TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS ; PAIR }
- { # otherwise continue
- DUP ; CDDADAR ; # T
- PUSH int 86400 ; ADD ;
- PUSH int 86400 ; ADD ; # two days in second
- NOW ; COMPARE ; LT ;
- IF { # Between T + 24 and T + 48
- # We accept only delivery notifications, from W
- DUP ; CDDDDDR ; ADDRESS ; # W
- SENDER ;
- COMPARE ; NEQ ;
- IF { FAIL } {} ; # fail if not the warehouse
- DUP ; CAR ; # we must receive (Right amount)
- IF_LEFT
- { FAIL } # (Left _)
- { # We increment the counter
- DIP { DUP ; CDAAR } ; ADD ;
- # And rebuild the globals in advance
- DIP { DUP ; CDADR } ; PAIR ;
- DIP { CDDR } ; PAIR ;
- UNIT ; PAIR ;
- # We test if enough have been delivered
- DUP ; CDAAR ;
- DIP { DUP ; CDDAAR } ;
- COMPARE ; LT ; # counter < Q
- IF { CDR ; NIL operation } # wait for more
- { # Transfer all the money to the seller
- BALANCE ;
- DIP { DUP ; CDDDDADR } ; # S
- DIIP { CDR } ;
- UNIT ; TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS } } ;
- PAIR }
- { # after T + 48, transfer everything to the buyer
- BALANCE ;
- DIP { DUP ; CDDDDAAR } ; # B
- DIIP { CDR } ;
- UNIT ; TRANSFER_TOKENS ;
- NIL operation ; SWAP ; CONS ;
- PAIR} } } } } } }
-
-XII - Full grammar
-------------------
-
-::
-
- ::=
- |
- |
- |
- |
- |
- |
- |
- |
- |
- | Unit
- | True
- | False
- | Pair
- | Left
- | Right
- | Some
- | None
- | { ; ... }
- | { Elt ; ... }
- | instruction
- ::=
- | { ... }
- | DROP
- | DUP
- | SWAP
- | PUSH
- | SOME
- | NONE
- | UNIT
- | IF_NONE { ... } { ... }
- | PAIR
- | CAR
- | CDR
- | LEFT
- | RIGHT
- | IF_LEFT { ... } { ... }
- | IF_RIGHT { ... } { ... }
- | NIL
- | CONS
- | IF_CONS { ... } { ... }
- | SIZE
- | EMPTY_SET
- | EMPTY_MAP
- | MAP { ... }
- | ITER { ... }
- | MEM
- | GET
- | UPDATE
- | IF { ... } { ... }
- | LOOP { ... }
- | LOOP_LEFT { ... }
- | LAMBDA { ... }
- | EXEC
- | DIP { ... }
- | FAILWITH
- | CAST
- | RENAME
- | CONCAT
- | SLICE
- | PACK
- | UNPACK
- | ADD
- | SUB
- | MUL
- | EDIV
- | ABS
- | NEG
- | LSL
- | LSR
- | OR
- | AND
- | XOR
- | NOT
- | COMPARE
- | EQ
- | NEQ
- | LT
- | GT
- | LE
- | GE
- | SELF
- | CONTRACT
- | TRANSFER_TOKENS
- | SET_DELEGATE
- | CREATE_ACCOUNT
- | CREATE_CONTRACT
- | CREATE_CONTRACT { ... }
- | IMPLICIT_ACCOUNT
- | NOW
- | AMOUNT
- | BALANCE
- | CHECK_SIGNATURE
- | BLAKE2B
- | SHA256
- | SHA512
- | HASH_KEY
- | STEPS_TO_QUOTA
- | SOURCE
- | SENDER
- | ADDRESS
- ::=
- |
- | key
- | unit
- | signature
- | option
- | list
- | set
- | operation
- | address
- | contract
- | pair
- | or
- | lambda
- | map
- | big_map
- ::=
- | int
- | nat
- | string
- | bytes
- | mutez
- | bool
- | key_hash
- | timestamp
-
-XIII - Reference implementation
--------------------------------
-
-The language is implemented in OCaml as follows:
-
-- The lower internal representation is written as a GADT whose type
- parameters encode exactly the typing rules given in this
- specification. In other words, if a program written in this
- representation is accepted by OCaml's typechecker, it is guaranteed
- type-safe. This of course also valid for programs not handwritten but
- generated by OCaml code, so we are sure that any manipulated code is
- type-safe.
-
- In the end, what remains to be checked is the encoding of the typing
- rules as OCaml types, which boils down to half a line of code for
- each instruction. Everything else is left to the venerable and well
- trusted OCaml.
-
-- The interpreter is basically the direct transcription of the
- rewriting rules presented above. It takes an instruction, a stack and
- transforms it. OCaml's typechecker ensures that the transformation
- respects the pre and post stack types declared by the GADT case for
- each instruction.
-
- The only things that remain to be reviewed are value dependent
- choices, such as that we did not swap true and false when
- interpreting the If instruction.
-
-- The input, untyped internal representation is an OCaml ADT with the
- only 5 grammar constructions: ``String``, ``Int``, ``Seq`` and
- ``Prim``. It is the target language for the parser, since not all
- parsable programs are well typed, and thus could simply not be
- constructed using the GADT.
-
-- The typechecker is a simple function that recognizes the abstract
- grammar described in section X by pattern matching, producing the
- well-typed, corresponding GADT expressions. It is mostly a checker,
- not a full inferrer, and thus takes some annotations (basically the
- input and output of the program, of lambdas and of uninitialized maps
- and sets). It works by performing a symbolic evaluation of the
- program, transforming a symbolic stack. It only needs one pass over
- the whole program.
-
- Here again, OCaml does most of the checking, the structure of the
- function is very simple, what we have to check is that we transform a
- ``Prim ("If", ...)`` into an ``If``, a ``Prim ("Dup", ...)`` into a
- ``Dup``, etc.
diff --git a/vendors/tezos-modded/docs/whitedoc/octopus.svg b/vendors/tezos-modded/docs/whitedoc/octopus.svg
deleted file mode 100644
index 39085da7e..000000000
--- a/vendors/tezos-modded/docs/whitedoc/octopus.svg
+++ /dev/null
@@ -1,1558 +0,0 @@
-
-
-
-