Markdown agreement format

Canonical markdown agreement format for auto contracts with bounded subjective resolution.

Auto Contract Standard: Agreement Format

Abstract

This standard defines a canonical markdown document format for auto contract agreements. An agreement is a human-readable markdown document with structured YAML frontmatter whose hash is anchored onchain through an IAutoContract implementation. The format is generic: it works for escrow, governance, bounties, disputes, insurance, and any other contract type that requires bounded subjective resolution.

Motivation

Smart contracts excel at objective, deterministic settlement but break down when an outcome depends on a bounded judgment: did the deliverable meet the spec, was the governance proposal enacted faithfully, does the insurance claim qualify?

Encoding full agreement semantics in Solidity is impractical. Natural language is necessary for expressing terms, but natural language is not hashable or machine-routable without structure. This standard resolves the tension:

  • Markdown defines meaning. Agreements are written in plain markdown so that every party -- human or agent -- can read, audit, and reason about the terms without specialized tooling.
  • YAML frontmatter makes agreements machine-routable. Constrained fields let software validate parties, deadlines, chain targets, and contract types without parsing prose.
  • Hashes anchor meaning onchain. The full document is hashed; only the hash is stored onchain. This keeps the onchain footprint minimal while preserving a tamper-proof link to the complete terms.
  • The format is contract-type agnostic. By defining outcomes as named labels rather than hardcoded enums, a single agreement format serves escrow, governance, bounties, dispute resolution, and any future contract type.

Specification

Document Structure

A conforming agreement is a UTF-8 markdown document with two parts:

  1. YAML frontmatter delimited by ---
  2. A markdown body containing the required sections defined below

Required Frontmatter

Every agreement begins with YAML frontmatter containing these fields:

```yaml

standard: auto.contracts/v1 version: 1 chain_id: 421614217 contract_type: escrow parties:

  • address: "0x1111111111111111111111111111111111111111" role: buyer
  • address: "0x2222222222222222222222222222222222222222" role: seller resolver: "0x3333333333333333333333333333333333333333" resolver_policy: centralized_single_resolver deadline: "2026-05-15T17:00:00Z"

```

Field Definitions

  • standard -- Required. Must equal auto.contracts/v1, identifying this document as conforming to this standard.
  • version -- Required. Must equal 1. Reserved for future revisions.
  • chain_id -- Required. The chain ID of the IAutoContract settlement contract, as a positive integer.
  • contract_type -- Required. A lowercase identifier for the agreement's domain — a single word or hyphenated phrase. This standard doesn't restrict values; common types include escrow, governance, bounty, dispute, insurance, and milestone.
  • parties -- Required. An ordered array of party objects, each containing:
    • address -- A valid account address on the target chain, as a hex string.
    • role -- A lowercase label for the party's role (e.g., buyer, seller, proposer, voter, claimant, insurer). Roles are defined by the contract_type, not restricted by this standard.
  • resolver -- Required. The address authorized to call resolve on the settlement contract.
  • resolver_policy -- Required. A human-readable label for the resolver's governance model — e.g., centralized_single_resolver, multisig_3_of_5, dao_vote, oracle. For human interpretation only; it doesn't constrain onchain behavior.
  • deadline -- Required. An ISO 8601 timestamp, with a timezone designator, after which the agreement may expire under implementation-specific rules.

Optional Frontmatter

Agreements may include extra frontmatter for domain-specific data. Common optional fields:

  • visibility -- Access control for the document — public or private, defaulting to public.
    • public -- The document at contractURI is accessible to anyone.
    • private -- The document at contractURI is accessible only to the parties and the resolver. The termsHash remains public onchain and can verify the document for anyone who obtains it through other means.
  • currency -- Human-readable asset label (e.g., USDC, ETH).
  • amount -- Settlement amount as a decimal string.
  • quorum -- Required participation threshold for multi-party resolution.
  • appeals -- Number of allowed appeal rounds.

Consumers ignore unknown frontmatter fields.

Required Markdown Sections

The markdown body contains these sections, in order:

1. # Agreement

Starts with a level-1 heading. The heading should describe the agreement — # Agreement, # Governance Proposal #42, # Bug Bounty: Authentication Bypass.

2. ## Terms

Free-form markdown describing what the agreement covers — the obligations, deliverables, conditions, proposals, or claims at stake. It should be specific enough that a resolver can evaluate compliance without external context the document doesn't reference.

3. ## Review Question

Defines exactly one bounded question the resolver answers, phrased so that each possible answer maps to exactly one outcome in ## Resolution Effects.

A good question is:

  • Bounded -- answerable from the evidence classes listed in ## Allowed Evidence.
  • Objective where possible -- referencing concrete criteria from ## Terms.
  • Unambiguous -- a single question, not a compound query.

4. ## Allowed Evidence

Lists the evidence classes the resolver may inspect when answering the review question. Each class should be a short identifier or description.

Recommended evidence class identifiers:

  • github_pr
  • deployed_url
  • figma_link
  • screenshot
  • written_notes
  • onchain_data
  • attestation
  • api_response

Implementations may define additional evidence classes. The resolver must not consider evidence outside the classes listed here.

