From d845dc97402d0be7d0fe5300faf6c816223a659a Mon Sep 17 00:00:00 2001 From: Vincent Bernardoff Date: Wed, 8 Mar 2017 18:47:01 +0100 Subject: [PATCH] Alpha: documentation of RPC wrappers. --- src/client/client_commands.mli | 11 ++++++++++ src/client/client_node_rpcs.mli | 10 +++++++++ .../alpha/baker/client_mining_forge.ml | 9 ++++---- .../alpha/baker/client_mining_forge.mli | 14 ++++++++++--- .../alpha/baker/client_mining_main.ml | 5 +++-- .../embedded/alpha/client_proto_rpcs.mli | 21 +++++++++++++++++++ src/node/shell/node.mli | 5 +++++ src/node/shell/node_rpc_services.ml | 12 +++++------ src/proto/alpha/block_repr.mli | 5 ++++- src/proto/alpha/mining.mli | 15 +++++++++++-- src/proto/alpha/services_registration.ml | 2 +- src/proto/alpha/tezos_context.mli | 3 +++ test/test_basic.ml | 2 +- 13 files changed, 94 insertions(+), 20 deletions(-) diff --git a/src/client/client_commands.mli b/src/client/client_commands.mli index 4140e7f5f..7b0d7d845 100644 --- a/src/client/client_commands.mli +++ b/src/client/client_commands.mli @@ -16,10 +16,21 @@ type context = message : 'a. ('a, unit) lwt_format -> 'a ; answer : 'a. ('a, unit) lwt_format -> 'a ; log : 'a. string -> ('a, unit) lwt_format -> 'a } +(** This [context] allows the client {!command} handlers to work in + various modes (command line, batch mode, web client, etc.) by + abstracting some basic operations such as logging and reading + configuration options. It is passed as parameter to the command + handler when running a command, and must be transmitted to all + basic operations, also making client commands reantrant. *) val make_context : (string -> string -> unit Lwt.t) -> context +(** [make_context log_fun] builds a context whose logging callbacks + call [log_fun section msg], and whose [error] function calls + [Lwt.fail_with]. *) val ignore_context : context +(** [ignore_context] is a context whose logging callbacks do nothing, + and whose [error] function calls [Lwt.fail_with]. *) type command = (context, unit) Cli_entries.command diff --git a/src/client/client_node_rpcs.mli b/src/client/client_node_rpcs.mli index bf1055603..e8d955f4e 100644 --- a/src/client/client_node_rpcs.mli +++ b/src/client/client_node_rpcs.mli @@ -20,6 +20,11 @@ val forge_block: Operation_hash.t list -> MBytes.t -> MBytes.t Lwt.t +(** [forge_block cctxt ?net ?predecessor ?timestamp fitness ops + proto_hdr] returns the serialization of a block header with + [proto_hdr] as protocol-specific part. The arguments [?net] and + [?predecessor] are infered from the current head of main network, + and [?timestamp] defaults to [Time.now ()]. *) val validate_block: Client_commands.context -> @@ -31,6 +36,11 @@ val inject_block: ?wait:bool -> ?force:bool -> MBytes.t -> Block_hash.t tzresult Lwt.t +(** [inject_block cctxt ?wait ?force raw_block] tries to inject + [raw_block] inside the node. If [?wait] is [true], [raw_block] + will be validated before the result is returned. If [?force] is + true, the block will be injected even on non strictly increasing + fitness. *) val inject_operation: Client_commands.context -> diff --git a/src/client/embedded/alpha/baker/client_mining_forge.ml b/src/client/embedded/alpha/baker/client_mining_forge.ml index aef5c5f2c..b7145eb32 100644 --- a/src/client/embedded/alpha/baker/client_mining_forge.ml +++ b/src/client/embedded/alpha/baker/client_mining_forge.ml @@ -71,8 +71,9 @@ let inject_block cctxt block let forge_block cctxt block ?force ?operations ?(best_effort = operations = None) ?(sort = best_effort) - ?timestamp ?max_priority ?priority - ~seed_nonce ~src_sk src_pkh = + ?timestamp + ~priority + ~seed_nonce ~src_sk () = let block = match block with | `Prevalidation -> `Head 0 @@ -91,12 +92,12 @@ let forge_block cctxt block end >>= fun operations -> begin match priority with - | Some prio -> begin + | `Set prio -> begin Client_proto_rpcs.Helpers.minimal_time cctxt block ~prio () >>=? fun time -> return (prio, Some time) end - | None -> + | `Auto (src_pkh, max_priority) -> Client_proto_rpcs.Helpers.Rights.mining_rights_for_delegate cctxt ?max_priority ~first_level:level diff --git a/src/client/embedded/alpha/baker/client_mining_forge.mli b/src/client/embedded/alpha/baker/client_mining_forge.mli index f5643b873..e68c45db6 100644 --- a/src/client/embedded/alpha/baker/client_mining_forge.mli +++ b/src/client/embedded/alpha/baker/client_mining_forge.mli @@ -8,6 +8,10 @@ (**************************************************************************) val generate_seed_nonce: unit -> Nonce.t +(** [generate_seed_nonce ()] is a random nonce that is typically used + in block headers. When baking, bakers generate random nonces whose + hash is commited in the block they bake. They will typically + reveal the aforementionned nonce during the next cycle. *) val inject_block: Client_commands.context -> @@ -20,6 +24,11 @@ val inject_block: src_sk:secret_key -> Operation_hash.t list -> Block_hash.t tzresult Lwt.t +(** [inject_block cctxt blk ?force ~priority ~timestamp ~fitness + ~seed_nonce ~src_sk ops] tries to inject a block in the node. If + [?force] is set, the fitness check will be bypassed. [priority] + will be used to compute the mining slot (level is + precomputed). [src_sk] is used to sign the block header. *) val forge_block: Client_commands.context -> @@ -29,11 +38,10 @@ val forge_block: ?best_effort:bool -> ?sort:bool -> ?timestamp:Time.t -> - ?max_priority:int -> - ?priority:int -> + priority:[`Set of int | `Auto of (public_key_hash * int option)] -> seed_nonce:Nonce.t -> src_sk:secret_key -> - public_key_hash -> + unit -> Block_hash.t tzresult Lwt.t module State : sig diff --git a/src/client/embedded/alpha/baker/client_mining_main.ml b/src/client/embedded/alpha/baker/client_mining_main.ml index 39bffb409..2d481765d 100644 --- a/src/client/embedded/alpha/baker/client_mining_main.ml +++ b/src/client/embedded/alpha/baker/client_mining_main.ml @@ -23,8 +23,9 @@ let mine_block cctxt block ?force ?max_priority ?src_sk delegate = let seed_nonce = Client_mining_forge.generate_seed_nonce () in Client_mining_forge.forge_block cctxt ~timestamp:(Time.now ()) - ?force ?max_priority - ~seed_nonce ~src_sk block delegate >>=? fun block_hash -> + ?force + ~seed_nonce ~src_sk block + ~priority:(`Auto (delegate, max_priority)) () >>=? fun block_hash -> Client_mining_forge.State.record_block cctxt level block_hash seed_nonce |> trace_exn (Failure "Error while recording block") >>=? fun () -> cctxt.message "Injected block %a" Block_hash.pp_short block_hash >>= fun () -> diff --git a/src/client/embedded/alpha/client_proto_rpcs.mli b/src/client/embedded/alpha/client_proto_rpcs.mli index da4866c57..d8db09f7b 100644 --- a/src/client/embedded/alpha/client_proto_rpcs.mli +++ b/src/client/embedded/alpha/client_proto_rpcs.mli @@ -51,9 +51,15 @@ module Context : sig val level: Client_commands.context -> block -> Level.t tzresult Lwt.t + (** [level cctxt blk] returns the (protocol view of the) level of + [blk]. *) + val next_level: Client_commands.context -> block -> Level.t tzresult Lwt.t + (** [next_level cctxt blk] returns the (protocol view of the) level + of the successor of [blk]. *) + module Nonce : sig val hash: Client_commands.context -> @@ -130,6 +136,10 @@ module Helpers : sig val minimal_time: Client_commands.context -> block -> ?prio:int -> unit -> Time.t tzresult Lwt.t + (** [minimal_time cctxt blk ?prio ()] is the minimal acceptable + timestamp for the successor of [blk]. [?prio] defaults to + [0]. *) + val apply_operation: Client_commands.context -> block -> Block_hash.t -> Operation_hash.t -> MBytes.t -> MBytes.t option -> @@ -309,6 +319,17 @@ module Helpers : sig seed_nonce_hash:Nonce_hash.t -> proof_of_work_nonce:MBytes.t -> unit -> MBytes.t tzresult Lwt.t + (** [block cctxt root ~net ~predecessor ~timestamp ~fitness + ~operations ~level ~priority ~seed_nonce_hash + ~proof_of_work_nonce ()] returns the binary serialization of + a block header (comprising the shell and protocol-specific + part), rooted at [root], belonging to [net], with + predecessor [predecessor], [timestamp], [fitness], + associated operations [operations], level [level] (the + protocol cannot deduce it from [predecessor] on its own), + priority [priority] (the priority of this miner in the + mining queue associated to [level]), [seed_nonce_hash] (the + chosen seed that we will reveal in the next cycle). *) end module Parse : sig diff --git a/src/node/shell/node.mli b/src/node/shell/node.mli index a43e27f46..fbd9173ca 100644 --- a/src/node/shell/node.mli +++ b/src/node/shell/node.mli @@ -28,6 +28,11 @@ module RPC : sig val inject_block: t -> ?force:bool -> MBytes.t -> (Block_hash.t * unit tzresult Lwt.t) tzresult Lwt.t + (** [inject_block node ?force bytes] tries to insert [bytes] + (supposedly the serialization of a block header) inside + [node]. If [?force] is true, the block will be inserted even on + non strictly increasing fitness. *) + val inject_operation: t -> ?force:bool -> MBytes.t -> (Operation_hash.t * unit tzresult Lwt.t) Lwt.t diff --git a/src/node/shell/node_rpc_services.ml b/src/node/shell/node_rpc_services.ml index 39afb52c0..4e7c94869 100644 --- a/src/node/shell/node_rpc_services.ml +++ b/src/node/shell/node_rpc_services.ml @@ -171,7 +171,7 @@ module Blocks = struct let info = RPC.service - ~description:"All the block informations." + ~description:"All the information about a block." ~input: (conv (fun x -> Some x) @@ -648,7 +648,7 @@ let inject_block = contextual RPCs from the latest block \ (e.g. '/blocks/head/context/preapply'). Returns the ID of the \ block. By default, the RPC will wait for the block to be \ - validated before to answer." + validated before answering." ~input: (conv (fun (block, blocking, force) -> @@ -661,7 +661,7 @@ let inject_block = (describe ~description: "Should the RPC wait for the block to be \ - validated before to answer. (default: true)" + validated before answering. (default: true)" bool)) (opt "force" (describe @@ -681,7 +681,7 @@ let inject_operation = ID of the operation. The `signedOperationContents` should be \ constructed using a contextual RPCs from the latest block \ and signed by the client. By default, the RPC will wait for \ - the operation to be (pre-)validated before to answer. See \ + the operation to be (pre-)validated before answering. See \ RPCs ubder /blocks/prevalidation for more details on the \ prevalidation context." ~input: @@ -693,7 +693,7 @@ let inject_operation = (describe ~description: "Should the RPC wait for the operation to be \ - (pre-)validated before to answer. (default: true)" + (pre-)validated before answering. (default: true)" bool) true) (opt "force" @@ -748,7 +748,7 @@ let inject_protocol = (describe ~description: "Should the RPC wait for the protocol to be \ - validated before to answer. (default: true)" + validated before answering. (default: true)" bool) true) (opt "force" diff --git a/src/proto/alpha/block_repr.mli b/src/proto/alpha/block_repr.mli index d7b70cfae..7c028a660 100644 --- a/src/proto/alpha/block_repr.mli +++ b/src/proto/alpha/block_repr.mli @@ -37,4 +37,7 @@ val unsigned_header_encoding: val forge_header: Updater.shell_block -> proto_header -> MBytes.t - +(** [forge_header shell_hdr proto_hdr] is the binary serialization + (using [unsigned_header_encoding]) of a block header, + comprising both the shell and the protocol part of the header, + without the signature. *) diff --git a/src/proto/alpha/mining.mli b/src/proto/alpha/mining.mli index 7918c1140..843979fe6 100644 --- a/src/proto/alpha/mining.mli +++ b/src/proto/alpha/mining.mli @@ -15,6 +15,11 @@ val paying_priorities: context -> int32 list val minimal_time: context -> int32 -> Time.t -> Time.t tzresult Lwt.t +(** [minimal_time ctxt priority pred_block_time] returns the minimal + time, given the predecessor block timestamp [pred_block_time], + after which a miner with priority [priority] is allowed to + mine. Fail with [Invalid_slot_durations_constant] if the minimal + time cannot be computed. *) val pay_mining_bond: context -> @@ -47,10 +52,11 @@ val base_mining_reward: context -> priority:int32 -> Tez.t val endorsement_reward: block_priority:int32 -> Tez.t tzresult Lwt.t - -(** The contract owning rolls for the first mining priorities of a level. *) val mining_priorities: context -> Level.t -> public_key_hash lazy_list +(** [mining_priorities ctxt level] is the lazy list of contract's + public key hashes that are allowed to mine for [level]. *) + val endorsement_priorities: context -> Level.t -> public_key_hash lazy_list @@ -60,6 +66,11 @@ val first_mining_priorities: public_key_hash -> Level.t -> int32 list tzresult Lwt.t +(** [first_mining_priorities ctxt ?max_priority contract_hash level] + is a list of priorities of max [?max_priority] elements, where the + delegate of [contract_hash] is allowed to mine for [level]. If + [?max_priority] is [None], a sensible number of priorities is + returned. *) val first_endorsement_slots: context -> diff --git a/src/proto/alpha/services_registration.ml b/src/proto/alpha/services_registration.ml index 0072be745..968d8b0d6 100644 --- a/src/proto/alpha/services_registration.ml +++ b/src/proto/alpha/services_registration.ml @@ -344,7 +344,7 @@ let mining_rights_for_delegate Tezos_context.Timestamp.get_current ctxt >>= fun timestamp -> Mining.minimal_time ctxt priority timestamp >>= function | Ok time -> Lwt.return (raw_level, Int32.to_int priority, Some time) - | Error _ -> Lwt.return (raw_level, Int32.to_int priority, None)) + | Error _ -> Lwt.return (raw_level, Int32.to_int priority, None)) priorities >>= fun priorities -> return (priorities @ t) in diff --git a/src/proto/alpha/tezos_context.mli b/src/proto/alpha/tezos_context.mli index 4f1ced13b..2010013b7 100644 --- a/src/proto/alpha/tezos_context.mli +++ b/src/proto/alpha/tezos_context.mli @@ -69,6 +69,9 @@ module Timestamp : sig val to_seconds: time -> string val get_current: context -> Time.t Lwt.t + (** [get_current ctxt] returns the current timestamp of [ctxt]. When + [ctxt] is the context of a block, the block timestamp is used, + otherwise a timestamp is inferred otherwise. *) end diff --git a/test/test_basic.ml b/test/test_basic.ml index d20e29a97..a466566cd 100644 --- a/test/test_basic.ml +++ b/test/test_basic.ml @@ -177,7 +177,7 @@ let mine contract = let seed_nonce = Client_mining_forge.generate_seed_nonce () in Client_mining_forge.forge_block cctxt ~timestamp:(Time.now ()) ~seed_nonce ~src_sk:contract.secret_key - block contract.public_key_hash >>=? fun block_hash -> + block ~priority:(`Auto (contract.public_key_hash, None)) () >>=? fun block_hash -> return () let ecoproto_error f = function