Home / Docs / Configure a package

[contracts]

What it does

[contracts] in una.toml locks the uses clauses of selected public functions. The lock is the most authority the function header may grant: its bindings, their operations, and the conditions on those operations. If a later edit broadens that header, una check reports U3023. The lock constrains the header only; the body is checked against the header, so together they bound what the function may do.

The example below says update may run set_price only when dry_run is false. Its implementation guards the operation with that condition, and the two examples run the dry-run and live paths.

Learn more: Locking a contract: contracts and Limits on authority.

Forms

toml
[contracts]
"<module path>.<function>" = ["@<binding>: <Capability>[<op> [gives <label>] [where <condition>], ...]", ...]

Each key is the qualified name of a public function of the package: its module path, then the function name. Each value is an array of uses clauses written as a header writes them, with the operations listed in brackets; an entry must list at least one operation. A condition applies to the operation immediately before its where, and is a Bool of the refinement language over the function's parameters. A label after gives is the least label the header must read that operation's answers at (ADR 0094): a header that reads it lower is U3023, and una fix writes the label back. Its categories must be declared in [labels] categories.

Examples

una.tomltoml
[package]
name = "demo"
version = "0.1.0"
edition = "0.3"

[contracts]
"demo.update" = ["@catalog: Catalog[price, set_price where not dry_run]"]
src/demo.unauna
module demo

pub capability Catalog
  op price(sku: Int) -> Int
  op set_price(sku: Int, cents: Int) -> Unit

pub update(sku: Int, cents: Int, dry_run: Bool) -> Unit
  uses @catalog: Catalog[price, set_price where not dry_run]
=
  if not dry_run
    @catalog.set_price(sku, cents)
  unit

handler catalog() for Catalog
  op price(sku) = 0
  op set_price(sku, cents) = unit

test "dry run has no writes"
  given @catalog = catalog()
  do update(1, cents: 10, dry_run: true)
  expect not performed @catalog.set_price

test "live writes"
  given @catalog = catalog()
  do update(1, cents: 10, dry_run: false)
  expect performed @catalog.set_price

If the header is changed to Catalog[price, set_price] while the manifest still locks set_price where not dry_run, the contract_lock obligation that the header's condition implies the lock's is refuted, and checking fails with U3023 at the operation. Adding an operation or a binding that the lock does not list is U3023 too. A header that drops an operation or strengthens a condition grants less, and passes.

Edge cases

The checker verifies two separate relations: the function body must stay within its declared header (spec/05 §3 rule 4), and the header must stay within the lock (rule 5). A lock is not a run-time guard; the implementation expresses the condition in its control flow, and the verifier proves that each operation runs only where its condition holds.

Only public functions are locked. A handler is not locked: its operations are checked against its own header. The repair of U3023 brings the header back to its lock; changing the lock is never the repair.

Diagnostics

Edition

[contracts] is available in edition 0.3, a preview. In editions 0.1 and 0.2 it is an unknown table (U7002). Edition 0.4 keeps the rule, but a package of that edition describes itself in ita.una, where the lock is the contracts section, with one locked uses clause per line; its errors are U7008 at the line. una migrate converts [contracts] to that section.

Normative source