5. ## Resolution Effects

Maps each possible answer to the review question onto a named outcome. Outcomes are expressed as:

``` answer => outcome ```

Each outcome is a lowercase label that corresponds to a bytes32 value onchain (computed as keccak256(bytes(outcome))). The settlement contract uses this value to execute the appropriate state transition.

There must be at least two outcomes. Common labels:

  • release, refund (escrow)
  • approve, reject (governance)
  • valid, invalid (bounty, dispute)
  • covered, denied (insurance)

Canonical Hash Computation

The canonical agreement hash (termsHash) passed to IAutoContract.create(..., termsHash) is computed as:

``` termsHash = keccak256(document_bytes) ```

Where document_bytes is the complete UTF-8 encoded markdown document, including the YAML frontmatter delimiters.

Three normalization rules apply:

  1. Line endings are normalized to \n (LF) before hashing.
  2. The document either has no trailing newline after its final non-whitespace character, or exactly one — the publisher picks one convention and applies it consistently. Whichever they choose, the resulting bytes are canonical.
  3. The document carries no byte-order mark (BOM).

This standard doesn't mandate a transport or publication layer — only that:

  • The bytes hashed offchain are stable and reproducible.
  • The resulting termsHash is the value passed to the settlement contract.

Relationship to IAutoContract

An IAutoContract settlement instance created from a conforming agreement satisfies:

  • The first party in parties is the creator (the msg.sender of create).
  • The second party in parties is the counterparty argument to create.
  • resolver equals the resolver frontmatter field.
  • termsHash equals the canonical agreement hash.

When the resolver calls IAutoContract.resolve(contractId, outcome, resolutionHash):

  • outcome equals keccak256(bytes(label)), where label is the outcome string from ## Resolution Effects (e.g., keccak256(bytes("release"))).
  • resolutionHash is the hash of a resolution document conforming to the resolution standard paired with this agreement's contract_type.

For agreements with more than two parties, the mapping to IAutoContract.create is defined by the contract-type-specific extension standard. This base standard defines only the two-party case.

Extensibility

Contract-type-specific standards (e.g., auto.contracts/escrow/v1, auto.contracts/governance/v1) MAY:

  1. Require additional frontmatter fields beyond those defined here.
  2. Require additional markdown sections beyond those defined here.
  3. Restrict the allowed values of contract_type, parties[].role, and outcome labels.
  4. Define additional normalization rules for the canonical hash.

Extensions cannot remove or redefine any field or section this standard requires. A document conforming to an extension also conforms to this base standard.

Invariants

  1. Hash determinism. Identical document bytes always produce an identical termsHash; any difference in bytes produces a different one.

  2. Frontmatter completeness. A conforming agreement carries every required frontmatter field. A document missing any required field is non-conforming, and consumers reject it.

  3. Section completeness. A conforming agreement carries every required markdown section. Additional sections may appear between or after them, but the required ones are always present.

  4. Outcome coverage. Every possible answer to the review question maps to exactly one outcome in ## Resolution Effects — no answer is left unmapped.

  5. Outcome computability. Every outcome label in ## Resolution Effects converts deterministically to bytes32 via keccak256(bytes(label)), and the settlement contract uses that value and no other.

  6. Party-address binding. The addresses in parties match the addresses used in the onchain create call. Any mismatch makes the agreement non-conforming.

  7. Resolver exclusivity. Only the address in the resolver field can call resolve for this agreement, enforced by the settlement contract.

  8. Evidence boundary. The resolver considers only the evidence classes listed in ## Allowed Evidence. A resolution that relies on excluded evidence is non-conforming.

  9. Immutability after hashing. Once the termsHash is onchain, the document bytes never change. Any amendment is a new agreement with a new hash.

  10. Forward compatibility. Consumers ignore unknown frontmatter fields and markdown sections, so extension standards don't break base-standard consumers.

Example

The following is a conforming agreement for a bug bounty:

```md

standard: auto.contracts/v1 version: 1 chain_id: 421614217 contract_type: bounty parties:

  • address: "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" role: sponsor
  • address: "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" role: hunter resolver: "0xcccccccccccccccccccccccccccccccccccccccc" resolver_policy: centralized_single_resolver deadline: "2026-06-01T00:00:00Z" currency: USDC amount: "10000"

Agreement

Bug bounty for critical authentication bypass in api.example.com.

Terms

The sponsor offers a bounty of 10,000 USDC for a verified report demonstrating a critical authentication bypass in the production API at api.example.com.

A qualifying report MUST include:

  1. A step-by-step reproduction of the vulnerability.
  2. Proof that the bypass grants access to authenticated endpoints without valid credentials.
  3. A proposed remediation.

The hunter MUST submit the report before the deadline. The sponsor MUST NOT patch the reported vulnerability before the resolver renders a decision.

Review Question

Does the submitted report demonstrate a critical authentication bypass in api.example.com that is reproducible and includes a proposed remediation?

Allowed Evidence

  • written_notes
  • screenshot
  • api_response
  • github_pr

Resolution Effects

  • yes => release
  • no => refund ```

Copyright

This document is placed in the public domain.