Doc: add api/p2p.rst

.dockerignore

@@ -25,6 +25,7 @@ scripts/create_genesis/src
 docs/introduction/readme.rst
 docs/api/errors.rst
 docs/api/rpc.rst
+docs/api/p2p.rst
 
 src/bin_client/test/LOG.*
 

.gitignore

@@ -25,6 +25,7 @@ __pycache__
 /docs/introduction/readme.rst
 /docs/api/errors.rst
 /docs/api/rpc.rst
+/docs/api/p2p.rst
 
 /src/bin_client/test/LOG.*
 

docs/Makefile

@@ -9,6 +9,8 @@ DOCGENDIR     = doc_gen
 DOCERRORDIR   = $(DOCGENDIR)/errors
 DOCRPCDIR     = $(DOCGENDIR)/rpcs
 
+DEV ?= --dev
+
 all: html linkcheck
 
 linkcheck:
@@ -18,18 +20,26 @@ introduction/readme.rst: ../README.rst
 	sed 's/TEZOS/How to build and run/' $< > $@
 
 api/errors.rst: $(DOCERRORDIR)/error_doc.ml
-	@jbuilder build $(DOCERRORDIR)/error_doc.exe
+	@cd .. && jbuilder build ${DEV} docs/$(DOCERRORDIR)/error_doc.exe
 	../_build/default/docs/$(DOCERRORDIR)/error_doc.exe > api/errors.rst
 
-api/rpc.rst: $(DOCRPCDIR)/rpc_doc.ml $(DOCRPCDIR)/usage.rst $(DOCRPCDIR)/run_rpc_doc.sh
+$(DOCGENDIR)/rpc_doc.exe:
-	@jbuilder build $(DOCRPCDIR)/rpc_doc.exe
+	@cd .. && jbuilder build ${DEV} docs/$(DOCGENDIR)/rpc_doc.exe
-	./$(DOCRPCDIR)/run_rpc_doc.sh > api/rpc.rst
+
+api/rpc.rst: $(DOCGENDIR)/rpc_doc.exe api/rpc_usage.rst.inc
+	@jbuilder exec $(DOCGENDIR)/rpc_doc.exe < api/rpc_usage.rst.inc > api/rpc.rst
+
+$(DOCGENDIR)/p2p_doc.exe:
+	@cd .. && jbuilder build ${DEV} docs/$(DOCGENDIR)/p2p_doc.exe
+
+api/p2p.rst: $(DOCGENDIR)/p2p_doc.exe api/p2p_usage.rst.inc
+	@jbuilder exec $(DOCGENDIR)/p2p_doc.exe < api/p2p_usage.rst.inc > api/p2p.rst
 
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-html: Makefile api/errors.rst api/rpc.rst
+html: Makefile api/errors.rst api/rpc.rst api/p2p.rst
 	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
 
 clean:

docs/api/p2p_usage.rst.inc

@@ -0,0 +1 @@
+

docs/doc_gen/errors/error_doc.ml

@@ -38,11 +38,10 @@ let pp_rst_h2 = pp_rst_title ~char:'*'
 (* let pp_rst_h3 = pp_rst_title ~char:'='
  * let pp_rst_h4 = pp_rst_title ~char:'`' *)
 
-let string_of_err_category =
+let string_of_err_category = function
-  let open Error_monad in function
+  | `Branch -> "branch"
-    | `Branch -> "branch"
+  | `Temporary -> "temporary"
-    | `Temporary -> "temporary"
+  | `Permanent -> "permanent"
-    | `Permanent -> "permanent"
 
 let make_counter () =
   let i = ref 1 in

docs/doc_gen/jbuild

@@ -1,7 +1,8 @@
 (jbuild_version 1)
 
