tezt-tezos 20.1 (latest) · OCaml Package

include module type of Operation_core

Overview

This module aims to replace the module Operation_legacy to provide an interface which is more extensible. In other words, supporting a new operation should be easier using this interface.

An unsigned operation is represented by the datatype t. t is a wrapper around a JSON representation of an operation. Some meta information needs to be provided to sign this operation. t is not signed a priori to ease writing tests with bad signatures.

This module also provides two functions to ease the injection of an operation: inject which should be called when the injection is expected to succeed, and inject_with_error when the injection is expected to fail.

Anyone is free to add support for new operations.

Manager operations

Manager operations represent most of the operations used by the tests. Those operations contain several parameters (see Manager.make) and can be batched. Wrapper like Manager.inject and Manager.inject_with_error are provided to ease the writing of tests.

type t

The abstract representation of an unsigned operation.

type operation := t

type consensus_kind =

| Attestation of {
1. with_dal : bool;
}
| Preattestation

type kind =

| Consensus of {
1. kind : consensus_kind;
2. chain_id : string;
}
| Anonymous
| Voting
| Manager

The kind is necessary because it determines the watermark of an operation which is necessary for signing an operation. This type aims to be extended when other kinds of operations are added into this module.

val make : 
  branch:string ->
  ?signer:Account.key ->
  kind:kind ->
  Tezt_wrapper.JSON.u ->
  t

make ~branch ?signer ~kind json client builds the representation of an unsigned operation.

val json : t -> Tezt_wrapper.JSON.u

json t gives the json representation of an unsigned operation.

val hex : 
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  t ->
  Client.t ->
  Hex.t Lwt.t

hex ?(protocol=None) ?(signature=None) t client computes the binary representation of an operation as a hexadecimal string. If protocol is given, the binary representation is computed using the encoding of operation from the protocol. Otherwise, a call to the forge_operations RPC is done to compute the binary representation. If signature is given, the hexadecimal represents the signed version of the operation. client is used to construct the binary representation of t.

parameter protocol
controls whether the encoding of a protocol should be used to compute the binary representation of the operation rather than calling the forge_operations RPC to compute it.

parameter signature
controls whether a signature should be attached to the operation.

val sign : 
  ?protocol:Protocol.t ->
  t ->
  Client.t ->
  Tezos_crypto.Signature.t Lwt.t

sign t client signs the raw representation of operation t by its signer (see make). client is used to construct the binary representation of t. Note that if no signer have been given to t the function returns Tezos_crypto.Signature.zero.

val hash : t -> Client.t -> [ `OpHash of string ] Lwt.t

hash t client returns the hash of the operation

val byte_size : 
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  t ->
  Client.t ->
  int Lwt.t

Returns the size (in bytes) of the operation.

parameter protocol
Allows using the operation encoding rather than using the forge_operations RPC to compute the hexadecimal representation of the operation.

parameter signature
Allows to manually set the signature of the operation. When omitted, the operation is correctly signed using sign.

val inject : 
  ?request:[ `Inject | `Notify ] ->
  ?force:bool ->
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  ?error:Tezt_wrapper.Base.rex ->
  t ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject ?(request=`Inject) ?(force=false) ?(signature=None) ?(error=None) t injects an operation into the node. The node is extracted from the Client. If a node cannot be extracted, the injection fails. If the injection succeeds, the hash of the operation is returned.

parameter dont_wait
If true, the operation is injected without waiting on some node event. Making request ignore. Default is false.

parameter request
If `Inject, we do not wait the prevalidator to classify the operation. This can create some flakyness in the test but is needed to test corner cases. If `Notify, the function waits for the prevalidator to classify the operation. However, the nodes need to activate the debug events for the prevalidator.

parameter force
If true, the function succeeds even though the operation was classified with an error and was not propagated by the prevalidator. If false, the call fails if the prevalidator classified the operation with an error.

parameter protocol
Allow using the operation encoding rather than using the forge_operations RPC to compute the hexadecimal representation of the operations.

parameter signature
Allows to give manually the signature of the operation. The operation is signed when the signature is omitted.

parameter error
If the injection is expecting to fail, allows to specify the expected error.

