Skip to main content

CADL: Contract Architecture Description Language

Language Specification — Version 0.3 (Draft)

Graduate School of Informatics, Nagoya University — ERTL

October 20, 2026


Overview​

CADL (Contract Architecture Description Language) is a domain-specific language (DSL) for formally specifying, verifying, and deploying institutional designs in multi-agent System of Systems (SoS).

CADL adopts a three-layer architecture — Institution, Protocol, and Algorithm — so that governance rules and coordination mechanisms are described precisely within a single unified language. The Algorithm layer names the central and local algorithms each side runs; it does not describe their internals. From a CADL specification, the toolchain automatically generates simulator configurations and verifies design consistency.

Architecture at a Glance​

One source drives three outputs: formal verification and institutional-constraint code (smart contracts / policy / runtime classes) are produced from the parsed definition, and runtime simulator configs from the three-layer IR. Experiment results feed back into the CADL source so governance parameters (α, β, λ, ρ) can be tuned; α, β, and λ are the per-contract parameters, and ρ belongs to the motivation extension (Appendix C). The cadl tool covers the source, verifier, codegen, IR, and simulator-config steps; running experiments and evaluating them is done with a simulator or with CADL Explorer.

How to Read This Specification​

This document is organized into three parts. Readers are encouraged to follow the order below, but each chapter is also self-contained.

Part I — Background and Requirements​

  • 1. Introduction — Motivation, problem setting, and the role of CADL within the SoS research agenda.
  • 2. Objectives — What CADL aims to solve, and the scope of this draft.
  • 3. Comparison — Relationship to existing ADLs, contract languages, and multi-agent DSLs.
  • 4. Requirements — Functional and non-functional requirements that drive the language design.

Part II — Language and Design​

  • 5. Language Specification — Core syntax and semantics of the three layers (Institution / Protocol / Algorithm).
  • 6. Design — Design rationale, toolchain architecture, verification engine, and runtime system. The intermediate representation (IR) is described in Appendix E, §E.7 and the Glossary.
  • 7. Examples — Worked examples illustrating typical CADL usage.

Part III — Applications and Outlook​

  • 8. Use Cases — Application domains and case studies.
  • 9. Research — Open research questions and theoretical foundations.
  • 10. Roadmap — Implementation phases and the current status of the reference implementation.

Appendices​

Suggested Reading Paths​

  • First-time readers — To try the language first, start with the Quick Start; to learn it step by step, with the Textbook. To read this specification itself, read Chapters 1–2, skim Chapter 5, then look at Chapter 7 for concrete examples. The Chapter 7 listings are conceptual; runnable examples are in the examples/ directory of the cadl repository.
  • Implementers / tool builders — Focus on Chapters 5, 6, and Appendix A.
  • Researchers — Chapters 3, 9, and 10 give the broader context and open problems.

Getting the tool​

The reference implementation is cadl, published on PyPI as cadl-lang; the command is cadl. To install it and check a first example, follow Path B of the Quick Start. To work with a clone of the repository (an editable install, as the hands-on materials do), follow Section 2.4 of the Textbook. The repository README lists all commands.

  • cadl — The CADL compiler and command-line tool (reference implementation), published on PyPI as cadl-lang.
  • CADL Explorer — An interactive web application that demonstrates the CADL governance pipeline end-to-end, from specification through simulation to governance evaluation.
  • cadl-raspimouse-simulator — The simulator used by the hands-on course.

Learning by doing​

To write and run the language rather than only read about it, see the Textbook: starting from robot delivery, it walks through authoring a spec, generating code, and running the simulation. The hands-on materials add courses on other domains.

Status​

This is Version 0.3 (Draft). The language and toolchain are under active development; syntax and semantics may change in future revisions.

Version 0.3 extends Version 0.2 as follows. A file that is valid under Version 0.2 is valid under Version 0.3 and is read the same way.

  • Unary minus: an expression may contain a unary - (permit_state == -2, x > -0.5, -a * b); it binds tighter than * and /, and -x has the value of 0 - x (Appendix A, §A.10).
  • Verification target of a transition: the target: of a verification: entry may name a transition as FROM->TO (Appendix A, §A.8).
  • The SoS name is a string, not an identifier (Appendix A, §A.3).
  • model: hybrid is reserved in the motivation extension: a processor MUST accept it and treat it as commitment_budget (Appendix C).
  • Norms extension: the new extension norms: 0.1 (Appendix F) makes obligations, permissions, prohibitions, and powers first-class objects of a contract and adds bounded temporal operators. A file that does not declare it is read as before.
  • Agent governance extension: agents: 0.1 (Appendix G) binds actors to agents and tool servers and defines the allow / deny / escalate decision that the norms of a contract give for a message, with delegation and audit records.
  • Stochastic model extension: stochastic: 0.1 (Appendix H) gives a file an explicit parametric Markov model in which the institutional parameters appear, and defines the regime map as a query on it.
  • Strategic model extension: games: 0.1 (Appendix I) reads that model as a turn-based game among players and defines whether a named memoryless deterministic profile, in particular compliance, is an equilibrium against unilateral deviations, also as a map over parameters. The reference implementation provides it from cadl 0.3.23 (cadl game-check).
  • Grounding extension: grounding: 0.1 (Appendix J) derives indices for α and β and a coverage measure for incentives from the norms of a contract, compares the declared values with the indices, and defines the payoff term of the sanction of a norm. The reference implementation provides it from cadl 0.3.23 (cadl norms-indices).

Version 0.2 reconciled the text of Version 0.1 with the reference implementation. The changes that affect how a Version 0.1 file is read are:

  • β is the degree of centralisation of decision-making: 0 is fully decentralised and 1 is fully centralised (Section 5.4.2). Parts of Version 0.1 described it in the opposite direction.
  • SoS-DSL extension (Appendix E): on_violation.transition and on_match.transition name a target state (rules L-5 and M-3), and on_match.violation is a label that needs no declaration (rule M-2). The extension itself is still sos-dsl: 0.1.
  • A sharing: entry MUST be a quoted string (- "TAXI[*] -> CENTRAL : position"); unquoted, YAML reads it as a mapping and not as a string (Appendix A, §A.4).
  • The bound of a symbolic range is a symbolic size: in [1..N], N stands for any number of actors, and the language has no construct that gives it a value (Section 5.2.2, Appendix A, §A.3).
  • Identifiers are ASCII; strings and comments may contain any Unicode character (requirement NFR-7 in Chapter 4, Appendix A, §A.1).

The motivation extension keeps its own label, v0.1-ext.

The specification and the reference implementation are numbered independently: this specification is Version 0.3. The release of the reference implementation it was checked against, and how that release deviates from the grammar, are given in Appendix A, §A.12.

Feedback and discussion are welcome via GitHub Issues. Problems with the specification or this site can be reported at cadl-spec Issues.