-(executable
+(executables
- ((name rpc_doc)
+ ((names (rpc_doc
+          p2p_doc))
   (libraries
    (tezos-base
     tezos-stdlib-unix
@@ -20,7 +21,8 @@
 
 (alias
  ((name buildtest)
-  (deps (rpc_doc.exe))))
+  (deps (rpc_doc.exe
+         p2p_doc.exe))))
 
 (alias
  ((name runtest_indent)

docs/doc_gen/node_helpers.ml

@@ -0,0 +1,45 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright (c) 2014 - 2018.                                          *)
+(*    Dynamic Ledger Solutions, Inc. <contact@tezos.com>                  *)
+(*                                                                        *)
+(*    All rights reserved. No warranty, explicit or implicit, provided.   *)
+(*                                                                        *)
+(**************************************************************************)
+
+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 ;
+    } 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

docs/doc_gen/p2p_doc.ml

@@ -0,0 +1,58 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright (c) 2014 - 2018.                                          *)
+(*    Dynamic Ledger Solutions, Inc. <contact@tezos.com>                  *)
+(*                                                                        *)
+(*    All rights reserved. No warranty, explicit or implicit, provided.   *)
+(*                                                                        *)
+(**************************************************************************)
+
+let protocols = [
+  "Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
+]
+
+let pp_pre f ppf x =
+  Rst.pp_raw_html ppf
+    (Format.asprintf "<pre>@\n%a@\n</pre>" (fun ppf () -> f ppf x) ())
+
+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)"
+    (pp_pre Data_encoding.Binary_schema.pp)
+    (Data_encoding.Binary.describe Block_header.encoding) ;
+  Format.printf "%a@\n@\n%a@\n@."
+    Rst.pp_h2 "Operation (shell)"
+    (pp_pre 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 "Operation (alpha-specific)"
+         (pp_pre 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)"
+         (pp_pre Data_encoding.Binary_schema.pp)
+         (Data_encoding.Binary.describe Proto.operation_data_encoding) ;
+    )
+    protocols ;
+  return ()
+
+let () =
+  Lwt_main.run (Node_helpers.with_node main)

docs/doc_gen/rpc_doc.ml

@@ -11,30 +11,6 @@ let protocols = [
   "Alpha", "ProtoALphaALphaALphaALphaALphaALphaALphaALphaDdp3zK" ;
 ]
 
-module Rst = struct
-
-  let pp_title ~char ppf title =
-    let sub = String.map (fun _ -> char) title in
-    Format.fprintf ppf "@[<v 0>%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 "@[<v>.. raw:: html@   @   %s@ @ @]"
-      (Re.Str.global_replace (Re.Str.regexp "\n") "\n  " str)
-
-  let pp_html ppf f =
-    Format.fprintf ppf
-      "@[<v 2>.. raw:: html@ @ %a@]@\n@\n"
-      (fun ppf () -> f ppf) ()
-
-  let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name
-
-end
-
 let pp_name ppf = function
   | [] | [""] -> Format.pp_print_string ppf "/"
   | prefix -> Format.pp_print_string ppf (String.concat "/" prefix)
@@ -202,24 +178,36 @@ module Description = struct
             target_ref ;
           Option.iter service.input ~f: begin fun _ ->
             pp_button ppf
-              ~default:false ~shortlabel:"input" ~content:"Input format"
+              ~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" ~content:"Output format"
+            ~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, _) ->
+        Option.iter service.input ~f: begin fun (schema, bin_schema) ->
           pp_content ppf
-            ~tag:"pre" ~shortlabel:"input" target_ref
+            ~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" target_ref
+          ~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
@@ -258,83 +246,11 @@ module Description = struct
 
 end
 
-let style = {css|
-<style>
-  .tab {
-    overflow: hidden;
-    border: 1px solid #ccc;
-    background-color: #f1f1f1;
-  }
-  .tab button {
-    background-color: inherit;
-    float: left;
-    border: none;
-    outline: none;
-    cursor: pointer;
-    padding: 5px 10px;
-  }
-  .tab button:hover {
-    background-color: #ddd;
-  }
-  .tab button.active {
-    background-color: #ccc;
-  }
-  .tabcontent {
-    display: none;
-    padding: 6px 12px;
-    border: 1px solid #ccc;
-    border-top: none;
-    max-height: 40ex;
-    margin-bottom: 7ex;
-    overflow: auto;
-  }
-  .tabcontent p {
-    margin-bottom: 12px;
-  }
-  pre {
-    font-size: 12px
-  }
-  .rst-content .section ul p {
-    margin-bottom: 0;
-  }
-  span.query {
-    font-family: monospace;
-    white-space: pre;
-  }
-</style>
-|css}
-
-let script = {script|
-<script>
-  function showTab(elt, tab, ref) {
-    var i, tabcontent, tablinks;
-    tabcontent = document.getElementsByClassName(ref);
-    for (i = 0; i < tabcontent.length; i++) {
-      tabcontent[i].style.display = 'none';
-    }
-
-    tablinks = elt.parentNode.children;
-    for (i = 0; i < tablinks.length; i++) {
-      tablinks[i].className = tablinks[i].className.replace(' active', '');
-    }
-
-    document.getElementById(tab).style.display = 'block';
-    elt.className += ' active';
-  }
-
-  document.addEventListener('DOMContentLoaded', function() {
-    var a = document.getElementsByClassName('defaultOpen');
-    for (i = 0; i < a.length; i++) { a[i].click() }
-  })
-</script>
-|script}
-
-
 let pp_document ppf descriptions =
   (* Style : hack *)
-  Format.fprintf ppf "%a@." Rst.pp_raw_html style ;
+  Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.style ;
   (* Script : hack *)
-  Format.fprintf ppf "%a@." Rst.pp_raw_html script ;
+  Format.fprintf ppf "%a@." Rst.pp_raw_html Rst.script ;
   (* Page title *)
   Format.fprintf ppf "%a" Rst.pp_h1 "RPC API" ;
   (* include/copy usage.rst from input  *)
@@ -363,33 +279,7 @@ let pp_document ppf descriptions =
        Format.fprintf ppf "%a@\n@\n" (Description.pp prefix) rpc_dir)
     descriptions
 
