DHL concepts

Contract

A contract describes one kind of record: its state, the actions that change it, and the queries that read it. It is a Markdown file with front matter and fenced dhl blocks; prose around the blocks is for people.

---
namespace: sam.tools.loan
version: 1.0.0
---

A tool lent to someone, until it comes back.

```dhl
aggregate Loan
    state
        public item: Text(len=200)
        public status: Text(len=20)
```

The namespace names the contract (std.personal.shopping_list, com.acme.orders.order). Contracts in a repository live at the path of their namespace: contracts/std/personal/shopping_list.dhl.

Artifact

Compiling a contract produces an artifact: its schema and its WebAssembly code, identified by the hash of both. The artifact, not the namespace, is what runs. Changing a rule changes the artifact; records written under the old one keep their history and move to the new one through a signed upgrade (Upgrading a contract).

Record (subject)

One instance of a contract: one loan, one invoice. A record has an id (its subject), a revision, its state, and its full history of signed changes. Records belong to a tenant, the identity they live in.

Action

The only way a record changes. An action takes typed arguments, validates them against the record's current state and its context (who signs, what time it is, other records it observes), then applies changes to the state. If any validation line is false, the whole action is refused and nothing changes. A refusal is recorded too, with its reason.

Signer

Every action is signed. context.signer is the identity whose key signed it. Rules decide what the signer may do: "only the owner may return a loan" is context.signer == state.owner. In Mandala, people sign with their own key and act for organisations by delegation, which contracts can check (Delegation).

Query

A named, typed read over the records of a contract, written in DHLQ: filter, sort, page, select, aggregate (DHLQ query reference). Queries are read-only.

Composition

An action can require actions on other records (requires): placing an order opens each order line and reserves stock, all signed by the original signer and all committed together, or none. An action can also observe another record's state, such as a delegation, as evidence.

Where contracts come from

• Built into Mandala: the standard library (std.identity, std.personal, std.business, std.exchange…), compiled into every node.
• Configured: files or folders in MANDALA_CONTRACTS.
• Installed from the Workbench: saved in <data>/contracts.