val spawn_inject : 
  ?force:bool ->
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  t ->
  Client.t ->
  Tezt_wrapper.JSON.t Runnable.process Lwt.t

Same as inject, but do not wait for the process to exit.

val inject_and_capture1_stderr : 
  rex:Tezt_wrapper.Base.rex ->
  ?force:bool ->
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  t ->
  Client.t ->
  string Lwt.t

Run spawn_inject then capture one group on stderr with rex.

val inject_and_capture2_stderr : 
  rex:Tezt_wrapper.Base.rex ->
  ?force:bool ->
  ?protocol:Protocol.t ->
  ?signature:Tezos_crypto.Signature.t ->
  t ->
  Client.t ->
  (string * string) Lwt.t

Run spawn_inject then capture two groups on stderr with rex.

val inject_operations : 
  ?protocol:Protocol.t ->
  ?request:[ `Inject | `Notify ] ->
  ?force:bool ->
  ?error:Tezt_wrapper.Base.rex ->
  ?use_tmp_file:bool ->
  t list ->
  Client.t ->
  [ `OpHash of string ] list Lwt.t

inject_operations ?protocol ?request ?force ?error ?use_tmp_file ops client is similar as inject for a list of operations. This function calls the RPC RPC.post_private_injection_operations which is faster than calling the RPC used by inject several times. Note that this function should be used mainly when the time for injecting operations matters.

parameter use_tmp_file
see RPC.post_private_injection_operations for more information.

val make_run_operation_input : 
  ?chain_id:string ->
  t ->
  Client.t ->
  Tezt_wrapper.JSON.u Lwt.t

Craft a json representing the full operation, in a format that is compatible with the run_operation RPC (RPC.post_chain_block_helpers_scripts_run_operation).

This json contains many more fields than the one produced by the json function above.

The operation is signed with Tezos_crypto.Signature.zero, because the run_operation RPC skips signature checks anyway.

parameter chain_id
Allows to manually provide the chain_id. If omitted, the chain_id is retrieved via RPC using the provided client.

parameter client
The Client.t argument is used to retrieve the chain_id when it is not provided.

val make_preapply_operation_input : 
  protocol:Protocol.t ->
  signature:Tezos_crypto.Signature.t ->
  t ->
  Tezt_wrapper.JSON.u

Craft a json representing the full operation, in a format that is compatible with the preapply/operations RPC (RPC.post_chain_block_helpers_preapply_operations).

This json contains many more fields than the one produced by the json function above.

module Consensus : sig ... end

module Anonymous : sig ... end

module Voting : sig ... end

Voting operations (validation pass 1): proposals and ballot.

module Manager : sig ... end

Regular expressions for specific error messages.

Can be used as e.g.

the error argument of inject
the rex argument of inject_and_capture2_stderr
the msg argument of Process.check_error.

val gas_limit_exceeded : Tezt_wrapper.Base.rex

Matches the client message for the Operation_quota_exceeded protocol error.

val conflict_error_with_needed_fee : Tezt_wrapper.Base.rex

Matches the message produced by Operation_conflict {new_hash; needed_fee_in_mutez = Some fee} from src/lib_shell_services/validation_errors.

Captures new_hash and fee.

val conflict_error_no_possible_fee : Tezt_wrapper.Base.rex

Matches the message produced by Operation_conflict {new_hash; needed_fee_in_mutez = None} from src/lib_shell_services/validation_errors.

Captures new_hash.

val rejected_by_full_mempool_with_needed_fee : Tezt_wrapper.Base.rex

Matches the message produced by Rejected_by_full_mempool {hash; needed_fee_in_mutez = Some fee} from src/lib_shell_services/validation_errors.

Captures hash and fee.

val rejected_by_full_mempool_no_possible_fee : Tezt_wrapper.Base.rex

Matches the message produced by Rejected_by_full_mempool {hash; needed_fee_in_mutez = None} from src/lib_shell_services/validation_errors.

Captures hash.

val dal_data_availibility_attester_not_in_committee : Tezt_wrapper.Base.rex

Matches the message produced by Dal_data_availibility_attester_not_in_committee {attester; level; slot} from src/proto_alpha/lib_protocol/dal_errors_repr.

Captures attester, level, and slot.

val inject_error_check_recommended_fee : 
  loc:string ->
  rex:Tezt_wrapper.Base.rex ->
  expected_fee:int ->
  t ->
  Client.t ->
  unit Lwt.t

Calls inject_and_capture2_stderr and checks that the second captured group is expected_fee.

Intended to be used with conflict_error_with_needed_fee or rejected_by_full_mempool_with_needed_fee as rex.

val already_denounced : Tezt_wrapper.Base.rex

Matches the message produced by Already_denounced {kind; delegate; level} from src/proto_xxx/lib_protocol/validate_errors.

Captures delegate, level, kind.

val outdated_denunciation : Tezt_wrapper.Base.rex

Matches the message produced by Outdated_denunciation {kind; level; last_cycle} from src/proto_xxx/lib_protocol/validate_errors.

Captures kind, last_cycle, level.

val injection_error_unknown_branch : Tezt_wrapper.Base.rex

Matches the message Operation %a is branched on either: from src/lib_shell/prevalidator.ml.

Captures hash.

include module type of Operation_legacy

type manager_operation_content

manager_operation_content is an abstract type for manager operations. Values of this type can be constructed using the smart constructors below.

Unless mentioned otherwise, the default values for generic parameters of a manager operations are the following ones:

Default counter is the successor of the counter of source.

Default amount is 1 tez.

Default fee is 1000 mutez.

Default gas_limit is 1040 gas. Use a greater limit (e.g. ~1500) if the destination is not allocated, and ~1900 if the source will additionnaly be emptied.

Default storage_limit is 257.

type micheline = [

| `Json of Tezt_wrapper.JSON.u
(*
JSON value
*)
| `Michelson of string
(*
Michelson string
*)
| `File of string
(*
file with ext .tz or .json for JSON
*)

]

