Coq blog - Guillaume Claret

Beginning of verification for the parsing of smart-contracts

Mon, 22 Feb 2021 00:00:00 +0000

In this blog post, we will show how we formally verify in Coq some properties about the parser of smart-contracts for the crypto-currency Tezos. The proofs of this formal verification are hosted in our project coq-tezos-of-ocaml.

To reason about the implementation of the parser, written in OCaml, we use the tool coq-of-ocaml to convert it automatically to Coq. We will talk about the tricks we used to get this conversion to work, in particular for the GADTs and the mutually recursive functions. We will also present the properties which we verified and how we did it.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

How do we convert the OCaml code to Coq

The code which interests us is in the file script_ir_translator.ml. This is a long file, containing in particular the parser and type-checker of the Michelson language for smart-contracts. We are interested into the functions “parse something” and “unparse something” to show that there are compatible. We use the tool coq-of-ocaml to convert the code of this file. Since it depends on other files of the code of Tezos (for type definitions or primitives), we need to have the Coq definition of all its dependencies too. This is done in the project coq-tezos-of-ocaml. The translation of script_ir_translator.ml is in src/Proto_alpha/Script_ir_translator.v.

Mutually recursive functions

Mutually recursive functions are a challenge in Coq because of the syntactic constraints to make sure that each function terminates. Indeed, termination is important for Coq because a non-terminating functions would make the whole system logically inconsistent. Moreover, OCaml programs may not follow the syntactic constraints for termination of Coq as the OCaml compiler does not check for termination. Thus we use several techniques to translate the OCaml code to Coq without modifying too much the source:

disabling if needed the termination checker of Coq with the Guard Checking flag;
introducing OCaml attributes to guide the translation.

There are two main attributes useful to translate recursive functions:

@coq_struct "ident" to specify the {struct ident} parameter of the Fixpoint command of Coq;
@coq_mutual_as_notation to force some mutual functions to be defined as notations.

For example, let us we take the function parse_ty to parse types, defined in OCaml as:

let rec parse_ty =
 fun ctxt
    ~legacy
    ~allow_lazy_storage
    ~allow_operation
    ~allow_contract
    ~allow_ticket
    node ->
  Gas.consume ctxt Typecheck_costs.parse_type_cycle
  >>? fun ctxt ->
  match node with
  | Prim (_loc, T_unit, [], _annot) ->
      ok (Ex_ty Unit_t, ctxt)
  | Prim (_loc, T_int, [], _annot) ->
      ok (Ex_ty Int_t, ctxt)
  | Prim (_loc, T_nat, [], _annot) ->
      ok (Ex_ty Nat_t, ctxt)
  | Prim (_loc, T_string, [], _annot) ->
      ok (Ex_ty String_t, ctxt)
  | Prim (_loc, T_bytes, [], _annot) ->
      ok (Ex_ty Bytes_t, ctxt)
  | Prim (_loc, T_mutez, [], _annot) ->
      ok (Ex_ty Mutez_t, ctxt)
  | Prim (_loc, T_bool, [], _annot) ->
      ok (Ex_ty Bool_t, ctxt)
  [...]

and parse_parameter_ty =
 fun ctxt ~legacy ->
  parse_ty
    ctxt
    ~legacy
    ~allow_lazy_storage:true
    ~allow_operation:false
    ~allow_contract:true
    ~allow_ticket:true

and parse_any_ty =
  [...]

We have one main function parse_ty iterating over the parameter node and several auxiliary functions such as parse_parameter_ty which are exposed at top-level. We represent these auxiliary functions as notations in Coq, so that they are simpler to reason about compared to mutual fixpoints. We annotate the parse_parameter_ty function by the @coq_mutual_as_notation attribute so that we generate in Coq:

Reserved Notation "'parse_parameter_ty".
Reserved Notation "'parse_any_ty".
[...]

Fixpoint parse_ty
  (ctxt : Alpha_context.context) (legacy : bool) (allow_lazy_storage : bool)
  (allow_operation : bool) (allow_contract : bool) (allow_ticket : bool)
  (node : Alpha_context.Script.node) {struct node}
  : M? (ex_ty * Alpha_context.context) :=
  let parse_parameter_ty := 'parse_parameter_ty in
  let parse_any_ty := 'parse_any_ty in
  [...]
  let? ctxt := Alpha_context.Gas.consume ctxt Typecheck_costs.parse_type_cycle
    in
  match
    (node,
      match node with
      | Micheline.Prim loc Michelson_v1_primitives.T_big_map args _annot =>
        allow_lazy_storage
      | _ => false
      end,
      match node with
      |
        Micheline.Prim _loc Michelson_v1_primitives.T_sapling_state
          (cons memo_size []) _annot => allow_lazy_storage
      | _ => false
      end) with
  | (Micheline.Prim _loc Michelson_v1_primitives.T_unit [] _annot, _, _) =>
    return? ((Ex_ty Script_typed_ir.Unit_t), ctxt)
  | (Micheline.Prim _loc Michelson_v1_primitives.T_int [] _annot, _, _) =>
    return? ((Ex_ty Script_typed_ir.Int_t), ctxt)
  | (Micheline.Prim _loc Michelson_v1_primitives.T_nat [] _annot, _, _) =>
    return? ((Ex_ty Script_typed_ir.Nat_t), ctxt)
  | (Micheline.Prim _loc Michelson_v1_primitives.T_string [] _annot, _, _) =>
    return? ((Ex_ty Script_typed_ir.String_t), ctxt)
  [...]

where "'parse_parameter_ty" :=
  (fun (ctxt : Alpha_context.context) (legacy : bool) =>
    parse_ty ctxt legacy true false true true)

and "'parse_any_ty" :=
  [...]

Definition parse_parameter_ty := 'parse_parameter_ty.
Definition parse_any_ty := 'parse_any_ty.
[...]

We define parse_parameter_ty as a notation 'parse_parameter_ty. We introduce an alias parse_parameter_ty as a standard definition at the end, so that the code depending on parse_parameter_ty does not need to know that this is actually a notation. Using the notation, we consider parse_parameter_ty as a shorthand to call parse_ty rather than a whole new function. This can also simplifies our proofs as parse_ty is now a single recursive function. With the @coq_struct attribute, we specify that the parameter node is the one to recurse on. Even if the function parse_ty is not syntactically terminating for Coq (due to some flattening when parsing pair elements), it is important for the proofs to have a “resonable” struct parameter. This prevents the simpl tactic to diverge when doing proofs by symbolic evaluation. Here we choose the parameter node as it is different on each recursive call.

GADTs

Our current approach to translate GADTs to Coq is to:

erase the type parameters;
use OCaml attributes to force the generation of dynamic casts in Coq when needed (these dynamic casts are axioms).

Fortunately, for our experiment we did not need to use dynamic casts and the code generated without the type parameters for the GADTs was compiling just fine!

The proofs

All the proofs are accessible online on coq-tezos-of-ocaml/src/Proto_alpha/Proofs/Script_ir_translator. We wanted to verify the following property:

 forall term, parse (unparse term) = term

for the terms of type comparable_ty and ty. For the type ty, we express this property as:

Lemma parse_unparse_ty
  ctxt
  legacy
  allow_lazy_storage allow_operation allow_contract allow_ticket
  ty
  (H_ty
    : Script_typed_ir.Ty.is_valid
        legacy
        allow_lazy_storage allow_operation allow_contract allow_ticket
        ty =
      true
  )
  : let unlimited_ctxt := Raw_context.with_unlimited_gas ctxt in
    (let? '(node, ctxt) := Script_ir_translator.unparse_ty unlimited_ctxt ty in
    Script_ir_translator.parse_ty
      ctxt
      legacy
      allow_lazy_storage allow_operation allow_contract allow_ticket
      node) =
    return? (Script_ir_translator.Ex_ty ty, unlimited_ctxt).

The parameters legacy, allow_lazy_storage, allow_operation, allow_contract, allow_ticket are boolean flags of the parsing function. They are mainly there to allow or forbid some elements, such as the contracts or the tickets. The context ctxt represents the current state, and in particular contains a reference to the block-chain state. We replace it by:

let unlimited_ctxt := Raw_context.with_unlimited_gas ctxt in

which is the same context with an unlimited gas value. The gas is there to compute the execution cost for smart-contracts. By setting the gas as unlimited, we avoid having to reason about failures due to gas exhaustion, without too much loss of generality. The unparse_ty and parse_ty functions are in the error monad, whose basic operators are return? to return a success value and let? to bind two operations.

We recursively express the pre-condition Script_typed_ir.Ty.is_valid on the type ty. This pre-condition depends on the same flags as the parsing function. It checks that the forbidden operations are not present, and that all the integers are in the expected intervals.

We do the proof by induction on the value ty. The most complex case is the case of pairs because we flatten the pairs to lists of elements, so the induction is not direct. Apart from that case, most of the proof is dedicated to handling the error monad and unfolding the definitions. To get an idea, here is an extract of the Coq proof to handle the general case:

destruct ty; unfold simple_unparse_ty; simpl; try reflexivity;
  repeat (rewrite simple_unparse_ty_eq; simpl);
  repeat (rewrite Comparable_ty.parse_unparse_comparable_ty; simpl);
  repeat (rewrite (parse_simple_unparse_ty ctxt); simpl);
  trivial;
  simpl in H_ty; try (rewrite Bool.andb_true_iff in H_ty; destruct H_ty);
  trivial.

For each case, we try to do some symbolic evaluation with simpl, and apply the inductive hypothesis parse_simple_unparse_ty or lemma such as parse_unparse_comparable_ty. We also do some basic boolean manipulations with andb_true_iff for the pre-condition.

Finally, we check that the pre-condition Script_typed_ir.Ty.is_valid is true for all the terms parsed by the function parse_ty. We express this property as follows:

Lemma parse_is_valid
  ctxt
  legacy
  allow_lazy_storage allow_operation allow_contract allow_ticket
  node
  : let result :=
      Script_ir_translator.parse_ty
        ctxt
        legacy
        allow_lazy_storage allow_operation allow_contract allow_ticket
        node in
    match result with
    | Pervasives.Ok (Script_ir_translator.Ex_ty ty, _) =>
      Script_typed_ir.Ty.is_valid
        legacy
        allow_lazy_storage allow_operation allow_contract allow_ticket
        ty =
      true
    | _ => True
    end.

The proof proceeds by induction on the parameter node.

Conclusion

We have seen that we can write basic formal proofs about the parser of smart-contracts of Tezos. We do that first by automatically translating the OCaml code to Coq, and then by doing the proofs in Coq.

We will next focus on writing proofs on the parsing functions for the data of smart-contracts. These functions are slightly more involved than the parsing functions on the types, but follow the same structure.

Removing existential types from modules in coq-of-ocaml

Mon, 08 Feb 2021 00:00:00 +0000

The tool coq-of-ocaml translates OCaml programs to Coq programs using a shallow embedding. To translate the modules and functors of OCaml we use polymorphic records in Coq. With this representation, we are also able to translate first-class modules.

We originally used existential types to represent abstract module types. This could be a source of complexity for the reasoning on the generated code. Indeed, existential types require to do frequent projections and wrapping in Coq. In this blog post, we show how we removed the need of existential types in most non-first-class modules.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Example

We take the following OCaml code:

module F (X : Source) : Target with type t2 = X.t = struct
  type t1 = string
  type t2 = X.t
  let y = X.x
end

module FM = F (M)

We assume that:

the signature Source has one abstract type t;
the signature Target has two abstract types t1 and t2, the type t2 being explicitly specified as X.t in this example.

Now

We show how we now translate this OCaml example with the latest changes in coq-of-ocaml. In particular, we show how we avoid using existential types for the abstract module types. We start by using a Coq type class to represent the functor parameters as explained in a previous article:

Module F.
  Class FArgs {X_t : Set} := {
    X : Source (t := X_t);
  }.
  Arguments Build_FArgs {_}.

We represent the abstract type t of X with a parameter X_t of the class FArgs. This type is implicit (notation {}) since we can infer it from the module X. We then define the various fields of the functor, including a special field functor which is the record representing the result of the functor:

  Definition t1 `{FArgs} : Set := string.

  Definition t2 `{FArgs} : Set := X.(Source.t).

  Definition y `{FArgs} : X.(Source.t) := X.(Source.x).

  Definition functor `{FArgs} :=
    {|
      Target.y := y
    |}.
End F.

Finally, we wrap the functor F.functor into a function F without type classes:

Definition F {X_t : Set} (X : Source (t := X_t))
  : Target (t1 := _) (t2 := X.(Source.t)) :=
  let '_ := F.Build_FArgs X in
  F.functor.

We keep X_t as an implicit parameter. The type X_t is a parameter rather than an existential type. For the abstract type t1, we let Coq infer its value with:

Target (t1 := _) (t2 := X.(Source.t))

Since Coq has access to the definition of F, it is able to guess the value of t1, and we do not need an existential type there. For the type t2, we directly give its value X.(Source.t) like in the OCaml source. We think it is better to always give an explicit type value when possible. Indeed, the expression inferred by Coq may be too large and have caused performance issues in some of our examples.

To apply the functor F on M we simply do a function application:

Definition FM := F M.

Coq infers all the missing abstract type values for us.

Before

Before these recent changes, we were wrapping all the modules into one existential type for each abstract type. On this example, we would have generated the following Coq code:

Module F.
  Class FArgs := {
    X : {t : Set & Source.signature (t := t)};
  }.

  Definition t1 `{FArgs} : Set := string.

  Definition t2 `{FArgs} : Set := (|X|).(Source.t).

  Definition y `{FArgs} : (|X|).(Source.t) := (|X|).(Source.x).

  Definition functor `(FArgs)
    : {t1 : Set & Target.signature (t1 := t1) (t2 := (|X|).(Source.t))} :=
    existT (A := Set) _ t1
      {|
        Target.y := y
      |}.
End F.
Definition F X := F.functor {| F.X := X |}.

Definition FM := F (existT (A := Set) _ _ (|M|)).

We wrap the abstract type t of X in the existential:

{t : Set & Source.signature (t := t)}

We wrap the abstract type t1 in the existential:

existT (A := Set) _ t1 {| ... |}

To access the fields of each module we first project the existential types with the notation:

Notation "(| M |)" := (projT2 M).

To apply the functor F to M we also wrap M into an existential in order to be sure to have the correct number of existential types. We believe that the use of existential types associated with frequent projections or wrapping was a source of complexity for proofs made on the generated Coq code.

Strategy

We now describe the general strategy we use to remove the need of existential types in common use cases.

Definitions

When we define a module M with some abstract types in the signature, we let Coq infer their values. When we define a functor F parametrized by some modules:

M_1, ..., M_n

with the abstract types:

M_1 : t_1_1, t_1_2, ...
...
M_n : t_n_1, t_n_2, ...

and returning a module of signature S with the abstract types:

S : t_1, t_2, ...

we push all the abstract types in front, so that the type of the function representing the functor F in Coq is:

F :
  (* The abstract types could also have a higher arity such as Set -> Set *)
  forall {t_1_1 t_1_2 ... t_n_1 t_n_2 ... : Set},
  forall (M1 : M_1_signature (t_1_1 := t_1_1) (t_1_2 := t_1_2) ...),
  ...
  forall (M_n : M_n_signature (t_n_1 := t_n_1) (t_n_2 := t_n_2) ...),
  S
    (t_1 := either _ if abstract or some type expression if specified)
    ...
    (t_n := ...)

We only support functors whose parameters are all modules. Since we support modules containing functors, it is possible to wrap a functor into a module to pass it to another functor. However the functors in modules cannot return some abstract types (we had universe level issues with that). We also expect the functors to be applied on all their parameters at once (no currying). Indeed, we need to infer all the abstract types of the parameters at once.

An example of a functor type from the Coq code generated from Tezos is the following:

Definition Make_single_data_storage {C_t V_t : Set}
  (R : Storage_sigs.REGISTER) (C : Raw_context.T (t := C_t))
  (N : Storage_sigs.NAME) (V : Storage_sigs.VALUE (t := V_t))
  : Storage_sigs.Single_data_storage (t := C.(Raw_context.T.t))
    (value := V.(Storage_sigs.VALUE.t)) :=
  (* ... the definition *)

Axioms

We convert .mli files to lists of axioms. This raises an issue as we cannot infer the abstract types in a module or in the output module of a functor anymore. This inference is not possible because we do not have access to the definition of axioms. We solve this issue by adding one more axiom for each type to infer.

For example, in OCaml the module Map is declared as follows:

