---
title: "13.3 Locking a contract: [contracts]"
url: https://una-lang.org/en/learn/authority/locking-a-contract-contracts/
release: v0.4.0
edition: "0.2, 0.3"
---

# 13.3 Locking a contract: [contracts]

## 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`.

```diff include="steps/12-locked..steps/13-unlocked:src/store/sale.una" context="1" title="src/store/sale.una"
--- 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)
   sale
```

This 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:

```text include="steps/13-unlocked/expected/output.txt"
set DESK-02 to 19920
a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791
```

The 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]`:

:::steps
```toml include="steps/12-locked/una.toml" title="steps/12-locked/una.toml"
[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]"]
```

1. **`[contracts]`.** The table of locks. Like `[boundaries]`, it exists only in edition `0.3`.
2. **`"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.
3. **`["…"]`.** The value: an array of `uses` clauses, each a text written as the header writes it, without the word `uses`.
4. **`@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:

```toml include="steps/14-lock-forms/una.toml" title="steps/14-lock-forms/una.toml"
[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_price` may only read prices: its lock lists `price` with no condition.
- `apply_sale` has two bindings, so its lock has two texts. `price` has no condition, and `set_price` has one.

The module writes the same clauses in the headers:

```una include="steps/14-lock-forms/src/store/sale.una" title="steps/14-lock-forms/src/store/sale.una" verified="check"
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}")
  sale
```

```una include="steps/14-lock-forms/src/store/app.una" title="steps/14-lock-forms/src/store/app.una" verified="check, run"
module 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}")
```

```text include="steps/14-lock-forms/expected/output.txt"
LAMP-01 costs 1990
audit: LAMP-01: 1990 to 1791
a dry run plans 1791
```

The 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](#why-lock-a-header), with its condition, its guard, and the lock of [How to write `[contracts]`](#how-to-write-contracts):

```una include="steps/12-locked/src/store/sale.una" title="steps/12-locked/src/store/sale.una" verified="check"
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)
  sale
```

```una include="steps/12-locked/src/store/app.una" title="steps/12-locked/src/store/app.una" verified="check, run"
module 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}")
```

```text include="steps/12-locked/expected/output.txt"
a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791
```

The 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](https://una-lang.org/en/learn/authority/conditions-on-operations-edition-0-3/#s13-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:

```diff include="steps/14-lock-forms..steps/15-extra-op:src/store/sale.una" context="0" title="src/store/sale.una"
--- a/src/store/sale.una
+++ b/src/store/sale.una
@@ -14 +14 @@
-  uses @prices: PriceList[price]
+  uses @prices: PriceList[price, set_price]
```

```text include="steps/15-extra-op/expected/rendered.txt"
[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:

```diff include="steps/12-locked..steps/16-weakened:src/store/sale.una" context="0" title="src/store/sale.una"
--- 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]
```

```text include="steps/16-weakened/expected/rendered.txt#L1-L14,L18"
[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 = true
```

The 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:

```text include="steps/16-weakened/expected/commands/fix.txt"
$ 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 it
```

The 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

:::decide
**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](https://una-lang.org/en/learn/authority/a-ceiling-for-a-module-boundaries/#s13-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:

```diff include="steps/12-locked..steps/17-narrower:src/store/sale.una" context="0" title="src/store/sale.una"
--- 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 > 0
```

```una include="steps/17-narrower/src/store/app.una#main" title="steps/17-narrower/src/store/app.una"
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}")
  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?

:::answer 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:

```text include="steps/17-narrower/expected/output.txt"
a dry run plans 19920
set LAMP-01 to 1791
the sale applied 1791
a sale of 0 percent keeps 4500
```

A sale of 0 percent changes nothing, so the guard skips `set_price`, and no `set` line is printed for the rug.
:::
