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
- Appendix A — Syntax — EBNF grammar reference.
- Appendix B — References — Cited literature.
- Appendix C — Motivation Extension — Agent motivation models and profiles.
- Appendix D — Code Generation Targets — Catalogue of codegen targets.
- Appendix E — SoS-DSL Extension — Contract lifecycles and runtime monitors.
- Appendix F — Norms Extension — Obligations, permissions, prohibitions and powers, counts-as rules, bounded temporal operators, and amendments.
- Appendix G — Agent Governance Extension — Agents and tool servers as actors, allow / deny / escalate decisions from norms at the message boundary, delegation with provenance, and boundary-policy generation.
- Appendix H — Stochastic Model Extension — A parametric Markov model in which α, β and λ appear, properties, regime map queries, and export to the PRISM language.
- Appendix I — Strategic Model Extension — Players, profiles and payoffs on the model of Appendix H, checks that a named memoryless deterministic profile is an equilibrium against unilateral deviations, and equilibrium maps over institutional parameters.
- Appendix J — Grounding of the Institutional Parameters — Indices for α and β and a coverage measure for incentives, derived from the norms of a contract; their comparison with the declared values; and the payoff term of a sanction.
- Glossary — Terms used throughout the specification.
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.
Related Tools
- 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-xhas the value of0 - x(Appendix A, §A.10). - Verification target of a transition: the
target:of averification:entry may name a transition asFROM->TO(Appendix A, §A.8). - The SoS
nameis a string, not an identifier (Appendix A, §A.3). model: hybridis reserved in the motivation extension: a processor MUST accept it and treat it ascommitment_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 fromcadl0.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 fromcadl0.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.transitionandon_match.transitionname a target state (rules L-5 and M-3), andon_match.violationis a label that needs no declaration (rule M-2). The extension itself is stillsos-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],Nstands 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.