Michelson scripts and data in different representations.

Used when originating or calling contracts. Depending on the test, the user can provide:

an EzJsonm value directly
a Michelson value in a string
a Michelson value in a file (mainly for Michelson scripts). In this case, files should have extension `.tz`, `.tez` or `.mic`
a file storing directly the JSON representation. This is for instance useful to test contracts that fail at type-checking. Instead of Michelson, the user can generate the JSON and store it a file with a '.json' extension.

Smart constructors

val mk_reveal : 
  source:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  Client.t ->
  manager_operation_content Lwt.t

mk_reveal allows to construct a manager operation representing a public key revelation of an implicit account source.

Default counter is the successor of the counter of source.
Default fee is 1000 mutez.
Default gas_limit is 1040 gas.
Default storage_limit is 0.

val mk_call : 
  source:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  dest:string ->
  ?amount:int ->
  entrypoint:string ->
  arg:micheline ->
  Client.t ->
  manager_operation_content Lwt.t

mk_call allows to construct a manager operation representing a call to a smart contract entrypoint with a given parameter arg from an implicit account source.

Default counter is the successor of the counter of source.
Default amount is 0 tez.
Default fee is 30_000 mutez.
Default gas_limit is 30_000 gas.
Default storage_limit is 1_500.

val mk_origination : 
  source:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  code:micheline ->
  init_storage:micheline ->
  ?init_balance:int ->
  Client.t ->
  manager_operation_content Lwt.t

mk_origination allows to construct a manager operation representing a smart contract origination from an implicit account source.

Default counter is the successor of the counter of source.
Default init_balance is 0 tez.
Default fee is 1_000_000 mutez.
Default gas_limit is 100_000 gas.
Default storage_limit is 10_000.

Helper functions to build manager operations

val get_counter : source:Account.key -> Client.t -> int Lwt.t

Returns the current counter of the given implicit account

val get_next_counter : source:Account.key -> Client.t -> int Lwt.t

Returns the next counter of the given implicit account

val get_injection_branch : ?branch:string -> Client.t -> string Lwt.t

Returns branch if supplied as argument, or fetches and returns the default injection branch, i.e. head - 2.

Forging, signing and injecting operations

val sign_manager_op_bytes : 
  signer:Account.key ->
  bytes ->
  Tezos_crypto.Signature.t

sign_manager_op_bytes ~signer op_bytes signs op_bytes with signer's secret key and the watermark Generic_operation.