module type S = sig
  (** The type of the map keys. *)
  type key

  (** The type of maps from type [key] to type ['a]. *)
  type +'a t

  (* ... *)
end

module Make: functor (Ord : OrderedType) -> S with type key = Ord.t

The signature S has two abstract types key and t. The signature OrderedType has one abstract type t. We transform the declaration of the functor Make to the axioms:

Parameter Make_t :
  forall {Ord_t : Set} (Ord : OrderedType (t := Ord_t)), Set -> Set.

Parameter Make :
  forall {Ord_t : Set},
  forall (Ord : OrderedType (t := Ord_t)),
  S (key := Ord.(OrderedType.t)) (t := Make_t Ord).

Since the abstract type t of the signature S is unspecified, we introduce an additional axiom Make_t to describe its value. This axiom takes the same arguments as the functor Make.

First-class modules

We keep using existential types for the first-class modules. This is because first-class module values can appear at any position in a program (in a function, in a data structure, …). Thus the methods above would not be enough to eliminate the need of existential types in all cases.

We use the following strategy:

we add the existential types when we go from a module to a value;
we remove the existential types (by projection) when we go from a value to a module;
when we access to the field of a first-class module, we consider that the existential types have already been removed, since it has already been converted to a module.

Here is an example of OCaml code with first-class modules, from the code of Tezos:

type ('key, 'value) map =
  (module Boxed_map with type key = 'key and type value = 'value)

let map_set : type a b. a -> b -> (a, b) map -> (a, b) map =
fun k v (module Box) ->
  ( module struct
    type key = a

    type value = b

    let key_ty = Box.key_ty

    module OPS = Box.OPS

    let boxed =
      let (map, size) = Box.boxed in
      (Box.OPS.add k v map, if Box.OPS.mem k map then size else size + 1)
  end )

This implements a map type which is polymorphic in the type of the keys. One needs to give the comparison function for the keys when initializing an empty map. We translate this code to:

Definition map (key value : Set) : Set :=
  {OPS_t : Set -> Set @
    Boxed_map (key := key) (value := value) (OPS_t := OPS_t)}.

Definition map_set {a b : Set} (k : a) (v : b) (Box : map a b)
  : map a b :=
  let 'existS _ _ Box := Box in
  existS (A := Set -> Set) _ _
    (let key : Set := a in
    let value : Set := b in
    let key_ty := Box.(Boxed_map.key_ty) in
    let OPS := Box.(Boxed_map.OPS) in
    let boxed :=
      let '(map, size) := Box.(Boxed_map.boxed) in
      ((Box.(Boxed_map.OPS).(S.MAP.add) k v map),
        (if Box.(Boxed_map.OPS).(S.MAP.mem) k map then
          size
        else
          size +i 1)) in
    {|
      Boxed_map.key_ty := key_ty;
      Boxed_map.OPS := OPS;
      Boxed_map.boxed := boxed
    |}).

We use an existential type to define the type map. Note that we use an existential type in the sort Set with the imprediative Set option of Coq enabled. This allows us to avoid any universe level issue by always staying in the sort Set. We define the existential in Set like the ones in Prop or Type:

Inductive sigS (A : Type) (P : A -> Set) : Set :=
| existS : forall (x : A), P x -> sigS P.

Notation "{ x : A @ P }" := (sigS (A := A) (fun x => P)) : type_scope.

To open the first-class module value Box as a module we use the pattern:

fun k v (module Box) ->

in OCaml. We convert this pattern to an existential projection:

let 'existS _ _ Box := Box in

in Coq. Then to close the module and convert it back to a value, we wrap it into an existential with:

existS (A := Set -> Set) _ _ (...)

Conclusion

We hope that the effort we made into removing existential types from the generated Coq code will help to do simpler proofs on OCaml programs using a lot of modules.

Improvements of coq-of-ocaml for functors and signatures

Tue, 20 Oct 2020 00:00:00 +0000

With coq-of-ocaml we can translate many OCaml constructs to an equivalent in the Coq language. Based on the code which we encounter, we continue to update coq-of-ocaml to handle more OCaml programming patterns. In this post, we will show:

how we changed the representation of functors to have a clearer generated code;
how we handled the anonymous sub-signatures.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Functors like plain modules

Th module system of OCaml allows to represent modules parametrized by others. Such parametrized modules are called functors. We represent modules with a named signature by records in Coq. Then we encode functors by functions over dependent records. We like this representation because:

we can also encode first-class modules (modules used in the context of values in OCaml);
it does not depend on the functor system of Coq, but only on dependent types. The less Coq features from the kernel we use, the safer we feel.

An issue we had was expressing lemmas about items of a functor. For example, with the following OCaml code:

module type Source = sig
  type t
  val x : t
  val id : 'a -> 'a
end

module type Target = sig
  type t
  val y : t
end

module F (X : Source) : Target with type t = X.t = struct
  type t = X.t
  let y = X.x
end

we would generate the following Coq code:

Module Source.
  Record signature {t : Set} : Set := {
    t := t;
    x : t;
  }.
End Source.

Module Target.
  Record signature {t : Set} : Set := {
    t := t;
    y : t;
  }.
End Target.

Definition F :=
  fun (X : {t : Set & Source.signature (t := t)}) =>
    ((let t : Set := (|X|).(Source.t) in
    let y := (|X|).(Source.x) in
    existT (A := unit) (fun _ => _) tt
      {|
        Target.y := y
      |}) : {_ : unit & Target.signature (t := (|X|).(Source.t))}).

There are two module types Source and Target which we represent by record definitions. We parametrize these records by their abstract types. We represent the functor F by a function from the type of record Source to the type of record Target. Here the whole definition of F is packed into a single function. We define the resulting record using local let declarations. We changed that to have top-level definitions for each item of the functor (t and y). By representing the functor parameters as a type-class, we now generate:

Module F.
  Class FArgs := {
    X : {t : Set & Source.signature (t := t)};
  }.

  Definition t `{FArgs} : Set := (|X|).(Source.t).

  Definition y `{FArgs} : (|X|).(Source.t) := (|X|).(Source.x).

  Definition functor `(FArgs)
    : {_ : unit & Target.signature (t := (|X|).(Source.t))} :=
    existT (A := unit) (fun _ => _) tt
      {|
        Target.y := y
      |}.
End F.
Definition F X := F.functor {| F.X := X |}.

The class FArgs contains the functor arguments. This class has one field per functor parameter (in this case only X). We give to each declaration an implicit parameter `{FArgs} so that the parameter X is always accessible. At the end of the module, we materialize the functor as a function functor from an instance of the class of parameters, to the record of the resulting module. Eventually, we define the functor F as a function taking parameters in order and convert them to an instance of the class FArgs.

Remark: we do not use the section mechanism, because this would not compose. Indeed, we cannot create modules inside sections in the current version of Coq. Thus we can only represent flat functors with sections, and cannot represent functors with sub-modules.

For modules represented by records we do the same, without the FArgs parameter. For example, we translate:

module M : Source = struct
  type t = int
  let x = 12
  let id x = x
end

to:

Module M.
  Definition t : Set := int.

  Definition x : int := 12.

  Definition id {A : Set} (x : A) : A := x.

  Definition module :=
    existT (A := Set) _ t
      {|
        Source.x := x;
        Source.id _ := id
      |}.
End M.
Definition M := M.module.

We hope that this presentation is cleaner on the Coq side. For example:

we can directly talk about individual items without referencing the whole resulting record;
we can talk about intermediate items which may not be exported at the end;
we can have plain sub-modules for large functors (which cannot be represented as records with the current system when there are no named signatures);
we can define new types as we would at top-level.

Anonymous sub-signatures

For large signatures, we tend to use sub-signatures in order to group items going together. For example, we can define in OCaml:

module type T_encoding = sig
  type t

  val encoding : t list
end

module type Validator = sig
  module Ciphertext : sig
    include T_encoding

    val get_memo_size : t -> int
  end

  module CV : T_encoding

  type t = Ciphertext.t
end

Since we represent signatures by records, we cannot directly represent the sub-signature for Ciphertext in the signature Validator. Indeed, there are no notions of sub-records in Coq. Thus, we were generating the following error message:

--- foo.ml:8:23 ------------------------------------------------------------ not_supported (1/1) ---

   6 | 
   7 | module type Validator = sig
>  8 |   module Ciphertext : sig
>  9 |     include T_encoding
> 10 | 
> 11 |     val get_memo_size : t -> int
> 12 |   end
  13 | 
  14 |   module CV : T_encoding
  15 | 


Anonymous definition of signatures is not handled

Now we inline the sub-modules by prefixing the name of their fields, so that we generate a single flat record in Coq. For the OCaml code above, we generate:

Module T_encoding.
  Record signature {t : Set} : Set := {
    t := t;
    encoding : list t;
  }.
End T_encoding.

Module Validator.
  Record signature {Ciphertext_t CV_t : Set} : Set := {
    Ciphertext_t := Ciphertext_t;
    Ciphertext_encoding : list Ciphertext_t;
    Ciphertext_get_memo_size : Ciphertext_t -> int;
    CV : T_encoding.signature (t := CV_t);
    t := Ciphertext_t;
  }.
End Validator.

We prefix all the fields of the sub-module Ciphertext by Ciphertext_. We propagate the naming of the types. For example the type t from Ciphertext is renamed as Ciphertext_t in all the subsequent expressions. For all other fields which involve this type t, we mark it as Ciphertext_t. We keep using nested records for sub-signatures with a name. For example, the sub-module CV is a field of type T_encoding.signature, which is itself a record. The two variables Ciphertext_t and CV_t are the two abstract types of the signature. As with flat signatures, we represent them using existential types when unknown.

We also changed the way we translate the identifiers to reference items in signatures. For example, if we have a functor using the field Ciphertext.get_memo_size:

module F (V : Validator) = struct
  let get = V.Ciphertext.get_memo_size
end

we now generate:

Module F.
  Class FArgs := {
    V :
      {'[Ciphertext_t, CV_t] : [Set ** Set] &
        Validator.signature (Ciphertext_t := Ciphertext_t) (CV_t := CV_t)};
  }.

  Definition get `{FArgs} : (|V|).(Validator.Ciphertext_t) -> int :=
    (|V|).(Validator.Ciphertext_get_memo_size).
End F.

Here we represent V.Ciphertext.get_memo_size by (|V|).(Validator.Ciphertext_get_memo_size). We use the notation to access record fields with record.(field). We project the potential existential variables with the notation (|...|). Here are the steps we followed to translate this identifier:

check if V has a known named signature (in this case we find the signature Validator);
check if Ciphertext has a known signature (we do not find one);
conclude that the get_memo_size field has probably been inlined in the signature definition;
generate a record access on V on the field Ciphertext_get_memo_size, which is the concatenation of Ciphertext and get_memo_size according to the way we prefix field names in inlining.

The handling of anonymous sub-signatures is not completely mandatory. Indeed, we could also give a name to the sub-signatures in the OCaml code. However we encountered some cases were this was convenient, in order not to modify the OCaml code too much.

Conclusion

We have shown two new translation strategies which, we hope, will polish the experience of using coq-of-ocaml. This work was mainly directed by an experiment at handling some code from the Tezos codebase. The aim was to verify some parts of the sapling project. This code is outside of the protocol, which is the part we are the most used to work with. Then, we met some new OCaml constructs and patterns. In particular, we encountered large functors with anonymous sub-signatures, plain sub-modules, and new type definitions.

GADTs with type erasure in coq-of-ocaml

Fri, 19 Jun 2020 00:00:00 +0000

coq-of-ocaml is a compiler from the OCaml language to Coq. It now supports the conversion of the full Tezos protocol, composed of around 35.000 lines of code. The OCaml’s GADTs are a challenge to compile, as they have no direct equivalent in Coq. We present how we currently convert the GADTs, and especially the new mechanism of type erasure propagation.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Introduction

Let us look at a short example of GADT which we cannot directly compile to Coq. If we define the annotated trees of integers with a sum function for trees of two elements:

type _ t =
  | Leaf : int -> int t
  | Node : 'a t * 'b t -> ('a * 'b) t

let sum (tree : (int * int) t) : int =
  match tree with
  | Node (Leaf x, Leaf y) -> x + y

a direct translation to Coq could be:

Inductive t : Set -> Set :=
| Leaf : Z -> t Z
| Node : forall {A B : Set}, t A -> t B -> t (A * B).

Definition sum (tree : t (Z * Z)) : Z :=
  match tree with
  | Node (Leaf x) (Leaf y) => x + y
  end.

but this causes the following error:

Error: Non exhaustive pattern-matching: no clause found for pattern Leaf _

Coq cannot decide that this pattern-matching is exhaustive because types are not comparable in Coq. One could even add an axiom stating that:

Z = Z * Z

and we could not derive a contradiction as these two types have the same cardinality. See this discussion on type equality for more information. A solution with dependent types could be to use tags (which are values) to annotate the type t. We can say that with dependent types we “match values” while with GADTs we “unify types”.

Another issue is the fact that OCaml unifies polymorphic type variables of other values in the match. In Coq we can use the convoy pattern to achieve similar results. Finally, having a type appearing as a type parameter for itself in a GADT definition may break the strict positivity constraint and make Coq to refuse the type definition.

The main idea of our solution is to erase the type parameters of the GADTs. When there is a match with a GADT value, we need a way to get back the information we lost erasing the types. Using OCaml attributes to guide coq-of-ocaml, the user can add in the generated code:

a match branch for the impossible cases;
some casts on the variables introduced by the match patterns;
a cast on the results of the match branches.

We define the impossible match branch result and the casts operators in Coq using axioms.

We transitively propagate the type erasures from GADTs and phantom types. Erasing unused type variables is important in order not to block the type inference mechanism of Coq. Indeed, when a type variable is not used:

Definition id_nat {A : Set} (n : nat) : nat := n.

Definition one := id_nat 1.

Coq often reacts with the following error:

> Definition one := id_nat 1.
>                   ^^^^^^
Error: Cannot infer the implicit parameter A of id_nat whose type is "Set".

even if any set could fit for A.

Definition of types

We consider an algebraic type definition in OCaml to be a GADT if the return type parameters of some constructors are not (different) polymorphic type variables. Here is an example of GADT:

type _ expr =
  | Int : int -> int expr
  | Couple : 'a expr * 'b expr -> ('a * 'b) expr

This is not a GADT:

type 'loc ast =
  | Const : int * 'loc -> 'loc ast
  | Add : 'loc ast * 'loc ast * 'loc -> 'loc ast

We could also write 'loc ast with the of syntax:

type 'loc ast =
  | Const of int * 'loc
  | Add of 'loc ast * 'loc ast * 'loc

We do not consider the printable type to be a GADT:

type printable =
  | Printable : 'a * ('a -> string) -> printable

The reason why we define the type printable with the GADT syntax in OCaml is because there is an existential type variable 'a.

We transform the previous types into the following Coq code:

Inductive expr : Set :=
| Int : int -> expr
| Couple : expr -> expr -> expr.

Inductive ast (loc : Set) : Set :=
| Const : int -> loc -> ast loc
| Add : ast loc -> ast loc -> loc -> ast loc.

Arguments Const {_}.
Arguments Add {_}.

Inductive printable : Set :=
| Printable : forall {a : Set}, a -> (a -> string) -> printable.

For the expr type we remove the type parameter. Note that it does not change the information available at runtime. We transform the ast type keeping the type parameter loc. We use a forall quantifier in the Printable constructor to encode the existential type variable a.

Type expressions

We apply the erasure of unused types to type expressions. For example, with the following OCaml code:

type 'a num = int

type 'a num_with_label = 'a num * string

let add_label (n : 'a num) =
  (n, string_of_int n)

we generate the Coq code:

Definition num : Set := int.

Definition num_with_label : Set := num * string.

Definition add_label (n : num) : num_with_label :=
  (n, (OCaml.Stdlib.string_of_int n)).

We consider a type parameter to be unused if:

it does not appear in the type expression (such as in num), or;
is a GADT type parameter, or;
is only used by types which do not use their argument (such as in num_with_label).

Thanks to this propagation of erasure, we limit the number of type parameters appearing in the generated types. This is helpful because with the erasure of GADT parameters many types become useless in Coq and clutter the output. It also reduces the number of type errors during type inference for unused implicit type parameters, as we have seen in the introduction.

Pattern matching

By default, we only do a syntactic transformation from pattern matching in OCaml to pattern matching in Coq. We encode the when clauses with an additional boolean parameter:

let is_positive x =
  match x with
  | Ok n when n >= 0 -> true
  | _ -> false

is transformed to:

Definition is_positive {A : Set} (x : sum int A) : bool :=
  match
    (x,
      match x with
      | Stdlib.Ok n => OCaml.Stdlib.ge n 0
      | _ => false
      end) with
  | (Stdlib.Ok n, true) => true
  | (_, _) => false
  end.

We rename the existential type variables introduced by some constructors to their name in OCaml. The OCaml compiler typically names these variables $something. We can see the existential type names of OCaml in error messages or using Merlin to inspect the type of an expression. Even if not necessary in most cases, having this renaming is helpful:

in case some sub-expressions in a match branch cite the existential types in type annotations;
for debugging, so that the type names on the Coq side are the same as on the OCaml side.

We do this renaming by doing a trick consisting into:

building an existT value;
destructuring this value right after, giving a name to the existential types at this moment.

For example, with our previous printable type example:

type printable =
  | Printable : 'a * ('a -> string) -> printable

let pretty_print (x : printable) : string =
  let Printable (v, to_string) = x in
  to_string v

we get:

Inductive printable : Set :=
| Printable : forall {a : Set}, a -> (a -> string) -> printable.

Definition pretty_print (x : printable) : string :=
  let 'Printable v to_string := x in
  let 'existT _ __Printable_'a [v, to_string] :=
    existT (A := Set)
      (fun __Printable_'a => [__Printable_'a ** __Printable_'a -> string]) _
      [v, to_string] in
  to_string v.

because in OCaml the existential type is named $Printable_'a in this case (we replace the $ symbol by __ to get accepted by Coq).

Pattern matching with axioms

Sometimes, doing a syntactic transformation for the pattern matching is not enough in case of GADTs. For example:

type _ expr =
  | Int : int -> int expr
  | Couple : 'a expr * 'b expr -> ('a * 'b) expr

let left_and_right (e : (int * 'a) expr) : int * 'a expr =
  match e with
  | Couple (Int n, e) -> (n, e)

generates:

Inductive expr : Set :=
| Int : int -> expr
| Couple : expr -> expr -> expr.

Definition left_and_right (e : expr) : int * expr :=
  let 'Couple (Int n) e := e in
  (n, e).

which is ill-typed in Coq:

Error: Non exhaustive pattern-matching: no clause found for pattern Int _

Default branch

We can require a default match branch with the OCaml attribute @coq_match_with_default:

let left_and_right (e : (int * 'a) expr) : int * 'a expr =
  match[@coq_match_with_default] e with
  | Couple (Int n, e) -> (n, e)

which generates:

Definition left_and_right (e : expr) : int * expr :=
  match e with
  | Couple (Int n) e => (n, e)
  | _ => unreachable_gadt_branch
  end.

where unreachable_gadt_branch is an axiom:

Parameter unreachable_gadt_branch : forall {A : Set}, A.

Casting at the entry of branches

Sometimes we need to cast the free variables introduced by patterns:

type 'a int_or_bool =
  | Int : int int_or_bool
  | Bool : bool int_or_bool

let to_int (type a) (kind : a int_or_bool) (x : a) : int =
  match[@coq_match_gadt] (kind, x) with
  | (Int, (x : int)) -> x
  | (Bool, (x : bool)) -> if x then 1 else 0

generates:

Inductive int_or_bool : Set :=
| Int : int_or_bool
| Bool : int_or_bool.

Definition to_int {a : Set} (kind : int_or_bool) (x : a) : Z :=
  match (kind, x) with
  | (Int, _ as x) =>
    let x := cast Z x in
    x
  | (Bool, _ as x) =>
    let x := cast bool x in
    if x then
      1
    else
      0
  end.

where we cast each pattern variable as explicitly stated in the OCaml code. Without type annotations the cast would be towards the type a, what is correct but unhelpful to type-check the Coq code. The cast operator is an axiom:

Axiom cast : forall {A : Set} (B : Set), A -> B.

Note that this axiom is unsound as we can inhabit Empty_set:

cast Empty_set tt : Empty_set

We suppose the use of the cast to be valid as we follow the types computed by the OCaml compiler. To eliminate the cast axiom is proofs, we can use the following evaluation axiom:

Axiom cast_eval : forall {A : Set} {x : A}, cast A x = x.

For example, to show that to_int is idempotent over integers:

Lemma to_int_idempotent (n : Z) : to_int Int (to_int Int n) = n.

we first evaluate the left-hand side expression:

unfold to_int; simpl.

what gives us:

  n : Z
  ============================
  cast Z (cast Z n) = n
1 subgoal

By rewriting two times with cast_eval:

do 2 rewrite cast_eval.

we obtain:

1 subgoal

  n : Z
  ============================
  n = n

and then by reflexivity the proof is completed. If we give incorrect parameters to to_int, such as:

to_int Int false

the cast_eval axiom does not apply. Still, this term cannot be a valid OCaml code, so we believe that the cast_eval axiom covers all the interesting cases.

Casting the result of branches

In case there is a need to also cast the result value of each branch there is the @coq_match_gadt_with_result attribute:

let incr_if_int (type a) (kind : a int_or_bool) (x : a) : a =
  match[@coq_match_gadt_with_result] (kind, x) with
  | (Int, (x : int)) -> x + 1
  | (Bool, (x : bool)) -> x

generates:

Definition incr_if_int {a : Set} (kind : int_or_bool) (x : a) : a :=
  match (kind, x) with
  | (Int, _ as x) =>
    let x := cast Z x in
    cast a (Z.add x 1)
  | (Bool, _ as x) =>
    let x := cast bool x in
    cast a x
  end.

Casting with existential variables

When there are existential type variables in GADTs, we introduce them with an extended form of cast axiom:

Axiom cast_exists : forall {A : Set} {Es : Type} (T : Es -> Set),
  A -> {vs : Es & T vs}.

where Es is typically a tuple of types. For example, to sum a tree of integers with some type witness, we transform:

type _ ty =
  | Int : int ty
  | Couple : 'a ty * 'b ty -> ('a * 'b) ty

let[@coq_struct "t"] rec sum : type a. a ty -> a -> int
  = fun t e ->
  match[@coq_match_gadt] (t, e) with
  | (Int, (n : int)) -> n
  | (Couple (t1, t2), (e1e2 : _ * _)) ->
    let (e1, e2) = e1e2 in
    sum t1 e1 + sum t2 e2

to:

Unset Guard Checking. (* needed to disable termination check *)

Inductive ty : Set :=
| Int : ty
| Couple : ty -> ty -> ty.

Fixpoint sum {a : Set} (t : ty) (e : a) {struct t} : int :=
  match (t, e) with
  | (Int, _ as n) =>
    let n := cast int n in
    n
  | (Couple t1 t2, _ as e1e2) =>
    let 'existT _ [__0, __1] [t1, t2, e1e2] :=
      cast_exists (Es := [Set ** Set])
        (fun '[__0, __1] => [ty ** ty ** __0 * __1]) [t1, t2, e1e2] in
    let '(e1, e2) := e1e2 in
    Z.add (sum t1 e1) (sum t2 e2)
  end.

Here we need to introduce the existential variables with the cast to be able to say that e1e2 is a couple of type __1 * __2, for some types __1 and __2. Like for pattern matching without GADTs, we reuse the names generated by OCaml, replacing the $ symbol by __.

As a result, with all the techniques above, we can translate the whole Tezos protocol to Coq. This includes the interpreter and type-checker of the smart-contract language Michelson, which relies heavily on GADTs. We needed to annotate some of the functions manipulating GADTs, even if we tried to reduce the amount of annotations to a minimum. Eventually, we would like a system where we keep all the type information during the translation, so that we do not need axioms in the generated code.

Latest updates of coq-of-ocaml for the Tezos protocol

Mon, 17 Feb 2020 00:00:00 +0000

We recently made a lot of progress on the formalization in Coq of the Tezos economic protocol, written in OCaml, using coq-of-ocaml. We present here some of the new features of coq-of-ocaml and the results on the formalization of Tezos.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Functors

Previously, we were using dependent records to represent first-class modules. We now use dependent records whenever possible, even for non-first-class modules. This enables us to convert OCaml functors to Coq functions over dependent records. As an example, we translate this OCaml program:

(* Signature of the parameter of the functor *)
module type Source = sig
  type t
  val x : t
end

(* Signature of the result of the functor *)
module type Target = sig
  type t
  val y : t
end

(* Definition of the functor *)
module F (X : Source) : Target with type t = X.t = struct
  type t = X.t
  let y = X.x
end

(* Application to the module [M] *)
module M : Source = struct
  type t = int
  let x = 12
end

module N = F (M)

to the following Coq code:

Module Source.
  Record signature {t : Set} := {
    t := t;
    x : t;
  }.
  Arguments signature : clear implicits.
End Source.

Module Target.
  Record signature {t : Set} := {
    t := t;
    y : t;
  }.
  Arguments signature : clear implicits.
End Target.

Definition F :=
  fun (X : {t : _ & Source.signature t}) =>
    (let t := (|X|).(Source.t) in
    let y := (|X|).(Source.x) in
    existT (fun _ => _) tt
      {|
        Target.y := y
      |} : {_ : unit & Target.signature (|X|).(Source.t)}).

Definition M :=
  let t := Z in
  let x := 12 in
  existT _ _
    {|
      Source.x := x
    |}.

Definition N :=
  F
    (existT _ _
      {|
        Source.x := (|M|).(Source.x)
      |}).

We note (|M|) the projection projT2 to get the second component of an existential type {x : A & P x}. We represent signatures by records parametrized by their abstract types. We wrap these records with existential types for the abstract types which are not precised by a with type t = ... construct. Functors are then plain Coq functions over dependent records. For more details, see the documentation on the module system in coq-of-ocaml.

Our convention is to represent a module as a dependent record if there exists a name for its signature. In this case, we use its signature name for its record’s type name. We consider the other modules as namespaces, and represent them with standard Coq modules.

GADTs and existential types

GADTs, an advanced form of algebraic datatypes, are used a lot in the Tezos protocol. They help to ensure safety properties, like the soundness of the type-checker of the smart-contracts.

GADTs

As we did not find a general way to convert GADTs to Coq, we chose to erase the type annotations and introduce unsafe casts. Here is an example of OCaml code with a GADT:

type 'a int_or_string =
  | Int : int int_or_string
  | String : string int_or_string

let to_string (type a) (kind : a int_or_string) (x : a) : string =
  match[@coq_match_gadt] kind, x with
  | Int, (x : int) -> string_of_int x
  | String, (x : string) -> x

Note the [@coq_match_gadt] on the match and the type annotations on the variable x in the patterns. We import this code in Coq to:

Reserved Notation "'int_or_string".

Inductive int_or_string_gadt : Set :=
| Int : int_or_string_gadt
| String : int_or_string_gadt

where "'int_or_string" := (fun (_ : Set) => int_or_string_gadt).

Definition int_or_string := 'int_or_string.

Definition to_string {A : Set} (kind : int_or_string A) (x : A) : string :=
  match (kind, x) with
  | (Int, _ as x) =>
    let 'existT _ tt x := cast_exists (fun _ => Z) x in
    cast string (OCaml.Stdlib.string_of_int x)
  | (String, _ as x) =>
    let 'existT _ tt x := cast_exists (fun _ => string) x in
    cast string x
  end.

We convert the GADT int_or_string to an inductive int_or_string_gadt without annotations. We generate two axioms in each branch of the match, to cast:

the variables introduced by the pattern;
the result of the branch.

The axiom cast is the equivalent in Coq of the OCaml’s Obj.magic cast. It has the following signature:

Axiom cast : forall {A : Set} (B : Set), A -> B.

We say that:

cast behaves as the identity function when A is equal to B;
is undefined in other cases.

To specify this behavior, we use the following axiom:

Axiom cast_eval : forall {A : Set} {x : A}, cast A x = x.

While doing proofs, we must use the axiom cast_eval to evaluate cast by proving that the types A and B are the same. Doing so, we also verify that the type unifications of the type-checker of OCaml are indeed correct. The cast_exists axiom is like cast with the ability to introduce some existential variables when needed.

Existential variables

Types with existential variables are a special case of GADTs, where the type parameters are the same for all the constructors. For example, to represent a value which can be converted to a string, we can use:

type printable = Printable : 'a * ('a -> string) -> printable

let printable_to_string (x : printable) : string =
  let Printable (value, print) = x in
  print value

In this example, 'a is an existential variable. Coq also support existential variables in algebraic types. Here is what we generate for this example:

Inductive printable : Set :=
| Printable : forall {a : Set}, a -> (a -> string) -> printable.

Definition printable_to_string (x : printable) : string :=
  let 'Printable value print := x in
  let 'existT _ __Printable_'a [value, print] :=
    existT
      (fun __Printable_'a : Set =>
        [__Printable_'a ** (__Printable_'a -> string)]) _ [value, print] in
  print value.

We do not need any axioms. The let 'existT _ __Printable_'a [value, print] := block is there to rename the existential variables generated by Coq to the names of the OCaml compiler. We replace the forbidden symbol $ by __, so that:

$Printable_'a

becomes:

__Printable_'a

Having well named existential variables helps to get:

cleaner error messages;
type annotations on sub-expressions using these existential variables.

Documentation website

We added a website for coq-of-ocaml to have a central place with documentation. We used Docusaurus to generate the website. We chose Docusaurus for the following reasons:

open-source;
good defaults;
generates static HTML;
we can write the documentation in Markdown.

We converted most of the protocol

At the time of writing, 57% of the Coq code generated by coq-of-ocaml for the Tezos protocol compiles. This includes the interpreter of the smart-contracts, and amounts to around 30.000 lines of valid Coq code. We still ignore many features, like the side-effects or the extensible types. The main missing files are the *_services.ml files and the type-checker of smart-contracts (6.000 lines of OCaml, the largest file of the protocol).

Formalization of the Tezos protocol's interface in Coq

Wed, 15 Jan 2020 00:00:00 +0000

The protocol of Tezos is written in the OCaml language. It uses a restricted OCaml interface of a few thousands lines of code to access to its primitives. Using the compiler coq-of-ocaml, we generate a Coq formalization of most of the Tezos protocol’s interface (the missing OCaml constructs are listed here). We hope this work to be a first step to enable formal reasoning on the implementation of the Tezos protocol. In this blog post, we present what we added to coq-of-ocaml in order to support the Tezos interface.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Polymorphic variants

In OCaml, we can tag sum types with the backquote operator as follows:

type json =
  [ `O of (string * json) list
  | `Bool of bool
  | `Float of float
  | `A of json list
  | `Null
  | `String of string ]

There are no direct equivalents in Coq and we generate a warning message when we encounter tags. Still, we generate some code as a first approximation. For type definitions we generate a Coq inductive:

Inductive json : Set :=
| Bool : bool -> json
| Null : json
| O : list (string * json) -> json
| Float : Z -> json
| String : string -> json
| A : list json -> json.

and for inlined variants:

val fold :
  t ->
  key ->
  init:'a ->
  f:([`Key of key | `Dir of key] -> 'a -> 'a Lwt.t) ->
  'a Lwt.t

we generate a sum type with the tags as comments:

Parameter fold : forall {a : Set},
  t -> key -> a -> ((* `Dir *) key + (* `Key *) key -> a -> Lwt.t a) ->
  Lwt.t a.

Types and values collisions

In Coq, in contrast to OCaml, types and values live in the same namespace. Thus there are often name collisions in the generated code. Typically, this is due to the use of values having the same name as their type. We prevent that for the common cases (list, string, …) by translating the value names with a _value suffix. For example, we convert:

val string : string encoding

to:

Parameter __string_value : encoding string.

Modules

We added the import of the definitions of module types in the .mli files. The code to do so is the same as for .ml files. For example, we import:

module type COMPARABLE = sig
  type t

  val compare : t -> t -> int
end

to:

Module COMPARABLE.
  Record signature {t : Set} := {
    t := t;
    compare : t -> t -> Z;
  }.
  Arguments signature : clear implicits.
End COMPARABLE.

We handle the import of modules declared with a signature by unfolding the signature. We do so as we do not represent signatures in Coq unless for first-class modules (using a record type). For example, we import:

module String : COMPARABLE with type t = string

to:

Module String.
  Definition t := string.

  Parameter compare : t -> t -> Z.
End String.

This idea is due to Mehdi Bouaziz.

We also handle the include keyword by doing a similar unfolding. The unfolding of include significantly increases the size of the Coq code for the Tezos protocol’s interface. Indeed, the number of generated lines for the interface was multiplied by two once we converted the include occurences.

First-class modules

We improved the detection of first-class modules. The detection of first-class modules is a challenge in coq-of-ocaml. Indeed, we need to distinguish between first-class and plain modules in order to generated either a dependent record or a Coq module. Moreover, there are no builtin ways to translate between a record and a module in Coq.

When we access to the field of a module, we consider this module as a Coq record when it:

has a named signature (to have a corresponding named record definition);
is locally opened in an expression.

We added the constraint of being locally opened in order to filter out some plain modules with a named signature. We may change this rule in the future and convert more plain modules to records by default, as this could factorize the generated code and help to handle functors.

We added the support of first-class modules with polymorphic abstract types. For that, we mark the arity of the abstract types. For example, for a map signature in OCaml:

module type MAP = sig
  type key
  type +'a t
  val empty : 'a t
  val is_empty : 'a t -> bool
  val mem : key -> 'a t -> bool
end

we generate:

Module MAP.
  Record signature {key : Set} {t : Set -> Set} := {
    key := key;
    t := t;
    empty : forall {a : Set}, t a;
    is_empty : forall {a : Set}, t a -> bool;
    mem : forall {a : Set}, key -> t a -> bool;
  }.
  Arguments signature : clear implicits.
End MAP.

Records

In Coq, the fields of a record are projection functions which live in the same namespace as the values. Thus Coq is more prone to name collisions for record fields than OCaml. We solve this issue by putting the record definitions into modules of the same name. For example, for the record:

type descr = {name : string; descr : string option}

we generate the following Coq code:

Module descr.
  Record record := {
    name : string;
    descr : option string }.
End descr.
Definition descr := descr.record.

We thus prevent a name collision between the record type descr and the record field descr.

In subsequent accesses to the record fields, we prefix the projections by the record name. For example, to access to the name field of a record instance r of descr, we write in Coq:

r.(descr.name)

Pretty-printing

We improved the pretty-printing for the types. In particular:

we limit the number of parenthesis by taking into account the precedence of the operators;
we use a more consistent indentation.

As an example, we moved from the following generated Coq:

| FLambda : Z -> (list ((Context.binder_annot Names.Name.t) * Constr.constr)) ->
  Constr.constr -> (Esubst.subs fconstr) -> fterm

to:

| FLambda :
  Z -> list (Context.binder_annot Names.Name.t * Constr.constr) ->
  Constr.constr -> Esubst.subs fconstr -> fterm

Conclusion

We generated around six thousands valid Coq lines. Some OCaml constructs were missing, such as the extensible types. We may not support them as we see no direct equivalents in Coq. There is also a lot of code duplication due to the repetitive inclusion of similar module signatures. We will try to find solutions to factorize the generated code.

Finally, we will see if the code for the Tezos interface is usable when applying coq-of-ocaml to the protocol implementation.

First-class modules in coq-of-ocaml

Mon, 04 Nov 2019 00:00:00 +0000

For now, coq-of-ocaml only supports plain modules used as namespaces (no functors). First-class modules are an important construction to abstract code in OCaml as there are flexible and used heavily in some programs (including in Tezos). We present our strategy to import first-class modules to dependent record in Coq. We show that it works for the set example extracted from the Tezos source code.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Strategy

Here is an example of a first-class module in OCaml. We say that a type t is Printable when it provides a function to_string to convert it in string:

module type Printable = sig
  type t
  val to_string : t -> string
end

Given a printable type, we can write a generic function to print it on the terminal:

let print_on_the_terminal
  (type a)
  (module PrintableInstance : Printable with type t = a)
  (x : a)
  : unit =
  print_endline (PrintableInstance.to_string x)

The module Printable encapsulates both a type t and some associated data to_string. We model that with a dependent record in Coq, that is to say a record mixing types and values:

Module Printable.
  Record signature {t : Type} := {
    t := t;
    to_string : t -> string;
  }.
  Arguments signature : clear implicits.
End Printable.

Since the type t is not known at this point, we model it with a type parameter t. Later on, when someone uses the syntax with type t = ..., we call the signature with the value for t. We define a synonym field t := t to have a uniform way to access to the fields of the module. We put the whole record into a module Printable to namespace the projections and prevent name collisions.

We generate the following Coq code for the print_on_the_terminal function:

Definition print_on_the_terminal {A : Type}
  (PrintableInstance : {_ : unit & Printable.signature A}) : A -> unit :=
  let PrintableInstance := projT2 PrintableInstance in
  fun x =>
    print_endline (PrintableInstance.(Printable.to_string) x).

The print_endline function is an axiom, as side-effects are forbidden in Coq. The curly braces {} set implicit the type parameter A, because type variables are implicit in OCaml. The PrintableInstance value is a dependent pair, since it may contain a list of type values for the abstract types of the module. Here the only abstract type t is already filled with a value A, thus there are no type values (_ : unit). We open the dependent pair with projT2. We use the projection Printable.to_string to access to the to_string function of the module.

We often use types with a first-class module in a boxed form, where we associate both a module type and its value:

module type BoxedPrintable = sig
  module Printable : Printable
  val value : Printable.t
end

let print_boxed_printable (module BoxedPrintable : BoxedPrintable) : unit =
  print_endline (BoxedPrintable.Printable.to_string BoxedPrintable.value)

In Coq, we proceed as for the previous module and propagate the abstract type t of the sub-module Printable to the signature of BoxedPrintable:

Module BoxedPrintable.
  Record signature {Printable_t : Type} := {
    Printable : Printable.signature Printable_t;
    value : Printable.(Printable.t);
  }.
  Arguments signature : clear implicits.
End BoxedPrintable.

For the function print_boxed_printable, we use a parameter Printable_t in the dependent pair BoxedPrintable as the abstract type t is not known at this point. More generally, the abstract types are universally quantified in the definition of signatures and existentially quantified in values.

Definition print_boxed_printable
  (BoxedPrintable : {Printable_t : _ & BoxedPrintable.signature Printable_t})
  : unit :=
  let BoxedPrintable := projT2 BoxedPrintable in
  print_endline
    (BoxedPrintable.(BoxedPrintable.Printable).(Printable.to_string)
      BoxedPrintable.(BoxedPrintable.value)).

Note that the path to access the to_string function in Coq is more verbose and more explicit than in OCaml.

What we support

We support first-class modules with values, abstract types and type synonyms. We do not support first-class modules with other kinds of fields, such as the definition of new algebraic data types. We do not support functors (although we support first-class functions on first-class modules).

A difficulty is to be able to distinguish between first-class modules and plain modules. This is necessary because we import first-class modules to dependent records and plain modules to Coq modules. For example, for projections, the syntax in OCaml is the same in both cases but different in Coq. When accessing a field of a module, we consider the module to be first-class if there exists a signature of the same shape. Once we found the name of the signature, we generate a call to the corresponding projection in Coq. If there are more than one signature corresponding to a module we generate an error. This can be the case because OCaml modules are not generative by default (we can make generative OCaml modules by adding a () parameter). Our strategy to decide if a module is first-class is a heuristic, we may reconsider it later.

Set example

Here is the definition of sets as first-class modules, extracted from the Tezos source code:

module S = struct
  module type SET = sig
    type elt
    type t
    val empty: t
    val is_empty: t -> bool
    val mem: elt -> t -> bool
    val add: elt -> t -> t
    val remove: elt -> t -> t
  end
end

type 'a comparable_ty

module type Boxed_set = sig
  type elt
  val elt_ty : elt comparable_ty
  module OPS : S.SET with type elt = elt
  val boxed : OPS.t
  val size : int
end

type 'elt set = (module Boxed_set with type elt = 'elt)

let set_update
  : type a. a -> bool -> a set -> a set
  = fun v b (module Box) ->
  (module struct
    type elt = a
    let elt_ty = Box.elt_ty
    module OPS = Box.OPS
    let boxed =
      if b
      then Box.OPS.add v Box.boxed
      else Box.OPS.remove v Box.boxed
    let size =
      let mem = Box.OPS.mem v Box.boxed in
    if mem
    then if b then Box.size else Box.size - 1
    else if b then Box.size + 1 else Box.size
  end)

We successfully generate the following valid Coq code:

Module S.
  Module SET.
    Record signature {elt t : Type} := {
      elt := elt;
      t := t;
      empty : t;
      is_empty : t -> bool;
      mem : elt -> t -> bool;
      add : elt -> t -> t;
      remove : elt -> t -> t;
    }.
    Arguments signature : clear implicits.
  End SET.
End S.

Parameter comparable_ty : forall (a : Type), Type.

Module Boxed_set.
  Record signature {elt OPS_t : Type} := {
    elt := elt;
    elt_ty : comparable_ty elt;
    OPS : S.SET.signature elt OPS_t;
    boxed : OPS.(S.SET.t);
    size : Z;
  }.
  Arguments signature : clear implicits.
End Boxed_set.

Definition set (elt : Type) := {OPS_t : _ & Boxed_set.signature elt OPS_t}.

Definition set_update {a : Type} (v : a) (b : bool) (Box : set a) : set a :=
  let Box := projT2 Box in
  existT _ _
    {|
      Boxed_set.elt_ty := Box.(Boxed_set.elt_ty);
      Boxed_set.OPS := Box.(Boxed_set.OPS);
      Boxed_set.boxed :=
        if b then
          Box.(Boxed_set.OPS).(S.SET.add) v Box.(Boxed_set.boxed)
        else
          Box.(Boxed_set.OPS).(S.SET.remove) v Box.(Boxed_set.boxed);
      Boxed_set.size :=
        let mem := Box.(Boxed_set.OPS).(S.SET.mem) v Box.(Boxed_set.boxed) in
        if mem then
          if b then
            Box.(Boxed_set.size)
          else
            Z.sub Box.(Boxed_set.size) 1
        else
          if b then
            Z.add Box.(Boxed_set.size) 1
          else
            Box.(Boxed_set.size)
      |}.

We use existT _ _ to instantiate a dependent pair. We rely on the inference mechanism of Coq to fill the existential type variable OPS_t in this pair.

Future work and opinions

Things are not perfect yet. We still need to test the implementation more, debug, and add some features such as polymorphic abstract types.

As a matter of taste, we prefer to import OCaml code to dependent records rather than functors. Indeed, we believe that records are safer than functors. The implementation of functors in the Coq kernel is complex as we have heard, while dependent records are already given by the dependent types. Moreover, Coq functors are generative while OCaml ones are not. We hope that we will not need Coq functors to import the code we wish to verify.

Importing mutually recursive types from OCaml to Coq

Sat, 28 Sep 2019 00:00:00 +0000

In order to make coq-of-ocaml usable on a maximum of OCaml programs, we should handle mutually recursive types. We show how we import these types to Coq and the main differences between the two languages. As a result, more OCaml programming patterns should be supported by coq-of-ocaml.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Example

Take the following mutually recursive definition of a tree in OCaml:

type 'a tree = Tree of 'a node list

and 'a node =
  | Leaf of 'a leaf
  | Node of 'a tree

and 'content leaf = string * 'content

By applying coq-of-ocaml on this code we get:

Reserved Notation "'leaf".

Inductive tree (a : Type) : Type :=
| Tree : (list (node a)) -> tree a

with node (a : Type) : Type :=
| Leaf : ('leaf a) -> node a
| Node : (tree a) -> node a

where "'leaf" := (fun (content : Type) => string * content).

Definition leaf := 'leaf.

Arguments Tree {_}.
Arguments Leaf {_}.
Arguments Node {_}.

We transform algebraic data types to Coq’s inductive types. We use a notation to implement the type synonym leaf. This is a trick because Coq only supports inductive types in mutual definitions. See the documentation on notations for more information. We rename the leaf type parameter 'content instead of 'a to avoid a name collision in Coq. The type parameters of the constructors are set implicit with the command Arguments to keep the behavior of OCaml.

General mechanism

We handle type ... and ... definitions with algebraic data types (including GADTs, “Generalized Algebraic Data Types”) and type synonyms. We do not handle abstract types. For records in mutual definitions, one can use a type synonym to a more generic record. For example:

type expression =
  | Number of int
  | Operation of operation

and operation = {
  name : string;
  parameters : expression list }

can be rewritten as:

type 'a operation_skeleton = {
  name : string;
  parameters : 'a list }

type expression =
  | Number of int
  | Operation of operation

and operation = expression operation_skeleton

in order to be imported into Coq.

In Coq, there is a distinction between type variables on the left (type parameters) and on the right of the : (type indices):

Inductive t (A1 A2 ... : Type) : forall (B1 B2 ... : Type), Type :=
| Constr1 : ... -> t A1 A2 ... C1 C2 ...
| ...

The variables Ai do not behave the same as the variables Bi. Type parameters have the constraint of being the same for each constructor. When used, they simplify the typing of the pattern matching. Typically, in GADTs, type variables are type indices while in non-generalized algebraic data types they are type parameters. In mutually recursive inductive types there is one more constraint: the type parameters must be the same for each type. We consider a type variable to be a parameter if it appears with the same name in each OCaml constructor and in the type definition. For example:

type ('a, 'b) arith =
  | Int : 'a * int -> ('a, int) arith
  | Eq : 'a * ('a, int) arith * ('a, int) arith -> ('a, bool) arith
  | Plus : 'a * ('a, int) arith * ('a, int) arith -> ('a, int) arith

is imported to:

Inductive arith (a : Type) : forall (b : Type), Type :=
| Int : a -> Z -> arith a Z
| Eq : a -> (arith a Z) -> (arith a Z) -> arith a bool
| Plus : a -> (arith a Z) -> (arith a Z) -> arith a Z.

Arguments Int {_}.
Arguments Eq {_}.
Arguments Plus {_}.

Here we transform 'a to a type parameter and 'b to a type index.

Limitations

Many OCaml programs define all types as mutually recursive by default. In Coq this is usually very difficult as:

only algebraic and synonym types can be mutual;
all type parameters must be the same;
the “strictly positive” constraint in Coq prevents some constructions (such as having a type as a type parameter for another);
the proofs or the definition of recursive functions on mutually recursive types is more complicated than with simple recursive types.

In practice, I would recommend to find a way to avoid mutually recursive types when possible. For cases they are used, I hope this import mechanism to be useful.

Multiple error messages in coq-of-ocaml

Fri, 13 Sep 2019 00:00:00 +0000

The coq-of-ocaml compiler transforms OCaml programs to Coq ones. There usually are many errors in each file to import (the Coq language tends to be stricter than OCaml and we do not want to import code with too much encoding). Fixing errors may be the most time consuming part of an import. We present a system to display all the errors at once instead of one by one. We believe that it helps to get a quick idea of how difficult a file is to translate, while having a sense of progress when fixing the errors.

We develop coq-of-ocaml at 🐙 Nomadic Labs with the aim to formally verify OCaml programs, and in particular the implementation of the crypto-currency Tezos. If you want to use this tool for your own projects, please do not hesitate to look at our website or contact us!

Multiple errors report

Example

Take this perfectly valid OCaml program:

let foo x =
  if x then
    assert false (* no assert in Coq *)
  else begin
    print_endline "bar"; (* no sequencing of side-effects in Coq *)
    true
  end

We would like to report that both the assert and the sequencing of effects with ; are not available in Coq.

To import programs, coq-of-ocaml runs a single pass on the OCaml’s typed abstract syntax tree. During the recursive exploration of the syntax tree, we would like to explore both branches of the if to report both errors. We need a way to accumulate errors along the way and not block at the first mistake. Since coq-of-ocaml has a single pass, we hope to get most of the errors doing so.

An error monad

To encapsulate the error handling mechanism, we define the following free monad in OCaml (coq-of-ocaml is implemented in OCaml):

module Command = struct
  type 'a t =
    | GetEnv : Env.t t
    | Raise : Error.Category.t * string -> 'a t
end

module Wrapper = struct
  type t =
    | SetEnv of Env.t
    | SetLoc of Loc.t
end

type 'a t =
  | All : 'a t * 'b t -> ('a * 'b) t
  | Bind : 'b t * ('b -> 'a t) -> 'a t
  | Command of 'a Command.t
  | Return of 'a
  | Wrapper of Wrapper.t * 'a t

There are three main constructs to note:

All which combines the results of two computations, both of which may fail. It allows to accumulate errors in each branch of the syntax tree;
Command, especially the case Raise to create an error at the current code location;
Wrapper, especially the case SetLoc to set the current code location in (and only in) the following computation.

We also have primitives GetEnv and SetEnv to manipulate the current OCaml environment from the AST. The Bind and Return are the standard monadic primitives. We chose a free-monad in order to isolate the definition of side-effects and, one day, import coq-of-ocaml to Coq.

We rewrote coq-of-ocaml using the All primitive as much as possible (typically when two computations were not depending on each other). Since the current OCaml environment and location are handled by the monad, we cleaned the code to propagate their values. Having done that, retrieving the complete list of errors was mostly given for free.

A nice output

In order to present a nice output to the user, we decided to do the following:

add colors;
show the code extract where the error comes from, using a presentation similar to the JavaScript’s @babel/code-frame (for now an error location is a line; we plan to precise the column and add multiline support);
clearly separate errors with a long line and some spaces;
add an error category (side-effect, dependency not found, …).

Some of these changes were inspired by the Elm blog post on producing Compiler Errors for Humans.

Fixing flaky makefiles in opam Coq packages

Wed, 04 Sep 2019 00:00:00 +0000

In opam, some packages fail to install sometimes. This is a problem because these bugs are hard to reproduce. Yet the user may get the impression that some packages are broken. We show how we listed and then corrected these bugs. The opam Coq repository should now be more stable.

Round 1

At first we (I) did not know how to fix these installation bugs. They would typically result in OCaml errors such as:

The following actions will be performed:
  - install coq-rational 8.6.0
[...]
- File "Rewrite/LeibnizRewrite/AC/aC.ml", line 1:
- Error: Corrupted compiled interface

in coq-rational.8.6.0. As we ran opam with the option -j1 (one parallel build), this did not seem like a concurrency bug. We decided to add a black-list file to the Coq opam bench to list out and hide these bugs. This was not a perfect solution, but at least it did not flood the results with non-reproducible errors.

Round 2

As noticed by Karl Palmskog, the opam builds were running in parallel despite the -j1 option. As a proof, the presence in the installation traces of:

make[2]: *** Waiting for unfinished jobs....

This was due to a bug in opam, corrected in version 2.0.5. Thus the fix was just to replace:

[make "-j%{jobs}%"]

by:

[make]

in each package definition with parallel build issues.

These errors occurred in most of the packages using coq_makefile and mixing Coq and OCaml code. The versions 4.02 and 4.05 of OCaml were impacted, but the version 4.07 seems free of bugs. The most frequent error message is Corrupted compiled interface. Apparently this happens when both byte and opt compilations run in parallel, modifying .cmi files at the same time. The Dune build system may be a more robust alternative to coq_makefile, but I have no data about it.

Result

Most of the Coq packages with flaky makefiles are now corrected, and the respective maintainers contacted. We will continue to fix these bugs as they occur.

Connecting the opam bench to Gitter

Tue, 03 Sep 2019 00:00:00 +0000

The Coq opam bench system detects bugs in opam packages from the Coq repository. However these bugs may be hard to follow. Indeed, they are in a table one needs to consult regularly. We present a system to post results in a Gitter channel coq/opam-bench-reports. Thanks to this channel, we can more easily track down the latest build failures.

The idea of publishing results in Gitter was given by Emilio Jesús Gallego Arias in coq/issues/10418. Improvements were added from suggestions from Emilio Jesús Gallego Arias and Karl Palmskog.

Bench report in Gitter

Implementation

The code to publish results in Gitter is at github.com/coq-bench/make-html. The implementation is in Ruby and shares code with the bench website generator. We extract the results from a CSV database generated by the project github.com/coq-bench/run which tests the packages.

To connect to Gitter, we use the ruby-gitter package. The code goes as follows:

# Use the developer token from the Gitter documentation
# (what is possible as very few messages are sent)
client = Gitter::Client.new(token)

# Find the room id
room = client.rooms.find {|room| room.name == "coq/opam-bench-reports"}
room_id = room.id

# Construct the message with the results
message = "..."

# Actually send the message
client.send_message(message, room_id)

We use a dedicated coq-opam-bench-gitter-bot user to publish on Gitter and sign the messages. We retrieve the results of the past 72 hours, and run the code every 72 hours with a shell command:

while true; do sleep 72h; date; git pull; ruby push_to_gitter.rb ../database gitter-token coq/opam-bench-reports 72; done

Note the git pull of hot code swapping! This is useful to integrate small bench updates without breaking the 72 hours rythm.

We either display the list of packages which failed, or a success message.

Results

We went from dozens of errors every 72 hours (when setting up the system) to just a few these days. Probably, this was mainly due to the bug corrections themselves but the Gitter reports helped. The Gitter reports also created a channel to talk about opam bugs.

Continuous testing for Coq projects

Thu, 25 Jul 2019 00:00:00 +0000

Testing that a Coq project works with different Coq versions may be time consuming. This is necessary to deliver with confidence new project releases. Travis CI is a service to run tests on GitHub projects and is free for open-source code. We show a setup to run automated testing with Travis CI using pre-compiled Coq instances and opam. Thanks to that setup, we can automatically and quickly check new pull-requests and commits.

This configuration is directly inspired by the CI setup documentation written by Erik Martin-Dorel.

Travis CI report on a pull-request

Setting up Travis CI

To show the setup Travis CI, we take the example of the github.com/coq-io/system project. We need to create two files at the root of the project:

coq-io-system.opam to describe the dependencies;
.travis.yml to configure and activate Travis CI.

Describing the dependencies

We create an opam file coq-io-system.opam with the following content:

version: "dev"

opam-version: "2.0"
maintainer: "dev@clarus.me"
homepage: "https://github.com/clarus/io-system"
dev-repo: "git+https://github.com/clarus/io-system.git"
bug-reports: "https://github.com/clarus/io-system/issues"
authors: ["Guillaume Claret"]
license: "MIT"
build: [
  ["./configure.sh"]
  [make "-j%{jobs}%"]
]
install: [
  [make "install"]
]
depends: [
  "ocaml"
  "coq" {>= "8.5"}
  "coq-function-ninjas"
  "coq-list-string" {>= "2.0.0"}
  "coq-io" {>= "4.0.0"}
  "coq-io-system-ocaml" {>= "2.3.0"}
]
tags: [
  "keyword:effects"
  "keyword:extraction"
  "logpath:Io/System"
]
synopsis: "System effects for Coq"

This file describes the dependencies of the project. It can list any other opam packages published on the OCaml repository or the Coq repository. We also give the build and install commands. To check that this file is correct:

# linting to check for typos
opam lint coq-io-system.opam
# adding the Coq repository if not already done
opam repo add coq-released https://coq.inria.fr/opam/released
# installing the package
opam pin add coq-io-system . --kind=path -y

Later on, you may want to publish your package in opam. You can just take this file content and create a pull-request on the Coq repository. Since this opam file is used for continuous testing, you can be pretty confident that your package is correct.

Configuring Travis CI

We add a Travis CI file .travis.yml with the following content:

dist: bionic
language: generic

services:
  - docker

env:
  global:
  - PACKAGE_NAME="coq-io-system"
  matrix:
  - COQ_IMAGE="coqorg/coq:8.4"  SHOULD_SUPPORT="false"
  - COQ_IMAGE="coqorg/coq:8.5"  SHOULD_SUPPORT="true"
  - COQ_IMAGE="coqorg/coq:8.6"  SHOULD_SUPPORT="true"
  - COQ_IMAGE="coqorg/coq:8.7"  SHOULD_SUPPORT="true"
  - COQ_IMAGE="coqorg/coq:8.8"  SHOULD_SUPPORT="true"
  - COQ_IMAGE="coqorg/coq:8.9"  SHOULD_SUPPORT="true"
  - COQ_IMAGE="coqorg/coq:8.10" SHOULD_SUPPORT="true"

install: |
  # Prepare the COQ container
  docker pull ${COQ_IMAGE}
  docker run -d -i --init --name=COQ -v ${TRAVIS_BUILD_DIR}:/home/project -w /home/project ${COQ_IMAGE}
  docker exec COQ /bin/bash --login -c "
    # This bash script is double-quoted to interpolate Travis CI env vars:
    echo \"Build triggered by ${TRAVIS_EVENT_TYPE}\"
    export PS4='+ \e[33;1m(\$0 @ line \$LINENO) \$\e[0m '
    set -ex  # -e = exit on failure; -x = trace for debug
    opam update
    opam pin add ${PACKAGE_NAME} . --kind=path --no-action -y
    opam config list; opam repo list; opam pin list; opam list
    " install

script:
- echo -e "${ANSI_YELLOW}Building...${ANSI_RESET}" && echo -en 'travis_fold:start:script\\r'
- |
  docker exec COQ /bin/bash --login -c "
    export PS4='+ \e[33;1m(\$0 @ line \$LINENO) \$\e[0m '
    set -ex
    sudo chown -R coq:coq /home/project
    # Check if the package is compatible with the current environment
    if [ "${SHOULD_SUPPORT}" = "true" ] || opam install ${PACKAGE_NAME} --show-action -y; then
      # First install the dependencies
      opam install ${PACKAGE_NAME} --deps-only -y
      opam list
      # Then install the package itself in verbose mode
      opam install ${PACKAGE_NAME} -v -y
    fi;
    " script
- echo -en 'travis_fold:end:script\\r'

after_script:
- docker stop COQ  # optional

This YAML file explains to Travis CI what to do to check the project. We use the coqorg/coq Docker images. These images have pre-compiled versions of Coq with opam, what is crucial to speedup the tests. For each architecture from Coq 8.4 to Coq 8.9 we:

check if either:
- the platform is supposed to be supported if [ "${SHOULD_SUPPORT}" = "true" ],
- or if opam considers the platform as compatible opam install ${PACKAGE_NAME} --show-action -y;
install the dependencies opam install ${PACKAGE_NAME} --deps-only -y;
install the project in verbose mode opam install ${PACKAGE_NAME} -v -y.

Using Travis CI

You may need to activate Travis CI for your project in the settings page of Travis CI. Then for each pull-request or commit you will see a green or red mark precising if the project passed the tests, along with detailed logs when you click on it:

Commits in a pull-request

Error logs

Thanks for reading!

Approximating GADTs in Flow

Tue, 24 Jul 2018 00:00:00 +0000

The GADTs (Generalized algebraic data types) are a generalization of sum types where the type parameter can change in each case. GADTs are not available in Flow but we show a technique to approximate them. We take inspiration from Approximating GADTs in PureScript.

Use case

Let us say we want to implement an evaluator for simple arithmetic expressions. We define the type of expressions:

type Expr = {
  type: 'I',
  value: number
} | {
  type: 'B',
  value: boolean
} | {
  type: 'Add',
  x: Expr,
  y: Expr
} | {
  type: 'Mul',
  x: Expr,
  y: Expr
} | {
  type: 'Eq',
  x: Expr,
  y: Expr
};

and an evaluation function:

function evaluate(expr: Expr): boolean | number {
  switch (expr.type) {
    case 'I':
      return expr.value;
    case 'B':
      return expr.value;
    case 'Add':
      return evaluate(expr.x) + evaluate(expr.y);
    case 'Mul':
      return evaluate(expr.x) * evaluate(expr.y);
    case 'Eq':
      return evaluate(expr.x) === evaluate(expr.y);
    default:
      return expr;
  }
}

but we get a Flow error:

32:  return evaluate(expr.x) * evaluate(expr.y);
            ^ Cannot perform arithmetic operation because boolean [1] is not a number.
References:
23: function evaluate(expr: Expr): boolean | number {
                                   ^ [1]

This error occurs because Flow does not know if we multiply booleans or numbers since the return type of evaluate is boolean | number. Flow is right to warn us because the type Expr does not prevent to write expressions multiplying booleans:

const foo: Expr = {
  type: 'Mul',
  x: {type: 'B', value: true},
  y: {type: 'B', value: false}
};

To force the multiplication to be over numeric expressions, we would like to distinguish expressions which evaluate to a number from expressions which evaluate to a boolean.

GADTs to the rescue

GADTs allow to parametrize the expression type Expr by the return type of the evaluation (either boolean or number). In a language with GADTs like Haskell we can define a type Expr a (with a the type of the evaluation result) as follows:

-- In Haskell:
data Expr a where
  B :: Bool -> Expr Bool
  I :: Int -> Expr Int
  Add :: Expr Int -> Expr Int -> Expr Int
  Mult :: Expr Int -> Expr Int -> Expr Int
  Eq :: Expr Int -> Expr Int -> Expr Bool

evaluate :: Expr a -> a
evaluate expr = ...

Unfortunately, Flow has no syntax to express this kind of types:

type Expr<A> = {
  type: 'I', // Where do we say this is Expr<number>?
  value: number
} | {
  type: 'B', // Where do we say this is Expr<boolean>?
  value: boolean
} | {
  ...

Encoding in Flow

We use a trick to encode GATDs in Flow. We express that in the case type: 'I' of an expression of type Expr<A> the type A is actually a number by adding an equality witness _eq between A and number:

type Expr<A> = {
  type: 'I',
  _eq: number => A,
  value: number
} | {
  ...

To make the equality witness _eq valid, we must define it with the identity function:

function i(value: number): Expr<number> {
  return {type: 'I', _eq: x => x, value};
}

The full defintion:

type Expr<A> = {
  type: 'I',
  _eq: number => A,
  value: number
} | {
  type: 'B',
  _eq: boolean => A,
  value: boolean
} | {
  type: 'Add',
  _eq: number => A,
  x: Expr<number>,
  y: Expr<number>
} | {
  type: 'Mul',
  _eq: number => A,
  x: Expr<number>,
  y: Expr<number>
} | {
  type: 'Eq',
  _eq: boolean => A,
  x: Expr<number>,
  y: Expr<number>
};

and all the wrappers:

function i(value: number): Expr<number> {
  return {type: 'I', _eq: x => x, value};
}

function b(value: boolean): Expr<boolean> {
  return {type: 'B', _eq: x => x, value};
}

function add(x: Expr<number>, y: Expr<number>): Expr<number> {
  return {type: 'Add', _eq: x => x, x, y};
}

function mul(x: Expr<number>, y: Expr<number>): Expr<number> {
  return {type: 'Mul', _eq: x => x, x, y};
}

function eq(x: Expr<number>, y: Expr<number>): Expr<boolean> {
  return {type: 'Eq', _eq: x => x, x, y};
}

We can then define a well-typed evaluate function by applying the _eq witness to use the type equalities when needed:

function evaluate<A>(expr: Expr<A>): A {
  switch (expr.type) {
    case 'I':
      return expr._eq(expr.value);
    case 'B':
      return expr._eq(expr.value);
    case 'Add':
      return expr._eq(evaluate(expr.x) + evaluate(expr.y));
    case 'Mul':
      return expr._eq(evaluate(expr.x) * evaluate(expr.y));
    case 'Eq':
      return expr._eq(evaluate(expr.x) === evaluate(expr.y));
    default:
      return expr;
  }
}

const e1: Expr<number> = add(i(2), i(4));
const e2: Expr<number> = mul(i(2), i(3));
const e3: Expr<boolean> = eq(e1, e2);
console.log(evaluate(e1), evaluate(e2), evaluate(e3));

Note that _eq has no runtime value, is only here for typing and could be eliminated given a clever enough compiler / interpreter.

Robustness

We test the effectiveness of this encoding by introducing some errors in our code. In the definition of expressions:

mistake:

const e1: Expr<boolean> = add(i(2), i(4));

Flow output:

const e1: Expr<boolean> = add(i(2), i(4));
                          ^ Cannot assign `add(...)` to `e1` because number [1] is incompatible with boolean [2] in type argument `A` [3].

In the definition of evaluate, if we return a boolean where we expect a number:

mistake:

case 'Mul':
  return expr._eq(evaluate(expr.x) === evaluate(expr.y));

Flow output:

return expr._eq(evaluate(expr.x) === evaluate(expr.y));
                ^ Cannot call `expr._eq` with `evaluate(...) === evaluate(...)` bound to the first parameter because boolean [1] is incompatible with number [2].

If we do not use _eq:

mistake:

case 'Mul':
  return evaluate(expr.x) * evaluate(expr.y);

Flow output:

return evaluate(expr.x) * evaluate(expr.y);
       ^ Cannot return `evaluate(...) * evaluate(...)` because number [1] is incompatible with `A` [2].

A weakness of this encoding is that we must enforce by hand that _eq is always x => x.

The idea of using type equalities is taken from Approximating GADTs in PureScript. In PureScript the type system almost enforces that _eq is the identity (it could also be a non-terminating function). There is a thread on GitHub issues discussing the addition of GADTs to Flow.

Simple unit testing in Coq

Sat, 25 Jul 2015 00:00:00 +0000

Even if we can prove things in Coq, unit testing remains an extremely simple and powerful technique to verify what we write. Thanks to the dependent types, we can run unit tests in Coq at compile time by computing into the types. For example, in:

Definition test_pred : pred 5 = 4 :=
  eq_refl.

we check that the predecessor of 5 is 4 by saying that they are logically equal. The proof of the equality is its only constructor eq_refl. We force the type-checker of Coq to reduce both pred 5 and 4 to check that they are the same.

Usually we want to check many values, what we can do with a list:

Require Import Coq.Lists.List.

Import ListNotations.

Definition test_pred :
  List.map pred [0; 1; 2; 5] = [0; 0; 1; 4] :=
  eq_refl.

We map the pred function on the values 0, 1, 2, 5 and check the results.

The CUnit package

For functions with several parameters, the trick of the List.map function does not work well because of the currying. What need instead is a map over lists of tuples. I made the package CUnit to provide such a map. Install it with OPAM:

opam repo add coq-released https://coq.inria.fr/opam/released
opam install coq-cunit

Now we can test the plus function:

Require Import Coq.Lists.List.
Require Import CUnit.All.

Import ListNotations.

Definition test_plus : List.map_pair plus
  [(0, 0); (0, 3); (4, 0); (4, 3)] =
  [0; 3; 4; 7] :=
  eq_refl.

The complete list of maps in the package CUnit is the following:

List.map_pair {A B C} (f : A -> B -> C) (l : list (A * B)) : list C
List.map_triple {A B C D} (f : A -> B -> C -> D) (l : list (A * B * C)) : list D
List.map_quad {A B C D E} (f : A -> B -> C -> D -> E) (l : list (A * B * C * D)) : list E

Edit: this list of functions can be generalized to an arbitrary number of arguments. See the post Currying using Canonical Structures of Guillaume Allais.

Handle errors in Coq

Thu, 23 Jul 2015 00:00:00 +0000

Many programming languages handle errors with an exceptions mechanism. There are no exceptions in Coq, since this is a pure programming language. We mainly get two alternatives:

to extend Coq with an effect system for exceptions, implemented with monads or alike;
to use explicit sum types.

Even if the first option seems more powerful, from my experience an effect system is too heavy for the gains it brings compared the use of sum types with combinators. Sum types are just simple and ubiquitous. This is in fact the way errors are handled in Rust.

There are two basic sum types:

option A: either Some value or None for an error
A + E: either inl value or inr err for an error

The ErrorHandlers package

Since there are no error combinators in the standard library, I wrote the ErrorHandlers package:

opam repo add coq-released https://coq.inria.fr/opam/released
opam install -j4 coq-error-handlers

It provides the basic combinators bind, map and default. The bind sequences two computations with errors:

Require Import Coq.Lists.List.
Require Import ErrorHandlers.All.

Import ListNotations.

Compute
  Option.bind (List.hd_error [2; 4; 5]) (fun n =>
  Some (n + 1)).

prints Some 3.

The map is a particular case for when the second expression does not return errors:

Compute Option.map (List.hd_error [2; 4; 5]) (fun n => n + 1).

prints Some 3.

The default replaces an error with a default value:

Compute Option.default (Some 3) 0.
Compute Option.default None 0.

prints 3 and 0.

To summarize, here are the types of the combinators:

Option.bind : forall {A B}, option A -> (A -> option B) -> option B
Option.map : forall {A B}, option A -> (A -> B) -> option B
Option.default : forall {A}, option A -> A -> A
Sum.bind : forall {E A B}, A + E -> (A -> B + E) -> B + E
Sum.map : forall {E A B}, A + E -> (A -> B) -> B + E
Sum.default : forall {E A}, A + E -> A -> A

There are no notations to keep things simple and non-intrusive.

Launch of the Coq.io website

Tue, 21 Jul 2015 00:00:00 +0000

Coq.io is a library for writing and proving concurrent applications with inputs–outputs in Coq. In order to centralize the informations about it, I have setup a website on http://coq.io/. I have been lucky to get this domain name, since this gives a direct reference to the IO monad of Haskell, which popularized the idea of clean imperative programming in a functional language.

There is a Getting started page with some basic examples and an introduction to the technique of formal specification by use cases, and links to some reference documentation. The library is still evolving, with three upcoming improvements:

a type C.I.t for infinite (co-inductive) computations;
a type Trace.t for whose who want to separate the specifications from the proofs of use cases;
a Lwt.E effect to add arbitrary Lwt commands.

Implementation of promises for Coq

Mon, 16 Mar 2015 00:00:00 +0000

Last time, we presented two primitives Join and First to write and specify concurrent programs with Coq.io, using the concept of promises. We will explain how we implemented these primitives and give examples of concurrent programs.

Implementation

The promises are available in the package coq-io, starting from the version 2.1.0. This package symbolically describes the primitive Join and First. They must be implemented for each set of effects.

For example, in coq-io-system (which defines effects to interact with the system), we compile all the external calls and the computation primitives to Lwt in coq-io/src/Extraction.v:

Fixpoint eval {A : Type} (x : C.t System.effects A) : Lwt.t A.
  destruct x as [A x | command | A B x f | A B x y | A B x y].
  - exact (Lwt.ret x).
  - exact (eval_command command).
  - exact (Lwt.bind (eval _ x) (fun x => eval _ (f x))).
  - exact (Lwt.join (eval _ x) (eval _ y)).
  - exact (
      Lwt.bind (Lwt.first (eval _ x) (eval _ y)) (fun s =>
      Lwt.ret @@ Sum.to_coq s)).
Defined.

This code is written in proof mode, so that we do not care about the match/with parameters and compile with both Coq 8.4 and 8.5 patterns. The functions join and first are implemented in coq-io-system-ocaml/ioSystem.ml using Lwt primitives. The Lwt primitives needed some wrappers because their types are:

Lwt.join : unit Lwt.t list -> unit Lwt.t
Lwt.pick : 'a Lwt.t list -> 'a list Lwt.t

where we needed:

join : 'a Lwt.t -> 'b Lwt.t -> ('a * 'b) Lwt.t
first : 'a Lwt.t -> 'b Lwt.t -> ('a, 'b) Sum.t Lwt.t

Hello World

You can see a simple example of concurrent program in coq-hello-world:

Definition concurrent_hello_world (argv : list LString.t)
  : C.t System.effects unit :=
  let! _ : unit * unit := join
    (System.log (LString.s "Hello"))
    (System.log (LString.s "World")) in
  ret tt.

You can compile this program by replacing the line:

Definition main := Extraction.run hello_world.

with:

Definition main := Extraction.run concurrent_hello_world.

and following the instructions given in the README.md. It will display either:

Hello
World

or:

World
Hello

The specification of this program stays that it does exactly one thing: displaying concurrently Hello and World:

Definition concurrent_hello_world_ok (argv : list LString.t)
  : Run.t (concurrent_hello_world argv) tt.
  apply (Run.Let (Run.Join
    (Run.log_ok (LString.s "Hello"))
    (Run.log_ok (LString.s "World")))).
  apply Run.Ret.
Defined.

Larger example and drawbacks

In the branch #join of repos2web, we modified our website generator for OPAM repositories to read the packages descriptions concurrently. Our main modification is to use the Join operator in the recursive functions to make concurrent recursive calls:

Fixpoint get_packages (repository : LString.t) (packages : Packages.t)
  : C FullPackages.t :=
  match packages with
  | [] => ret []
  | package :: packages =>
    let! full_package_full_packages := join
      (get_package repository package)
      (get_packages repository packages) in
    let (full_package, full_packages) := full_package_full_packages in
    ret (full_package :: full_packages)
  end.

The specifications are updated similarly.

We tried to run this program on large generated repositories, to see if we gained performances. Unfortunately, after a couple of thousands of packages, we hit the limit of number of files we can open at the same time. We could have a finer control of the concurrency with, for example, a bounded pool of light-weight threads, or by handling the EMFILE exception (“too many open files”) to retry again later.

We feel that the specification of the Linux system API is quite complex, with many corner cases in practice (like this limit on the number of opened files). These corner cases are hard to be spotted by formal specifications, since the specification of Linux seems complex. Thus programming on top of Linux does not benefit as much as we could hope from formal specifications.

Next, we would like to investigate more the Xen API which seems cleaner, completely event-driven and available in OCaml thanks to the MirageOS project.

Concurrency with promises in Coq

Sat, 14 Mar 2015 00:00:00 +0000

We will present two primitives to write concurrent (and interactive) programs in Coq, using the concept of promises in the library Coq.io. We will also show how to formally specify programs written using promises.

Primitives for concurrency

To write an interactive application we quickly need a way to do non-blocking inputs–outputs operations. There are many approaches to do non-blocking operations or concurrency, for example:

blocking calls in system threads
a main event loop
callbacks in lightweight threads
promises
the actor model

We chose to use promises, in the style of the Lwt library for lightweight threads in OCaml. The promises can be implemented efficiently using lightweight threads, while being simpler to use than an event loop or callbacks. The actor model is another interesting approach which we will study later.

Sequential computations

We recall the definition of our interactive sequential computations (see the coq-io package):

Module C.
  Inductive t (E : Effects.t) : Type -> Type :=
  | Ret : forall {A : Type} (x : A), t E A
  | Call : forall (command : Effects.command E), t E (Effects.answer E command)
  | Let : forall {A B : Type}, t E A -> (A -> t E B) -> t E B.
End C.

where the effects are defined as:

Module Effects.
  Record t := New {
    command : Type;
    answer : command -> Type }.
End Effects.

The effects are a type of command and a type of answer, dependent on the values of the commands. A computation of type C.t E A is a computation returning a value of type A with the effects E. It can be of three forms:

Ret x, the pure value x
Call command, the call to a command
Let x f, the evaluation of x, followed by the evaluation of f applied to the result of x

The Let operator is also called the bind in the terminology of monads. The effects E typically represent external calls to the system. You can for example look at the API of the coq-io-system library, which provides basic calls to manipulates files and the terminal.

Join

We add the Join operator to the computations:

| Join : forall {A B : Type}, t E A -> t E B -> t E (A * B)

The program Join x y runs the two computations x and y in parallel and returns the couple of their results. Since the two computations are launched concurrently, blocking calls made in x will not block calls in y, and reciprocally. This is the main operator we will use to write concurrent programs.

Note that since our programs are pure, there are no shared states between x and y. We will see in a future post how to represent a shared state in a concurrent program in Coq.

First

The First operator is defined as:

| First : forall {A B : Type}, t E A -> t E B -> t E (A + B)

The program First x y runs the two computations x and y in parallel and returns the result of the first which terminated. The other may be canceled.

This operator is dangerous because one of our computations can get canceled. The First primitive is mainly there to implement timeouts. If we want to run a computation slow which may not terminate or may take too much time, we can combine this computation with a timeout by writing something like:

First slow (sleep 10)

to make sure the program terminates after 10 seconds (we suppose that sleep 10 is the computation which does nothing but terminating after 10 seconds).

Specification of promises

We specify our computations using use-cases described by runs:

Module Run.
  Inductive t : forall {E : Effects.t} {A : Type}, C.t E A -> A -> Type :=
  | Ret : forall {E A} (x : A), t (C.Ret (E := E) x) x
  | Call : forall E (command : Effects.command E) (answer : Effects.answer E command),
    t (C.Call E command) answer
  | Let : forall {E A B} {c_x : C.t E B} {x : B} {c_f : B -> C.t E A} {y : A},
    t c_x x -> t (c_f x) y -> t (C.Let c_x c_f) y.
End Run.

You can see an example of specification using runs in Formally verify a script in Coq. The main idea is that a universally quantified run can be viewed as the formal specification of a use-case. This kind of specification is verified just by typing, using lemma on equalities when the type-checker fails.

A run can be a run of the computation:

Ret x, the pure value x returned by the computation
Call command, an answer to this command
Let x f, a run of x and a run of f applied to the result of the run of x

We will extend our definition of runs with new cases for the primitives Join and First.

Join

We define the run of a Join by:

| Join : forall {E A B} {c_x : C.t E A} {x : A} {c_y : C.t E B} {y : B},
  t c_x x -> t c_y y -> t (C.Join c_x c_y) (x, y)

This means that a run of Join x y is a couple of runs for x and y. Equivalently, a specification of Join x y is a couple of specifications for x and for y.

A priori, the interactions of the threads x and y are not specified. This is up to the user to express these interactions in the specification, if there are some.

First

There are two ways to run a First:

| Left : forall {E A B} {c_x : C.t E A} {x : A} {c_y : C.t E B},
  t c_x x -> t (C.First c_x c_y) (inl x)
| Right : forall {E A B} {c_x : C.t E A} {c_y : C.t E B} {y : B},
  t c_y y -> t (C.First c_x c_y) (inr y)

A run of First x y is either a run of x (the Left case) or a run of y (the Right case). Equivalently, a specification of First x y is a specification of x or a specification of y.

We could ask: yes, but sometimes both x and y are actually executed! And if we choose the Left case for example, we should program x instead of First x y to start with. These are the same concerns we may have for the definition of the logical disjunction in Coq:

Inductive or (A B : Prop) : Prop :=
| or_introl : A -> A \/ B
| or_intror : B -> A \/ B

where "A \/ B" := (or A B) : type_scope.

and the reasons of these definitions are similar.

Next time

Next time we will see how to implement the primitives Join and First, to generate efficient and non-blocking interactive programs written in Coq.

Formally verify a script in Coq

Thu, 05 Mar 2015 00:00:00 +0000

Last time, in Write a script in Coq, we explained how to implement scripts in Coq using Coq.io with the example of repos2web, a website generator for OPAM repositories. We will see how to specify and prove correct this script.

There is now a newer OPAM website generator opam-website. See the results on coq.io/opam.

Unit testing, revisited

A common practice to check programs is to write unit tests. For each function, a test is written to execute it on some particular inputs, and to check that the results are what we expect. On more complex programs, we also need to simulate the inputs–outputs with the users, a database, the network, … To solve this problem, programmers invented solutions like the mock objects which are basically implementations of fake execution environments.

Unfortunately tests are not exhaustive since the set of program inputs is usually infinite. Methods like random testing can extend the range of tested configurations, but are always limited to a finite set of inputs.

We will explain how to write exhaustive tests in Coq by writing scenarios which formalize the notion of use cases. The completeness of the scenarios is given us for free, thanks to the strict type-system of Coq: in our settings, a scenario is correct if it is well-typed so that there is no need to run it on its (infinite) set of parameters.

To the best of our knowledge, Coq is the only language with formal verification of use cases.

Remark: some people are used to specify programs with pre/post-conditions or invariants, rather than by use cases. We believe that these approaches are pertinent for algorithms but not for interactive programs, because (from our experience) these specifications are less natural than the specifications by use cases. This seems counter-intuitive because use-cases do not cover all the execution paths. But we have to remember that:

the Coq type system protects us from bad behaviors in all execution paths,
there are often hypothesis on the environment, so all execution paths may not be interesting,
the quality of a specification depends on its clarity and its similarities with the human intuition.

Write the scenarios

We write our scenarios in src/Scenarios.v. There is at least one scenario per function, for the cases in which the environment has no bugs (no file system errors) and the repository architecture is well-formed. For example, for the function:

Definition get_packages (repository : LString.t) : C (option Packages.t) :=
  let! names := list_coq_files repository in
  match names with
  | None => ret None
  | Some names => get_packages_of_names repository names
  end.

we write the following scenario:

Definition get_packages_ok (repository : LString.t) (packages : Packages.t)
  : Run.t (get_packages repository) (Some packages).
  apply (Let (list_coq_files_ok _ (Packages.to_folders packages))).
  apply (get_packages_of_names_ok repository packages).
Defined.

What does this mean?

This scenario is parametrized by any repository folder names and any lists of OPAM packages. It runs the function get_packages on repository in a “valid” environment and ensures that the result is Some packages, meaning that the repository was successfully parsed.

The get_package function starts by a let! to call list_coq_files. We first reuse the scenario list_coq_files_ok. This describes a use case in which a list of folders starting by coq- is correctly listed:

apply (Let (list_coq_files_ok _ (Packages.to_folders packages))).

Since this scenario states that the result is Some files:

Definition list_coq_files_ok (folder : LString.t) (files : list Name.t)
  : Run.t (list_coq_files folder) (Some files).

we know that the function get_packages will call the function get_packages_of_names. We then apply its scenario:

apply (get_packages_of_names_ok repository packages).

Coq tells us there nothing more to do, so we conclude by:

Defined.

The Coq type-checker accepts our scenario which means it is valid: we do not need to run it on every (repository, packages) tuples. Even if we used the tactical mode to define the scenario, we did not write any proofs: the scenario is valid by-construction. However, in some cases, proofs are required to help the type-checker with non-trivial equalities. See for example the list_coq_files_ok scenario. Over 13 scenarios, only 2 required proofs to help the type-checker.

What did we prove?

We proved that, for any list of OPAM packages, given the “right answers” from the file system, the function get_packages will terminate without errors and will return Some packages. The “right answers” are defined by giving the “right answers” to list_coq_files and then giving the “right answers” to get_packages_of_names.

Next time

We have seen how to formally verify an interactive program in Coq. Next time we will see how to optimize this program using concurrency.

Write a script in Coq

Wed, 04 Mar 2015 00:00:00 +0000

We will explain how to write scripts in Coq using the library Coq.io with the example of repos2web, a website generator. This generator parses an OPAM repository with Coq packages and generates an HTML page.

There is now a newer OPAM website generator opam-website. See the results on coq.io/opam.

Get started

Install the coq-io-system package with OPAM to enable the system effects. See Use OPAM for Coq to configure OPAM for Coq.

opam repo add coq-released https://coq.inria.fr/opam/released
opam install coq-io-system

Create an empty Coq project by adding the following files in a fresh directory:

configure.sh, the configure script:

#!/bin/sh

coq_makefile -f Make -o Makefile

Make, the coq_makefile project file:
```
-R src Repos2Web

src/Main.v
```

src/Main.v, the main source file:

Require Import Coq.Lists.List.
Require Import Io.All.
Require Import Io.System.All.
Require Import ListString.All.

Import ListNotations.
Import C.Notations.

(** The main function. *)
Definition main (argv : list LString.t) : C.t System.effects unit :=
  System.log (LString.s "test").

(** The extracted program. *)
Definition repos2web := Extraction.run main.
Extraction "extraction/repos2web" repos2web.

extraction/Makefile, the Makefile for the extracted program:

build:
    ocamlbuild repos2web.native -use-ocamlfind -package io-system

clean:
    ocamlbuild -clean

Compile your Coq code to OCaml:

./configure.sh
make

Compile and run the generated OCaml:

cd extraction/
make
./repos2web.native

This should print you the message test on the terminal!

Parse the OPAM repository

To write our script we need to understand the basis of how OPAM for Coq repositories are organized (for example in opam-coq-archive). All the packages are in the packages folders. There is one folder per package name, all prefixed by coq- because we are in the Coq namespace. In each package folder, there is one folder per version of the package with three files descr, opam and url to describe the package.

packages/
  coq-list-string/
    coq-list-string.1.0.0/
      descr
      opam
      url
    coq-list-string.2.0.0/
      ...
  ...

We define the data type of an OPAM repository in src/Model.v. In a first pass, we will generate an element of type Packages.t. This is a list of packages described by a name and a list of versions. In a second pass, we will generate an element of type FullPackages.t, by adding the description of each version and by computing each latest version using the (complex) Debian ordering.

First pass

The first pass is described in src/Main.v in the Basic module. The function list_coq_files lists the files/folders which are starting with the coq- prefix in a given folder:

Definition list_coq_files (folder : LString.t) : C (option (list Name.t)) :=
  let! folders := System.list_files folder in
  match folders with
  | None =>
    do! log (LString.s "The folder " ++ folder ++ LString.s " cannot be listed.") in
    ret None
  | Some folders => ret (Some (Name.of_strings folders))
  end.

Let us precise the return type C (option (list Name.t)). We defined C as:

Definition C := C.t System.effects.

for convenience. This means than C is the type of computations doing interactions with the system. We need to use this special type because Coq is a purely functional language: without using the type C, functions cannot do inputs–outputs.

The type C is parametrized by option (list Name.t), the result type of the function. Thus, the result of list_coq_files can be either:

None in case of error,
some list of names in case of success.

As described in Tutorial: a Hello World in Coq, we use the let! operator to combine computations and the ret operator to return a pure value. We interact with the system by calling the following functions:

list_files : LString.t -> C (option (list LString.t)): list the content of a folder
log : LString.t -> C unit: print a message on the terminal

The complete list of system functions is available on system API.

We continue by defining more functions and conclude with:

Definition get_packages (repository : LString.t) : C (option Packages.t) :=
  let! names := list_coq_files repository in
  match names with
  | None => ret None
  | Some names => get_packages_of_names repository names
  end.

to get the list of packages in a repository folder (or None in case of error).

Second pass

The second pass follows the same structure as the first one. The main trick is the function:

(** Return the latest version, using Debian `dpkg` for comparison. *)
Definition max_version (version1 version2 : Version.t) : C (option Version.t) :=
  ...

which uses the dpkg command line tool to compare two versions numbers according to the Debian ordering. If you want to test it, the dpkg tool should be available on most Linux distribution, even on those which are not based on Debian.

Render the HTML

We define the HTML rendering in src/View.v. The last function is:

Definition index (packages : FullPackages.t) : LString.t :=
  header ++ title packages ++ table packages ++ footer.

which pretty-prints a list of packages to HTML. This function is pure (no inputs–outputs), because the return type is not C of something but LString.t. There is nothing special about the pretty-printing, and we generate the page using the Bootstrap CSS framework to get a nice rendering.

The final main function in src/Main.v combines the parsing and the rendering to write the output file in html/index.html:

Definition main (argv : list LString.t) : C unit :=
  match argv with
  | [_; repository] =>
    let repository := repository ++ LString.s "/packages" in
    let! packages := Basic.get_packages repository in
    match packages with
    | None => log (LString.s "The packages cannot be listed.")
    | Some packages =>
      let! full_packages := Full.get_packages repository packages in
      let index_content := View.index full_packages in
      let index_name := LString.s "html/index.html" in
      let! is_success := System.write_file index_name index_content in
      if is_success then
        log (index_name ++ LString.s " generated.")
      else
        log (LString.s "Cannot generate " ++ index_name ++ LString.s ".")
    end
  | _ => log (LString.s "Exactly one argument expected (the repository folder).")
  end.

We use the list of command line arguments argv to get the folder in which the OPAM repository is stored. You can add a Coq-ish theme downloading this Bootstrap CSS:

curl -L https://github.com/clarus/coq-red-css/releases/download/coq-blog.1.0.2/style.min.css >html/style.min.css

Next time

We have seen how to write a script in Coq doing file manipulations. Next time we will see how to specify this script and prove it correct, using a reasoning by use cases.

Tutorial: a Hello World in Coq

Fri, 20 Feb 2015 00:00:00 +0000

We will present the classic Hello World program in Coq. We will explain how to compile, run, and certify interactive programs in Coq. We will use the library Coq.io.

The Hello World program exists in almost every languages, including in White Space. In Coq this is more complicated because the language is purely functional. This means that no effects can be done, in particular no inputs-outputs. This constraint is there to preserve the logical consistency of the system. However, we can still encode inputs-outputs by defining a monad. This technique was popularized by the Haskell programming language.

Hello World

Using OPAM for Coq, install the package coq-io-system:

opam repo add coq-released https://coq.inria.fr/opam/released
opam install coq-io-system

You can now write the Hello World:

Require Import Coq.Lists.List.
Require Import Io.All.
Require Import Io.System.All.
Require Import ListString.All.

Import ListNotations.
Import C.Notations.

(** The classic Hello World program. *)
Definition hello_world (argv : list LString.t) : C.t System.effect unit :=
  System.log (LString.s "Hello world!").

We load some libraries and write the hello_world program by calling the System.log function. The return type is C.t System.effect unit, which means this is a impure computation with System effects and returning a value of type unit. The command line arguments are given in the list of strings argv, but not used here.

To compile the hello_world program we add:

Definition main := Extraction.launch hello_world.
Extraction "extraction/main" main.

to generate an OCaml file main.ml. We compile and run this file:

ocamlbuild main.native -use-ocamlfind -package io-system
./main.native

This should display Hello world! on the terminal.

Specification

The specification of this program is very straightforward: the program only prints “Hello world!” and quits (here the specification is as long as the program itself, but this is not always the case). A simple way to write this specification is to describe an environment of the program which reacts to a single event: the printing of the message “Hello world!” on the terminal. You can express this environment as a program:

(** The Hello World program only says hello. *)
Definition hello_world_ok (argv : list LString.t) : Run.t (hello_world argv) tt.
  apply (Run.log_ok (LString.s "Hello world!")).
Defined.

The specification hello_world_ok is of type Run.t (hello_world argv) tt: this runs the program hello_world on an argument argv and returns the result tt. We just apply the function Run.log_ok of the coq-io-system library which exactly describes an environment reacting to a single printing event.

This specification needs no proofs because it is valid by construction. We do not need any SMT solver, model checker or manual proof. The specification is valid because it is well-typed. Of course this example is very simple, so we will see a slightly more complex one.

What is your name?

This program asks for your name and replies with your name:

(** Ask for the user name and answer hello. *)
Definition your_name (argv : list LString.t) : C.t System.effect unit :=
  do! System.log (LString.s "What is your name?") in
  let! name := System.read_line in (* Ask the name. *)
  match name with
  | None => ret tt (* In case of error do nothing. *)
  | Some name => System.log (LString.s "Hello " ++ name ++ LString.s "!")
  end.

We see here how to compose impure computations in sequence with the do! and let! keywords. The construct:

let! x := e1 in e2

executes e1, assigns the result to x and then executes e2. The do! is a syntactic sugar for a let! with an empty variable name. We use the System.read_line function which gets a new line on the standard input. If the read_line operation fails we returns the pure value tt using the ret operator, else we print the user name on the terminal.

You can run this program as before by compilation to OCaml.

Specification

We have two use cases for the your_name program:

when the user enters a name,
when the standard input is broken.

For the first use case:

(** The `your_name` program answers something when you give your name. *)
Definition your_name_ok (argv : list LString.t) (name : LString.t)
  : Run.t (your_name argv) tt.
  apply (Run.Let (Run.log_ok _)).
  apply (Run.Let (Run.read_line_ok name)).
  apply (Run.log_ok _).
Defined.

The specification is parametrized by a name which could be any string. The environment does exactly three steps:

display something on the terminal (the underscore _ means any value)
answer name to the event read_line
display something on the terminal

The Run.Let command composes two steps. For a failing standard input:

(** The `your_name` program does nothing more in case of error on stdin. *)
Definition your_name_error (argv : list LString.t) : Run.t (your_name argv) tt.
  apply (Run.Let (Run.log_ok _)).
  apply (Run.Let Run.read_line_error).
  apply Run.Ret.
Defined.

we also give three steps:

display something on the terminal
answer by an error to the event read_line
terminate (the command Run.Ret)

Again, we do not need to prove anything because the specifications are correct by construction.

Next time we will continue with more tutorials, to help you build and certify realistic interactive applications in Coq.

A bench system for the Coq packages

Tue, 17 Feb 2015 00:00:00 +0000

We will present the bench system for the Coq packages.

OPAM is the package manager for Coq. The number of packages is growing, so we needed a bench system to automatically check that all packages are compiling. The bench system will help both:

packages developers, to check that their programs are compiling with correct dependency constraints;
Coq developers, to monitor the changes breaking compatibility.

Use the bench

The results of the bench are available on coq-bench.github.io, using the two installation strategies clean and tree. The results are presented in a colored table with the installation times for valid packages. The best column contains the best score obtained for each package.

We check:

that packages are well-formed, using our lint checker
the installation of dependencies (with a timeout of 5 minutes)
the installation of the package (with a timeout of 30 minutes)
the removing of the package (by comparing the list of files before installation and after removing)

We record the duration of each operation and compute the installation size.

Because your dependencies may evolve, it is good practice to regularly check the bench results for your packages. The clean strategy installs each package in a clean environment whereas the tree strategy installs as many packages as possible before to remove incompatible ones. In practice, the tree strategy yields more errors because packages are tested in an environment polluted by many other packages.

Architecture

The bench system is hosted on GitHub in the organization coq-bench. There are four projects:

run: run the benchmarks
database: the backup of the benchmarks
make-html: generate the web pages
coq-bench.github.io: the website itself

run

This program runs the benchmarks and is written in Ruby. The entry-point is long_run.rb. For each bench a clean Docker image is generated from the parametrized Dockerfile.erb. Then OCaml, OPAM and Coq are installed, and each package is tested. The packages can be from the stable repository or both the stable and unstable repositories. The results are then saved into the database.

database

The database is in the CSV format. There is one file per bench and one row per package. The first row gives a legend for each of the 31 columns.

make-html

This program generates the static HTML pages from the CSV database and is written in Ruby. For example, to generate the pages of the clean results:

ruby make_html.rb ../database/clean html/clean

coq-bench.github.io

These are the static HTML pages of the bench website. GitHub provides us a nice and simple way to host web pages from a Git repository using GitHub Pages.

Strategies

There are many possible strategies with respect to the installation order of the packages. The installation order is important because OPAM installs different dependencies in different contexts.

We would like to optimize the installation order to reduce the total execution time of the bench, by always installing and testing the dependencies first, so that no packages are compiled twice. Unfortunately this is not possible. Here is a simple counter example. With the following list of packages:

A.1.0.0
A.2.0.0
B.1.0.0 depending on A (any versions)
C.1.0.0 depending on A.1.0.0 and B
C.2.0.0 depending on A.2.0.0 and B

we must compile B twice (once with A.1.0.0 and once with A.2.0.0) to test both C.1.0.0 and C.2.0.0.

We provide the two following strategies.

Clean

This is the simplest strategy. We install each package in a fresh environment. This is the most robust and reproducible strategy. But this is not really optimal for packages with big dependencies because they are always reinstalled from scratch.

Tree

This is a more complex strategy. We install as many packages as possible until all new packages are incompatible with the current environment. The main source of incompatibility is the fact that we cannot install two packages with the same name but different version numbers. Once we are blocked, we roll-back until new packages are installable.

This strategy is more clever but also more fragile. We use the branch mechanism of Git on the .opam folder to switch efficiently between OPAM states. At the end of the process, we obtain a tree of all the Git branches used to explore the packages space. For example, for the stable repository:

* b99f693 coq-concurrency-pluto.1.0.0
* a1ff2f1 coq-concurrency-system.1.0.0
* 27c7b93 coq-moment.1.0.0
* d950f53 coq-list-string.2.0.0
| * 4817264 coq-flocq.2.2.0
| | * 3d4105d coq-flocq.2.3.0
| |/  
| | * 544de40 coq-concurrency-proxy.1.0.0
| | * 9a1989e coq-coqeal:refinements.0.9.1
| | * 0bfd44f coq-fpmods.0.2.0
| | * bda2af7 coq-coqeal:theory.0.9.1
| | * 27aa320 coq-plouffe.1.0.0
| | * 35961d5 coq-coquelicot.2.0.1
| | * 89db498 coq-error-handlers.1.0.0
| | * aa85f8c coq-flocq.2.4.0
| |/  
| * 48f33a4 coq-iterable.1.0.0
| * 0a48735 coq-function-ninjas.1.0.0
| * e2980d1 coq-list-plus.1.0.0
| * 4122f1a coq-list-string.1.0.0
|/  
* 89705ad coq-math-classes.1.0.2
* 5d3ec5d coq-math-comp.1.5.0
* 470eefb coq-ssreflect.1.5.0
* b0205c8 Initial files.

Related work

The OPAM for OCaml community did some work to obtain a bench system too. There are:

OPAM Weather Service: do not install the packages, only check the dependency constraints
OPAM Bulk: a future bench system
OCamlot: a bench system (abandoned?)

A blog engine written and proven in Coq

Fri, 16 Jan 2015 00:00:00 +0000

I present ChickBlog (sources on GitHub), a blog engine written and proven in Coq.

This is a demo blog engine where a user can login (no passwords), add, edit or delete posts. The code is written mostly in Coq, compiled to OCaml and linked to the CoHTTP library to handle the HTTP protocol.

The aim of this project is to demonstrate that applications with I/Os can be written and specified naturally using the (new) concept of symbolic simulations in Coq.

Run

Get the sources:

git clone https://github.com/clarus/coq-chick-blog.git
cd coq-chick-blog/

Add the Coq repositories with OPAM:

opam repo add coq-released https://coq.inria.fr/opam/released

Install the dependencies:

opam install --jobs=4 coq-list-string coq-error-handlers coq-function-ninjas coq-moment
opam install --jobs=4 lwt cohttp

Download the CSS:

curl -L https://github.com/clarus/coq-red-css/releases/download/coq-blog.1.0.2/style.min.css >extraction/static/style.min.css

Compile:

./configure.sh && make
cd extraction/
make

Run on localhost:8008:

./chickBlog.native

Dockerfile

A Dockerfile is provided to run ChickBlog in an isolated environment using Docker:

docker build --tag=chick-blog .
docker run -ti -p 8008:8008 chick-blog

Specification

The blog is defined in Main.v as the function:

Definition server (path : Path.t) (cookies : Cookies.t) : C.t Response.t.

It handles an HTTP request and generate an answer using system calls to the file system. The type C.t A represents a computation doing I/O operations:

Inductive t (A : Type) : Type :=
| Ret : forall (x : A), t A
| Call : forall (command : Command.t), (Command.answer command -> t A) -> t A.

A computation can either:

return a pure value of type A
call an external command and wait for its result

The purity of Coq ensures that each request is answered exactly once in finite time. We specify the behavior of the server in Spec.v.

Scenarios

A scenario is a set of runs of the server. A type-checking scenario shows that the server behaves as expected in a certain use case. For example, we check that when we create, edit and view a post we get the same result as what we entered. You can think of a scenario as a unit test with universally quantified variables.

Here is a simple check of the execution of the index page:

(** The index page when the list of posts is available. *)
Definition index_ok (cookies : Cookies.t) (post_headers : list Post.Header.t)
  : Run.t (Main.server Path.Index cookies).
  (* The handler asks the list of available posts. We return `post_headers`. *)
  apply (Call (Command.ListPosts _ ) (Some post_headers)).
  (* The handler terminates without other system calls. *)
  apply (Ret (Response.Index (Cookies.is_logged cookies) post_headers)).
Defined.

Given any cookies and post_headers, we execute the server handler on the page Request.Path.Index. The handler does exactly one system call, to which we answer Some post_headers, playing the role of the system. The final response of the server is then Response.Public.Index post_headers. Note that we do not need to execute index_ok on every instances of cookies and post_headers: since the type-system of Coq is supposed sound, it is enough to type-check index_ok.

Privacy

We check that, for any runs of a program, an unauthenticated user cannot access private pages (like edit) or modify the file system with system calls.

More comments on Hacker News, Reddit and Lobsters.

Checking concurrent programs with symbolic simulations

Thu, 18 Dec 2014 00:00:00 +0000

Concurrent programs with inputs/outputs are hard to test: they are non-deterministic and interact with the outside world. They are even harder to formally specify completely, and prove correct. We present (what we believe to be) a novel approach to check such programs doing symbolic simulations in Coq.

Symbolic simulations are like deterministic simulations one concrete data, using symbolic values to run and check the results of a full set of simulations. Here is a good talk about testing real systems by simulation: Testing Distributed Systems with Deterministic Simulation. We use the Coq’s pure programming language Gallina to describe the behavior of a program’s environment, which can include the user, the operating system, other connected computers, … The environment is responsible for two things:

feeding data to the program
checking that its answers verify some properties

We hope this approach will provide a good compromise between full specifications and testing on single data instances. We will define a simple concurrent calculus and give some examples.

All the following code extracts are in Coq and available on coq-concurrency/system#simulation-callbacks.

Calculus with handlers

To allow simpler reasoning, we want our calculus to be somehow “deterministic”. A first way is to remove shared mutable variables. Then the only source of non-determinism is the order of the input events. Having shared mutable states is often useful, typically to implement a data storage. Still, we will try to go as far as possible without mutable states.

An second way to reduce non-determinism is to restrict how we are waiting for events and doing threads. We define a calculus with only asynchronous calls and forks (without joins):

Inductive t : Type :=
| Ret : t
| Par : t -> t -> t
| Send : forall (command : Command.t), Command.request command ->
  (Command.answer command -> t) -> t.

A computation can do three things:

Ret: do nothing
Par c1 c2: start c1 and c2 in parallel
Send command request (fun answer => c): emit a request request of kind command with a handler for the answer

This is the classical HelloWorld:

Definition hello_world : C.t :=
  do! Command.Write @ LString.s "Hello world!" in
  C.Ret.

We use the notation do! command @ request in e for Send command request (fun _ => e).

Here is a simple echo program repeating one user input:

Definition echo : C.t :=
  let! message := Command.Read @ tt in
  do! Command.Write @ message in
  C.Ret.

The let! is like the do! but naming the argument of the handler.

These examples are sequential programs. Note that in practice they may not terminate, if the operating system never answers to the requests. There can be at most one answer per request. We use a fixpoint and the Par operator to handle several requests in parallel:

Fixpoint echo_par (fuel : nat) : C.t :=
  match fuel with
  | O => C.Ret
  | S fuel => C.Par echo (echo_par fuel)
  end.

This program concurrently waits for fuel user inputs, prints them and stops.

Simulations

A simulation, or a run, is a co-program over a concurrent and interactive program. It answers to the requests of the program, playing the role of the environment. A simulation is defined by induction over the program’s structure. This has two advantages:

by construction, a simulation must give exactly one answer per request
you can construct the simulation following the structure of the program

The type of a simulation is:

Inductive t : C.t -> Type :=
| Ret : t C.Ret
| Par : forall {c1 c2 : C.t}, t c1 -> t c2 -> t (C.Par c1 c2)
| Send : forall (command : Command.t) (request : Command.request command)
  (answer : Command.answer command) {handler : Command.answer command -> C.t},
  t (handler answer) -> t (C.Send command request handler).

For convenience, we use the tactic mode of Coq to build simulations. Doing so, we get a kind of interactive and symbolic debugger for our programs. This helps writing meaningful simulations. Here is the simulation of HelloWorld:

Definition hello_world_run : Run.t hello_world.
  apply (Run.Send Command.Write (LString.s "Hello world!") tt).
  exact Run.Ret.
Defined.

This simulation checks that the program hello_world does exactly one thing: sending the message "Hello world!". For the echo of one message:

Definition run_echo (message : LString.t) : Run.t echo.
  apply (Run.Send Command.Read tt message).
  apply (Run.Send Command.Write message tt).
  exact Run.Ret.
Defined.

We check that, for any message entered by the user, the program will only print this message. Given a list of messages, we can construct a set of simulations for the concurrent echo:

Fixpoint run_echo_par (messages : list LString.t)
  : Run.t (echo_par (List.length messages)).
  destruct messages as [|message messages].
  - exact Run.Ret.
  - apply Run.Par.
    * exact (run_echo message).
    * exact (run_echo_par messages).
Defined.

This simulation is recursive to follow the shape of the simulated program. It reuses the simulation run_echo of echo. The simulation is defined for any order of interleaving of the message events.

Time server

In the file Simulation.v we give an example of a simple time server. The clients can connect and get the current time of the server. Unlike for the previous examples, we do not cover all possible runs. Instead we give two sets of simulations:

a first one where the server socket cannot be bound
a second one where both the server and clients sockets never return an error

We do not cover all the cases, for example the case of a client socket which cannot be written to. We believe this is both a weakness and a strength of this approach. Contrary to a full specification, not all the execution paths are tested. But simulations are simple to write, while covering more cases than traditional tests.

Future work

We want to extend this method to check more complex programs, like a database or a chat-server. For that we should first extend the expressiveness of the calculus, and so of the simulations.

We also want to relate this method to the specifications plus proofs approach. A first way could be to have simulations which by construction cover all the execution paths. An other way could be to express properties over simulations to enforce a specification over any simulations.

Pluto: a first concurrent web server in Gallina

Thu, 04 Dec 2014 00:00:00 +0000

Pluto is, to our knowledge, the first concurrent web server written in Gallina, the functional language of Coq.

It is a research project which aims to apply the pure and dependently typed Coq language to system programming, with inputs/outputs and fine grained concurrency in mind. This kind of programming is particularly error-prone and hard to test, due to non-determinism and interactions with the external world. Moreover, such programs (like servers and databases) often manipulate critical data. We try to develop new programming techniques with an extremist and purely functional approach, in the hope to lead to safer systems.

For now Pluto can serve static websites, using event-based I/Os and lightweight threads to handle concurrent requests.

Use

The simplest way to install Pluto is to use OPAM for Coq. See this tutorial for more informations. Add the stable and unstable repositories:

opam repo add coq-released https://coq.inria.fr/opam/released
opam repo add coq-extra-dev https://coq.inria.fr/opam/extra-dev

Install Pluto:

opam install --jobs=4 coq-concurrency-pluto

Run it on some html/ folder:

pluto.native 8000 html/

Your website is now available on localhost:8000.

Architecture

Coq is a pure language so it cannot directly express concurrency and I/Os. For that we use a Domain Specific Language (DSL) with new primitive constructs to describe impure computations. The architecture is implemented in the coq-concurrency/system project.

Operators

The Read and Write commands read or update atomically global references (shared by all the threads). Ret lifts a pure Coq expression, Bind sequences two computations. The Send constructor does an asynchronous call to the OS. It uses a handler with its own private memory (a lightweight thread), called each time an answer is sent to the request. The Exit command halts the program and stops all pending handlers.

We decided to use fully asynchronous I/Os with lightweight threads for two reasons:

it is generally considered more efficient than the synchronous system-calls plus system-threads model (see the evolution from the Apache 1 multi-threaded server to mono-threaded event-driven systems like Node.js)
it corresponds more to what computers intrinsically are: the most primitive communication facilities on microprocessors are the OUT instruction and the interruption mechanism. The Direct Memory Access is a fastest solution in practice, but also relies on these primitives. Finally, this corresponds to the Xen API design, in the hope that some day Coq could be ported as an unikernel like OCaml with MirageOS.

Implementation

The implementation of this DSL is two folds. In Coq, a run function gives an executable semantics of the computations. The existence of an executable semantics is an improvement over other works which only give unrealized axioms for I/Os effects (for example in Haskell or in Idris, see IO.idr).

We also compile Coq programs to OCaml using a customized version of the extraction mechanism of Coq. The impure operators are compiled to impure OCaml operators realizing the effects, like sending messages to the OS.

The impure effects can be classified into three categories:

memory
exit
asynchronous calls

The memory and exit effects are implemented, both in Coq and OCaml, by the monadic transformations of the state and exception monads (see monadic transformations).

In Coq, the asynchronous calls are represented by a monad reader and a monad writer. The system-calls are typed, and to each request type corresponds one answer type. The handlers are stored into a heap and must have a type compatible with their request. They have their own private memory (implemented as a state monad), and can be called an unbounded number of times (for example, with a web server, the socket listener will get as many inputs as connecting clients). A handler can also disconnect itself to be garbage collected.

In OCaml, the handlers are stored in the heap extracted from the Coq implementation. Communication with the OS occurs through a unique bidirectional pipe. The Send method writes a message on the pipe. A single loop listens synchronously to the pipe, and dispatches the events to the handlers. All messages are serialized into strings. At the other end of the pipe sits a proxy. The proxy parses the messages and translates them into real system-calls. It is implemented in OCaml using Lwt. Note that Lwt is not used as a lightweight threads library, but as an asynchronous API to Unix. For a more technical discussion about asynchronous system-calls in Unix, you can read this paper of Kerneis and Chroboczek.

Implementation architecture

Correction

There is no mechanism to prove properties about the effects yet (I/Os, shared memory, …). However it is possible to certify the functional part of the server, or any interactive Coq application based on our runtime, using standard techniques in Coq (see for example the Program extension of Matthieu Sozeau).

We can also question the correctness of the compilation to OCaml, or whether the run function in Coq is faithful to the extracted code. We have no formal proof, but we designed the system with correctness in mind. In particular, we designed our DSL with a minimal “attack surface”. The memory, the lightweight threads, the exit effect are compiled by monadic transformation in Coq and then using the standard extraction mechanism. For I/Os, there is no abstract World type which could lead to duplication in Coq. We just use a monad reader and monad writer, and messages are sent or read into a pipe. On the long term, we could dream of a formally proven Coq compiler and adapt it to our customized compilation of read/write effects.

Code extracts

This is the main function of the server, in pluto/Pluto.v:

Definition program (argv : list LString.t) : C.t [] unit :=
  match argv with
  | [_; port; website_dir] =>
    match LString.to_N 10 port with
    | None => print_usage tt
    | Some port_number =>
      Time.get (fun time =>
      let time := Moment.Print.rfc1123 @@ Moment.of_epoch @@ Z.of_N time in
      let welcome_message := LString.s "Pluto starting on " ++ website_dir ++
        LString.s ", port " ++ port ++
        LString.s ", on " ++ time ++ LString.s "." in
      Log.write welcome_message (fun _ =>
      ServerSocket.bind port_number (fun client =>
        match client with
        | None =>
          Log.write (LString.s "Server socket failed.") (fun _ => C.Exit tt)
        | Some client => handle_client website_dir client
        end)))
    end
  | _ => print_usage tt
  end.

The program is parametrized by the list of the command-line arguments. The return type is C.t [] unit, the type of computations returning unit with an empty shared memory ([] means that the list of memory cells is empty).

We first check that there are two arguments, the first one being an integer (the port number). Else we print a usage message and exit. Then we request the current time to log it. The definition of Time.get is in system/StdLib.v:

(** Get the current time (the number of seconds since Unix epoch). *)
Definition get {sig : Signature.t} (handler : N -> C.t sig unit)
  : C.t sig unit :=
  C.Send Command.Time tt tt (fun _ time =>
    do! handler time in
    C.Ret None).

The function get is parametrized by a handler N -> C.t sig unit which is a computation receiving the time in seconds. The handler is called when the OS responds to the C.Send operator, calling the callback fun _ time => do! handler time in C.Ret None. This callback has no private memory (actually a private memory of type unit initialized to tt). The callback always returns None to disconnect itself after an answer (so that the handler is called at most once, even if the OS is bugged and responds several times to the Command.Time request).

We log the current time in RFC 1123 format with a welcome message and bind to the server socket. The handler is listening while there are new clients connecting, and runs the handle_client method for each. This program may never terminate, while we are writing pure Coq without explicit non-termination monad. The non-termination effect is provided by the monad reader, which is compiled to OCaml as an infinite loop listening to the system pipe.

Future work

We learn many things writing a realistic example of a web server in Coq, especially in the way of implementing side effects. We also shown that it is possible to use Coq as a programming language to write interactive and concurrent softwares.

Our main goal now is to extend our DSL of computations with a specification and a certification mechanism. We would like to write a specification of the non-purely functional part of our web server and prove its correctness, exploiting the unique ability of Coq to marry proofs and programs.

Note: Pluto is also the only planet discovered and undiscovered by the Americans. The New Horizons space probe should give us more insights about this mysterious object.

Why and how to write code compatible with many Coq versions

Wed, 03 Dec 2014 00:00:00 +0000

You should always write your code to make it compatible with at least two consecutive Coq versions, if you wish to have larger people adoption.

The pace of Coq releases is surprisingly slow for a project with that many users, unfortunately due to a lack of organization resources. However, the releases happen and usually introduce a lot of incompatibilities. At this point, users depending on your libraries may be forced to migrate because of other dependencies, or forced not to migrate. Playing nice with them means allowing them to have the choice.

More important, a lot of people prefer to use the development version of Coq because of the slow release cycle. So your code should at least support the latest stable release and the current development version.

Check your code

OPAM is the best way to test your code with different versions of Coq. You can read this introduction to learn more about how to use OPAM for Coq.

Let us say we want to test our project foo with the Coq versions 8.4.5 and dev. We create two installs of Coq in foo/opam.8.4.5 and foo/opam.dev. For the stable version:

cd foo/
mkdir opam.8.4.5 # we create the empty directory to prevent a bug of OPAM
opam init --root=opam.8.4.5
eval `opam config --root=opam.8.4.5 env`
opam install --jobs=4 coq.8.4.5

In an other terminal, for the unstable Coq:

mkdir opam.dev
opam init --root=opam.dev
eval `opam config --root=opam.dev env`
opam repo add coq-core-dev https://coq.inria.fr/opam/core-dev
opam install -j4 -v coq.dev

You have now a different version of Coq in each terminal, and can test your code for two versions. If you have an old computer, and may be afraid of having many Coq installations for each project, remember you can always use cache mechanisms like the one provided by Docker to save disk space.

We also provide a coq-bench website, where OPAM packages are tested for different versions of Coq. This is another simple way to check your code compatibility if you have a package.

Be clean and robust

This is obvious but this must be emphasized: be clean and robust. Most Coq features outside the kernel can be considered as experimental, or do not have a clear semantics. This includes in particular the tactic language LTac.

So try not to rely too much on advanced features, and make your proofs scripts robust (using explicitly named variables or bullets for example).

Preprocess

You can use preprocessing to solve breaking incompatibility changes. This helps to keep one code database, instead of splitting your developments with one branch per Coq version.

Some people use the CPP preprocessor, but it has a heavy syntax and is quite limited. Instead, I recommend to go for simpler and more powerful tools like ERB. Here is an example file Test.v:

Definition proj (n : {n : nat & n >= 2}) : nat :=
  match n with
  | existT n _ => n
  end.

This code will not work with coq.dev as you need one more argument in the match:

Definition proj (n : {n : nat & n >= 2}) : nat :=
  match n with
  | existT _ n _ => n
  end.

The solution is to make a Test.v.erb file, which will be preprocessed into Test.v:

Definition proj (n : {n : nat & n >= 2}) : nat :=
  match n with
  | existT <%= "_" unless version[0..2] == "8.4" %> n _ => n
  end.

We add a _ in the match, unless if the Coq version starts by 8.4. Other common constructs are:

<%= "bla" if version[0..2] == "8.4" %>
<%= version[0..2] == "8.4" ? "bla" : "bli" %>

To preprocess this Test.v.erb file, create a pp.rb file at the root of your directory:

# Preprocessor.
require 'erb'

# The version of Coq.
version = `coqc -v`.match(/version ([^(]*) \(/)[1]

Dir.glob("*.v.erb") do |file_name|
  renderer = ERB.new(File.read(file_name, encoding: "UTF-8"))
  output_name = file_name[0..-5]
  File.open(output_name, "w") do |file|
    file << renderer.result()
  end
  puts "#{file_name} -> #{output_name}"
end

The command ruby pp.rb will then compile all the files matching *.v.erb to *.v.

Edit from the comments: To integrate preprocessing with an IDE, you can use the ProofGeneral’s plugin of Clément Pit-Claudel. For other IDEs, the only solution is to edit the .v files in the IDE for one specific version of Coq, and do back-and-forths with the .v.erb files to add compatibility.

Make a Coq package

Tue, 25 Nov 2014 00:00:00 +0000

We will show you a typical workflow to create and publish a Coq package with OPAM. This will allow you to share your Coq developments in a simple way and gain visibility.

We assume you already know how to use OPAM to install Coq packages. If not, you can read this tutorial.

Create a project

Go on GitHub and make a new project, for example that-super-proof. Add a LICENSE file with your copyright if you want to make your package open-source (without a license a code is proprietary). I usually choose the MIT license, as one of the most permissive and popular:

The MIT License (MIT)

Copyright (c) <year> <copyright holders>

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.

Add a main file All.v:

Theorem two : 1 + 1 = 2.
  now admit.
Qed.

You can now commit your work.

The case of OCaml plugins

If your project is a Coq plugin (containing OCaml files), you can get inspiration from the Constructors project of Matthieu Sozeau. This is an example of a simple OCaml plugin, including the branches v8.4 and v8.5 for compatibility with the different versions of Coq.

Compile

We will use coq_makefile to generate a Makefile. Create a file Make:

-R . ThatSuperProof

All.v

and an executable file configure.sh:

#!/bin/sh

coq_makefile -f Make -o Makefile

To compile your project, run:

./configure.sh
make

coq_makefile is clever and also generates an install rule, among over things.

Publish

To publish a new version you need to make a release. In the GitHub page of your project, go to the releases section and add a new release named 1.0.0. People tend to use the SemVer convention for the version names, as MAJOR.MINOR.PATCH:

MAJOR: major changes
MINOR: minor changes
PATCH: bug fixes

We do a pull-request to add our new package (see pull-requests on GitHub if you need help). Fork the OPAM Coq repository and add a folder coq-that-super-proof/coq-that-super-proof.dev in released/packages/. Package names must start with the coq- prefix.

A package is described by three files:

descr
```
An arithmetic library.
```

opam

opam-version: "1.2"
maintainer: "me@myself.ninja"
homepage: "https://github.com/myself/that-super-proof"
dev-repo: "https://github.com/myself/that-super-proof.git"
bug-reports: "https://github.com/myself/that-super-proof/issues"
authors: ["Me Myself"]
license: "MIT"
build: [
  ["./configure.sh"]
  [make "-j%{jobs}%"]
]
install: [
  [make "install"]
]
remove: ["rm" "-R" "%{lib}%/coq/user-contrib/ThatSuperProof"]
depends: [
  "coq" {>= "8.4.5" & < "8.5~"}
]

The < "8.5~" is there to say that the Coq version must be lesser than 8.5.0, 8.5.1, … as well as 8.5~beta1, 8.5~beta2, …

url

http: "https://github.com/myself/that-super-proof/archive/1.0.0.tar.gz"
checksum: "da1da74c8f6c560b153ab8dc558cf29e"

The MD5 checksum is mandatory, and can be obtained with:

curl -L https://github.com/myself/that-super-proof/archive/1.0.0.tar.gz |md5sum

You can test your own fork of the OPAM Coq repository using opam repo add on the folder released of your fork. Then, issue a pull-request with your new package.

Use the bench

There is a bench system available on coq-bench.github.io. We test all the packages for each version of Coq. We host this service to help you to check that your packages compile for each platform, even development ones. Compatibility across Coq versions is not necessary but allows you to reach more users. You can specify the Coq versions you depend upon in the depends field of your opam files.

Use OPAM for Coq

Mon, 24 Nov 2014 00:00:00 +0000

OPAM is a package manager edited by OCamlPro. We will describe how to use it to handle Coq packages.

Install OPAM

Install OPAM by your preferred method. It is recommended to use the latest version (1.2.2 as of May 7, 2015), which can be installed from the sources:

curl -L https://github.com/ocaml/opam/releases/download/1.2.2/opam-full-1.2.2.tar.gz |tar -xz
cd opam-full-1.2.2
./configure && make lib-ext && make
sudo make install

By default the OPAM packages are installed in ~/.opam. You can also have many installation folders if you want many versions of Coq or packages. A practice I recommend is to have one installation folder per project or configuration. To configure OPAM in a fresh folder opam:

mkdir opam
opam init --root=opam # answer no to the question
eval `opam config env --root=opam` # run this command for each shell session

Remark: Some people also use the switch mechanism to handle many OPAM installations.

Add the repositories

To add the repository for the Coq packages:

opam repo add coq-released https://coq.inria.fr/opam/released

There is also a repository for the development versions. Use it at your own risks:

opam repo add coq-extra-dev https://coq.inria.fr/opam/extra-dev

To add the development versions of Coq:

opam repo add coq-core-dev https://coq.inria.fr/opam/core-dev

Install a package

The Coq packages are in the namespace coq-. To list all of them:

opam search coq-

To install a package:

opam install coq-io-hello-world

To specify the version you want to install:

opam install coq-io-hello-world.1.1.0

If the package is slow to install (for instance, Coq itself), use the -j option to speed it up and -v to see the progress:

opam install -j4 -v coq

Cybele

Thu, 02 May 2013 00:00:00 +0000

This post is a re-post from the now defunct blog of PPS. The date of this post is the same as the original post.

The proof by extraction is a new proof technique, combining advantages of the proof by reflection and the proof by untrusted OCaml oracles. The idea is to add effects to the Coq language, so mutable variables, non-termination and exceptions are allowed. The execution is made efficient by extraction to OCaml which can pre-compute complex values. The results are then post-checked in Coq thanks to our theory of simulable monads.

We provide Cybele, a Coq plugin to do proof by extraction. You can start looking at the Get started and Examples sections. It is based on an original idea of Yann Régis-Gianas, and we are developing it with the help of Lourdes del Carmen González Huesca, and Beta Ziliani.

From proof by reflection to proof by extraction

We consider the example of the equivalence decision between two terms given a list of known equivalences. Let us take a type T with ~ an equivalence relation and a list of hypothesis:

H_1 : e_{i_1} ~ e_{j_1}
…
H_n : e_{i_n} ~ e_{j_n}

Our goal is to prove that e_i ~ e_j using the reflexivity, symmetry and transitivity properties. On small instances we can obviously solve it by hand, or write a tactic to do it for us. We just need to apply the equivalence properties as many times as necessary. But on a bigger sample:

H_{1,2} : e_1 ~ e_2
…
H_{999,1000} : e_{999} ~ e_{1000}

a proof of e_1 ~ e_{1000} would consist of 998 applications of the transitivity rule. This is just huge. The solution of the proof by reflection technique is to replace a proof term by a computation. This computation has to be done by a proven correct decision procedure.

The union-find algorithm is an efficient way to solve the equivalence problem. Let us note hs the list of hypothesis indexes [(i_1, j_1), ..., (i_n, j_n)] and (i, j) the indexes of our goal e_i ~ e_j. Then a decision procedure in pseudo-code would look like:

decide (hs, (i, j)) : bool :=
  let a = ref [] in
  map (fun (i, j) -> union a i j) hs;
  let i2 = find a i in
  let j2 = find a j in
  i2 = j2

We start with an empty array a representing the fact that equivalence classes are a priori singleton sets. We merge them calling the union procedure on each hypothesis. If the representatives (i2, j2) of (i, j) are equal then the property e_i ~ e_j holds.

A nice way to show the soundness of decide is to add an invariant to the array a stating that if i and j are linked then e_i ~ e_j. This can be done elegantly in Coq, which natively supports mixed proofs and programs (see the Program construct). At the end we just return a proof of e_i ~ e_j if i2 equals j2. An harder thing is to encode the union-find in a purely functional way since it critically relies on a mutable array, and show the termination of the union and find procedures.

We decided not to do it, and instead introduce a monad M representing side-effects, non-termination and exceptions. We obtain a solution close to the pseudo-code:

Definition decide (known_eqs : equalities) (i j : T) : M (i ~ j).
  refine (
    let! a := tmp_ref s 0 nil in
    do! List.iter (unify a) known_eqs in
    let! Pi2 := find a i in
    let (i2, Hii2) := Pi2 in
    let! Pj2 := find a j in
    let (j2, Hjj2) := Pj2 in
    if eq_dec i2 j2 then
      ret _
    else
      error "decide: the terms are not equal").
  ... (* some proof term *)
Defined.

On line 3, let! is a notation for the bind operator. Line 9, we test the equality of i2 and j2. Line 10, ret _ means we are returning a proof, namely the proof that e_i ~ e_j. This proof is delayed until line 13, where it is made in proof mode. It uses the properties Hii2 and Hjj2 given by the invariant on a, stating that e_i ~ e_{i_2} and e_j ~ e_{j_2}.

This is very much in the style of the IO monad of Haskell. Ours provides the following primitives.

Memory

ref : forall i, T_i -> M (Ref.t T_i) (memory allocation)
read : Ref.t T -> M T
write : Ref.t T -> T -> M ()

Non-termination

fix : ((A -> B) -> A -> B) -> A -> B
dependent_fix : ((forall x : A, B) -> forall x : A, B) -> forall x : A, B

Exceptions

raise : string -> M T
try_with : (() -> M T) -> (string -> M T) -> M T

Printing

print : T -> M ()

Obviously, this monad cannot be run natively in Coq. There is no run function of type M A -> A or M A -> option A. This is due to the general fixpoint operators which cannot be encoded in Coq since its typing rules enforce termination. Plus we want to run it as efficiently as possible.

An hybrid back-end

To run our monad we combine the Coq and OCaml back-ends:

Compilation chain.

We use the extraction mechanism of Coq to get an equivalent program of our decision procedure in OCaml. All the monadic operators are replaced by native OCaml operators, since this language supports all the effects of our monad. We run it on a specific problem instance x. It may not return a result in case of uncaught exception or infinite loop. If the execution is successful, we extract what we call a prophecy. This value is a guide which helps Coq to evaluate the monad efficiently with an extended run function of type:

run : prophecy -> M A -> option A

For the non-termination it contains the numbers of steps needed to evaluate a monadic value. It can also contain some pre-computed values in OCaml to save computational time in Coq. We provide a general mechanism to pass results from OCaml to Coq in the prophecy with the system of input memory. When you allocate a reference, you can mark it as an “input”. If you do so, its final value after the OCaml run will be given as its initial value to Coq. Any value can be passed thought the prophecy as long as you can serialize it. It does not work for functions or proofs, but does for all common data-structures such as integers or lists.

Notice that if you do not save results in the prophecy, computations are made twice: once in OCaml, then post-checked in Coq with the run function. This is the main limitation of our system, but it could be solved with a proven correct extraction mechanism. We could directly trust the execution made in OCaml and import the result in Coq.

An hybrid programming model

We pretend that our programming model combines nicely safety and efficiency. Safety because of the strong type system of Coq and the ability to prove invariants on our programs. Efficiency because costly computations are delayed to OCaml. It supersedes what can be done with proof by reflection in pure Coq or with an OCaml plugin generating proof certificates. In a way, Cybele unifies these two techniques, and allow to combine both approach depending on the problem.

Trade-off efficiency vs correctness.

As future work we plan to add more monadic operators, especially for concurrency. It would also be great to have a trusted extraction mechanism for Coq.