-let genesis : State.Chain.genesis = {
+let main node =
-  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 main 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 ;
-  } 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 ->
   let shell_dir = Node.build_rpc_directory node in
   let protocol_dirs =
     List.map
@@ -412,12 +302,4 @@ let main dir =
   return ()
 
 let () =
-  Lwt_main.run begin
+  Lwt_main.run (Node_helpers.with_node main)
-    Lwt_utils_unix.with_tempdir "tezos_rpcdoc_" main >>= function
-    | Ok _ ->
-        Lwt.return_unit
-    | Error err ->
-        Format.eprintf "%a@." pp_print_error err ;
-        Pervasives.exit 1
-  end
-

docs/doc_gen/rpcs/run_rpc_doc.sh

@@ -1,19 +0,0 @@
-#!/bin/bash
-
-set -e
-set -o pipefail
-
-#**************************************************************************#
-#*                                                                        *#
-#*    Copyright (c) 2014 - 2018.                                          *#
-#*    Dynamic Ledger Solutions, Inc. <contact@tezos.com>                  *#
-#*                                                                        *#
-#*    All rights reserved. No warranty, explicit or implicit, provided.   *#
-#*                                                                        *#
-#**************************************************************************#
-
-docgen_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && echo "$(pwd -P)")"
-rpc_doc="../_build/default/docs/doc_gen/rpcs/rpc_doc.exe"
-usage="$docgen_dir/usage.rst"
-
-$rpc_doc < $usage | sed -e 's|/chains/main/blocks/head/|.../<block_id>/|g'

docs/doc_gen/rst.ml

