Home / Learn / 13 Limits on authority
13.3 Locking a contract: [contracts]
Page 4 of 9
13.3.1 What a locked contract is
When a store signs an agreement with a courier, each side keeps a copy. If someone later edits the agreement on one side, the copies disagree, and the change is noticed. A locked contract is such a copy for one function. The function's header says what it may do; una.toml keeps a copy of that, under [contracts]; and the checker fails when the header allows more than the copy.
13.3.2 Why lock a header
A header is code, and an edit to the code can change it. Here is a sale function whose header and body both lost their condition in the same edit: the header no longer says "never on a dry run", and the body no longer checks dry_run.
--- a/src/store/sale.una
+++ b/src/store/sale.una
@@ -8,7 +8,6 @@
pub apply_sale(sku: Text, cents: Int, percent: Int, dry_run: Bool) -> Int
- uses @prices: PriceList[set_price where not dry_run]
+ uses @prices: PriceList[set_price]
=
let sale = cents - cents * percent / 100
- if not dry_run
- @prices.set_price(sku, cents: sale)
+ @prices.set_price(sku, cents: sale)
saleThis package has no [contracts] table yet: it is the situation a lock prevents. The body keeps its header, so the package checks clean. una run . prints:
set DESK-02 to 19920
a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791The first line is a price change during a dry run, which the doc comment still says cannot happen. The verifier proved that the body keeps its header, but the header itself changed, and no rule said it should not. A reviewer must notice that a line of the header disappeared, in a change that may touch many files.
Locking moves the decision out of the code. With the condition copied into una.toml, the header can lose it only if the manifest changes too, and a change to una.toml is easy to see, and easy to require a review for.
13.3.3 How to write [contracts]
A lock is one line under [contracts]:
[package]
name = "store"
version = "0.1.0"
edition = "0.3"
[run]
entry = "store.app"
grants = ["console"]
# What `store.sale.apply_sale` may do with the price list, and when.
[contracts]
"store.sale.apply_sale" = ["@prices: PriceList[set_price where not dry_run]"][contracts]. The table of locks. Like[boundaries], it exists only in edition0.3."store.sale.apply_sale". The key: the qualified name of a public function of the package, its module path, a dot, and its name. It is in quotes, since it holds dots.["…"]. The value: an array ofusesclauses, each a text written as the header writes it, without the worduses.@prices: PriceList[set_price where not dry_run]. One clause: the binding, its capability, and in brackets the operations the function may perform, each with its condition when it has one.
13.3.3.1 Several bindings, and operations without a condition
A lock lists every binding the header has, and an operation may be listed with or without a condition. This step locks two functions:
[package]
name = "store"
version = "0.1.0"
edition = "0.3"
[run]
entry = "store.app"
grants = ["console"]
# Reading a price may only read the price list.
# A sale may read prices, set them only outside a dry run, and record to the audit log.
[contracts]
"store.sale.apply_sale" = ["@prices: PriceList[price, set_price where not dry_run]", "@audit: Audit[record]"]
"store.sale.show_price" = ["@prices: PriceList[price]"]show_pricemay only read prices: its lock listspricewith no condition.apply_salehas two bindings, so its lock has two texts.pricehas no condition, andset_pricehas one.
The module writes the same clauses in the headers:
module store.sale
--- The price list of the shop.
pub capability PriceList
op price(sku: Text) -> Int
op set_price(sku: Text, cents: Int) -> Unit
--- The log where every price change is recorded.
pub capability Audit
op record(line: Text) -> Unit
--- The price of a SKU, in cents.
pub show_price(sku: Text) -> Int
uses @prices: PriceList[price]
=
@prices.price(sku)
--- Takes `percent` off the price of a SKU, and records it. A dry run changes no price.
pub apply_sale(sku: Text, percent: Int, dry_run: Bool) -> Int
uses @prices: PriceList[price, set_price where not dry_run]
uses @audit: Audit[record]
=
let cents = @prices.price(sku)
let sale = cents - cents * percent / 100
if not dry_run
@prices.set_price(sku, cents: sale)
@audit.record("{sku}: {cents} to {sale}")
salemodule store.app
import store.sale (Audit, PriceList, apply_sale, show_price)
--- A price list where every SKU costs `each` cents, and that prints each change instead of storing it.
handler flat(each: Int) for PriceList
uses @console: Console[print]
op price(sku) = each
op set_price(sku, cents) = @console.print("set {sku} to {cents}")
--- An audit log that prints each line.
handler printed() for Audit
uses @console: Console[print]
op record(line) = @console.print("audit: {line}")
pub main() -> Unit
uses @console: Console[print]
=
let shown = show_price("LAMP-01") with @prices = flat(1990)
@console.print("LAMP-01 costs {shown}")
let planned = apply_sale("LAMP-01", percent: 10, dry_run: true) with @prices = flat(1990), @audit = printed()
@console.print("a dry run plans {planned}")LAMP-01 costs 1990
audit: LAMP-01: 1990 to 1791
a dry run plans 1791The dry run reads the price and writes the audit line, and sets no price.
13.3.4 A sale that cannot lose its dry run
Back to the sale of Why lock a header, with its condition, its guard, and the lock of How to write [contracts]:
module store.sale
--- The price list of the shop.
pub capability PriceList
op set_price(sku: Text, cents: Int) -> Unit
--- Takes `percent` off the price of a product. A dry run changes nothing, and says what it would do.
pub apply_sale(sku: Text, cents: Int, percent: Int, dry_run: Bool) -> Int
uses @prices: PriceList[set_price where not dry_run]
=
let sale = cents - cents * percent / 100
if not dry_run
@prices.set_price(sku, cents: sale)
salemodule store.app
import store.sale (PriceList, apply_sale)
--- A price list that prints each change instead of storing it.
handler printed() for PriceList
uses @console: Console[print]
op set_price(sku, cents) = @console.print("set {sku} to {cents}")
pub main() -> Unit
uses @console: Console[print]
=
let planned = apply_sale("DESK-02", cents: 24900, percent: 20, dry_run: true) with @prices = printed()
@console.print("a dry run plans {planned}")
let applied = apply_sale("LAMP-01", cents: 1990, percent: 10, dry_run: false) with @prices = printed()
@console.print("the sale applied {applied}")a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791The dry run of the desk plans its sale price and sets nothing. The real sale of the lamp sets its price. The handler printed prints each change instead of storing it, so you see when set_price runs.
13.3.5 How a lock is checked
The body and the lock are checked separately. The verifier proves that the body keeps its header, as section 13.1 showed. The lock adds one more check: that the header keeps the lock. The header must grant no more than its lock.
13.3.5.1 A header may grant less
A header may grant less than its lock, since that only narrows what the function may do: fewer operations, a stronger condition, or no binding of a capability that the lock names. A binding that the lock does not name at all, or an operation that it does not list, is U3023.
13.3.5.2 An operation the lock does not list (U3023)
Give show_price the right to set prices too:
--- a/src/store/sale.una
+++ b/src/store/sale.una
@@ -14 +14 @@
- uses @prices: PriceList[price]
+ uses @prices: PriceList[price, set_price][U3023] Error: the header of `show_price` lets `@prices.set_price` run, which its lock in `una.toml` does not list
╭─[ src/store/sale.una:14:34 ]
│
14 │ uses @prices: PriceList[price, set_price]
│ ────┬────
│ ╰────── the header of `show_price` lets `@prices.set_price` run, which its lock in `una.toml` does not list
│
├─[ una.toml:14:28 ]
│
14 │ "store.sale.show_price" = ["@prices: PriceList[price]"]
│ ─────────────┬─────────────
│ ╰─────────────── the lock
│
│ Help: repair 1: list only the operations of the lock in the header's `@prices`
│
│ Note: run `una explain U3023` for an explanation
────╯The first mark points at the operation in the header, and the second at the lock it breaks. The repair lists only the operations of the lock.
13.3.5.3 Weakening a locked header (U3023)
Now delete the condition from the header of apply_sale, and keep the guard:
--- a/src/store/sale.una
+++ b/src/store/sale.una
@@ -9 +9 @@
- uses @prices: PriceList[set_price where not dry_run]
+ uses @prices: PriceList[set_price][U3023] Error: the header of `apply_sale` lets `@prices.set_price` run where `not dry_run` does not hold, which `una.toml` locks
╭─[ src/store/sale.una:9:27 ]
│
9 │ uses @prices: PriceList[set_price]
│ ────┬────
│ ╰────── the header of `apply_sale` lets `@prices.set_price` run where `not dry_run` does not hold, which `una.toml` locks
│
├─[ una.toml:12:28 ]
│
12 │ "store.sale.apply_sale" = ["@prices: PriceList[set_price where not dry_run]"]
│ ────────────────────────┬────────────────────────
│ ╰────────────────────────── lock
│
│ Help: repair 1: restore the locked condition: write `set_price where not dry_run` in the header of `apply_sale`, or a condition that implies it; edit src/store/sale.una:9:36..9:36 to " where not dry_run"
│ Note 2: counterexample: dry_run = trueThe header now allows what the lock forbids, and the counterexample says when: dry_run = true. The body would still behave, since its guard is still there, but the promise the header makes is weaker than the lock, and that is what U3023 reports. The repair writes the condition back, and una fix . applies it:
$ una fix --dry-run .
fixed src/store/sale.una:9:36 U3023 restore the locked condition: write `set_price where not dry_run` in the header of `apply_sale`, or a condition that implies itThe repair changes the module, never una.toml. To weaken the contract, someone must change una.toml, and that change is what a reviewer sees.
13.3.5.4 What a lock may say (U7002)
Each of these is U7002, at the lock's line: a key that names no public function of the package; a text that does not parse, or lists no operation; one binding locked twice; a capability that the function's module does not see; an operation that the capability does not declare; and a condition that is not a Bool over the function's parameters. A handler is never locked: its operations are checked against its own header.
13.3.6 When to lock a contract
Which to use:
| You want… | Use |
|---|---|
| A function to keep what its body does, as its header says | Nothing more: the verifier already proves it |
| A header that cannot widen in a code change alone | A lock in [contracts] |
| To keep a supplier's module within what you grant it | A ceiling in [boundaries] (section 13.2) |
| The same rule on every call of a function | Its header; a lock only guards the header |
Lock the functions whose authority matters to the business: the ones that change prices, send money or delete records.
13.3.7 Check yourself: a narrower header
The header of apply_sale now asks for a stronger condition than its lock, and the guard matches it. The app adds a sale of 0 percent:
--- a/src/store/sale.una
+++ b/src/store/sale.una
@@ -9 +9 @@
- uses @prices: PriceList[set_price where not dry_run]
+ uses @prices: PriceList[set_price where not dry_run and percent > 0]
@@ -12 +12 @@
- if not dry_run
+ if not dry_run and percent > 0pub main() -> Unit
uses @console: Console[print]
=
let planned = apply_sale("DESK-02", cents: 24900, percent: 20, dry_run: true) with @prices = printed()
@console.print("a dry run plans {planned}")
let applied = apply_sale("LAMP-01", cents: 1990, percent: 10, dry_run: false) with @prices = printed()
@console.print("the sale applied {applied}")
let kept = apply_sale("RUG-07", cents: 4500, percent: 0, dry_run: false) with @prices = printed()
@console.print("a sale of 0 percent keeps {kept}")Does the package check against the same lock? If it does, what does una run . print?
Show the answer
It checks: the header's condition, not dry_run and percent > 0, implies the lock's, not dry_run, so the header grants less than the lock allows. una run . prints:
a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791
a sale of 0 percent keeps 4500A sale of 0 percent changes nothing, so the guard skips set_price, and no set line is printed for the rug.