Home / Learn

Release v0.4.0

5 Contracts and the verifier

Page 1 of 11

Billing code is where a small slip costs real money: a coupon that is worth more than the order, a refund that pays back more than was paid, a rate typed as 110 percent. Tests catch the cases someone thought of. In Una you write the rule itself into the function's header, as a contract, and the verifier proves before the program runs that the rule holds for every input. When it does not, the verifier shows you an input that breaks it. This chapter writes contracts for the billing step of a store, and shows how to read what the verifier says.

What you'll build

The billing step of a small store. It prices the two lines of an invoice, applies a coupon, pays from store credit first and the rest by card, and checks two refunds against what was paid:

Output
2 x LAMP-01 at 19.90: 39.80
1 x DESK-02 at 149.00: 149.00
subtotal 188.80, coupon -18.88, total 169.92
store credit 50.00, card 119.92
refund 39.80: paid back
refund 200.00: refused, only 169.92 was paid

You will learn to:

  • state what a function needs with requires, and what it promises with ensures;
  • read a counterexample, and turn it into a fix and an example;
  • make the rules of your data part of its type, with refined kinds and predicates;
  • list what the verifier proved with una obligations, and tell a refuted proof (U5001) from one the solver could not decide (U5002);
  • trace a contract back to the business rule it comes from, with requirement and una trace.

Download this chapter's packages: each step is a package under steps/, and the chapter's program is day-to-day/; run una check . and una run . in one.

Why it works this way

In most languages, the rules of a function live in comments, in checks that run with the code, and in tests. A comment can be wrong. A check that runs with the code stops the program in front of a customer. A test covers the inputs someone wrote down, and the bug is in another: a coupon worth more than a cheap order.

Una moves the rules into the header and proves them:

  1. A contract is part of the header. requires states what must hold of the arguments, and ensures what holds of the result. A reader learns what a function does from its header alone.
  2. The verifier proves every contract, for every input. una check turns each rule into a question for the solver Z3, at the version verification.lock pins. A rule that fails for some input is refuted, and the diagnostic shows that input: a counterexample.
  3. Nothing unproven passes. When the solver cannot decide a question, the result is an error too, never a silent pass. A program that checks holds no value that breaks its contracts, and its contracts cost nothing when it runs. The exceptions are visible in the code: a test that runs with the program, checked (chapter 7), and the contracts of the standard library, which are trusted, not proven.

The price: you state your rules in a small language the solver understands, and sometimes add a guard to give it a fact. In return, the checker finds the input that breaks a rule before a customer does.

Key idea

A contract is a rule the verifier proves for every input before the program runs. When it cannot prove the rule, it does not pass the program: it shows an input that breaks the rule, or says that it cannot decide.

View the Markdown

Next:5.1 Preconditions: requires