@@ -0,0 +1,101 @@
+(**************************************************************************)
+(*                                                                        *)
+(*    Copyright (c) 2014 - 2018.                                          *)
+(*    Dynamic Ledger Solutions, Inc. <contact@tezos.com>                  *)
+(*                                                                        *)
+(*    All rights reserved. No warranty, explicit or implicit, provided.   *)
+(*                                                                        *)
+(**************************************************************************)
+
+let pp_title ~char ppf title =
+  let sub = String.map (fun _ -> char) title in
+  Format.fprintf ppf "@[<v 0>%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 "@[<v>.. raw:: html@   @   %s@ @ @]"
+    (Re.Str.global_replace (Re.Str.regexp "\n") "\n  " str)
+
+let pp_html ppf f =
+  Format.fprintf ppf
+    "@[<v 2>.. raw:: html@ @ %a@]@\n@\n"
+    (fun ppf () -> f ppf) ()
+
+let pp_ref ppf name = Format.fprintf ppf ".. _%s :@\n@\n" name
+
+
+
+let style = {css|
+<style>
+  .tab {
+    overflow: hidden;
+    border: 1px solid #ccc;
+    background-color: #f1f1f1;
+  }
+  .tab button {
+    background-color: inherit;
+    float: left;
+    border: none;
+    outline: none;
+    cursor: pointer;
+    padding: 5px 10px;
+  }
+  .tab button:hover {
+    background-color: #ddd;
+  }
+  .tab button.active {
+    background-color: #ccc;
+  }
+  .tabcontent {
+    display: none;
+    padding: 6px 12px;
+    border: 1px solid #ccc;
+    border-top: none;
+    max-height: 40ex;
+    margin-bottom: 7ex;
+    overflow: auto;
+  }
+  .tabcontent p {
+    margin-bottom: 12px;
+  }
+  pre {
+    font-size: 12px
+  }
+  .rst-content .section ul p {
+    margin-bottom: 0;
+  }
+  span.query {
+    font-family: monospace;
+    white-space: pre;
+  }
+</style>
+|css}
+
+let script = {script|
+<script>
+  function showTab(elt, tab, ref) {
+    var i, tabcontent, tablinks;
+    tabcontent = document.getElementsByClassName(ref);
+    for (i = 0; i < tabcontent.length; i++) {
+      tabcontent[i].style.display = 'none';
+    }
+
+    tablinks = elt.parentNode.children;
+    for (i = 0; i < tablinks.length; i++) {
+      tablinks[i].className = tablinks[i].className.replace(' active', '');
+    }
+
+    document.getElementById(tab).style.display = 'block';
+    elt.className += ' active';
+  }
+
+  document.addEventListener('DOMContentLoaded', function() {
+    var a = document.getElementsByClassName('defaultOpen');
+    for (i = 0; i < a.length; i++) { a[i].click() }
+  })
+</script>
+|script}

src/lib_base/fitness.ml

@@ -53,8 +53,9 @@ let rec pp fmt = function
 let encoding =
   let open Data_encoding in
   def "fitness"
-    ~title: "Tezos block fitness"
+    ~title: "Fitness"
-    (list bytes)
+    ~description: "... FIXME ..."
+    (list (def "fitness.elem" bytes))
 
 let to_bytes v = Data_encoding.Binary.to_bytes_exn encoding v
 let of_bytes b = Data_encoding.Binary.of_bytes encoding b

src/lib_crypto/helpers.ml

@@ -103,7 +103,7 @@ module MakeEncoder(H : sig
       ~binary:
         H.raw_encoding
       ~json:
-        (def H.title
+        (def H.name
            ~title: (H.title ^ " (Base58Check-encoded)") @@
          conv
            H.to_b58check

src/proto_alpha/lib_protocol/src/seed_repr.ml

@@ -14,7 +14,7 @@ type t = T of State_hash.t
 type sequence = S of State_hash.t
 type nonce = MBytes.t
 
-let nonce_encoding = Data_encoding.bytes
+let nonce_encoding = Data_encoding.Fixed.bytes Constants_repr.nonce_length
 
 let init = "1234567890123456789012"
 let zero_bytes = MBytes.of_string (String.make Nonce_hash.size '\000')