val sign_manager_op_hex : signer:Account.key -> Hex.t -> Hex.t

Same as sign_manager_op_bytes, but the input operation is given in hexadecimal representation and returns a signature in hexadecimal representation.

val forge_operation : 
  ?protocol:Protocol.t ->
  branch:string ->
  batch:[ `Manager of manager_operation_content list ] ->
  Client.t ->
  [> `Hex of string ] Lwt.t

Forge an operation and returns the hexadecimal binary representation.

If the protocol argument is supplied, the operation is forged locally (using octez-codec), otherwise we call an RPC (.../helpers/forge/operations).

val inject_operation : 
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  unsigned_op:Hex.t ->
  signature:Hex.t ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

Inject a forged operation with its signature.

If the force argument (by default false) is true, then Tezt uses the RPC /private/injection/operation to allow for the injection of operations (which would be rejected by the default injection RPC).

The async argument, whose default value is false, is passed to the RPC during injection.

On success, the function returns the injected operation's hash.

val forge_and_inject_operation : 
  ?protocol:Protocol.t ->
  ?branch:string ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  batch:[ `Manager of manager_operation_content list ] ->
  signer:Account.key ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

forge_and_inject_operation allows to forge, sign and inject to a node, via the provided client, the list batch of managed operations. The forged operation is signed by the given signer account. Default branch is the one returned by RPC.get_branch client.

If the protocol argument is supplied, the operation is forged locally (using octez-codec), otherwise we call an RPC (.../helpers/forge/operations).

The async argument, whose default value is false, is passed to the RPC during injection.

On success, the function returns the injected operation's hash.

High-level injection functions

val inject_origination : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?branch:string ->
  source:Account.key ->
  ?signer:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  code:micheline ->
  init_storage:micheline ->
  ?init_balance:int ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject_origination is a high-level wrapper that allows to construct an origination operation and inject it using the given client. The signer can be different from the source to be able to inject missigned operations.

See mk_origination and forge_and_inject_operation for the list of parameters and their default values.

val inject_public_key_revelation : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?branch:string ->
  source:Account.key ->
  ?signer:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  ?public_key:string ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject_public_key_revelation is a high-level wrapper that allows to build public key reveal operations and to inject them using the given client. The signer can be different from the source to be able to inject missigned operations. Also, it is possible to provide a public_key that does not match the one of the signer or of the source.

See mk_reveal and forge_and_inject_operation for the list of parameters and their default values.

val inject_transfer : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?branch:string ->
  source:Account.key ->
  ?signer:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  dest:Account.key ->
  ?amount:int ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject_transfer is a high-level wrapper that allows to build XTZ transfer operations and to inject it using the given client. The signer can be different from the source to be able to inject missigned operations.

See manager_operation_content and forge_and_inject_operation for the list of parameters and their default values.

val inject_contract_call : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?branch:string ->
  source:Account.key ->
  ?signer:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  dest:string ->
  ?amount:int ->
  entrypoint:string ->
  arg:micheline ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject_contract_call is a high-level wrapper that allows to build smart contracts calls operations and to inject it using the given client. The signer can be different from the source to be able to inject missigned operations.

See mk_call and forge_and_inject_operation for the list of parameters and their default values.

val inject_transfers : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?amount:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?source:Account.key ->
  ?destination:Account.key ->
  node:Node.t ->
  number_of_operations:int ->
  Client.t ->
  [ `OpHash of string ] list Lwt.t

inject_transfers is a wrapper around inject_transfer to inject number_of_operations transfers with the same parameters. See inject_transfer for optional arguments.

val inject_transfer_ticket : 
  ?protocol:Protocol.t ->
  ?async:bool ->
  ?force:bool ->
  ?wait_for_injection:Node.t ->
  ?branch:string ->
  source:Account.key ->
  ?signer:Account.key ->
  ?counter:int ->
  ?fee:int ->
  ?gas_limit:int ->
  ?storage_limit:int ->
  contents:micheline ->
  ty:micheline ->
  ticketer:string ->
  amount:int ->
  destination:string ->
  entrypoint:string ->
  Client.t ->
  [ `OpHash of string ] Lwt.t

inject_transfer_ticket constructs and injects a mangager operation representing a transfer ticket operation.