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

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Document Structure

A conforming agreement MUST be a UTF-8 encoded markdown document consisting of:

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

Required Frontmatter

A conforming agreement MUST begin with YAML frontmatter containing the following 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 -- MUST equal auto.contracts/v1. Identifies this document as conforming to this standard.
  • version -- MUST equal 1. Reserved for future revisions.
  • chain_id -- REQUIRED. The chain ID on which the IAutoContract settlement contract exists. MUST be a positive integer.
  • contract_type -- REQUIRED. A lowercase identifier for the agreement's domain. This standard does not restrict values; common types include escrow, governance, bounty, dispute, insurance, and milestone. Implementations SHOULD use a single word or hyphenated phrase.
  • parties -- REQUIRED. An ordered array of party objects. Each party object MUST contain:
    • address -- A valid account address on the target chain, as a hex string.
    • role -- A lowercase label describing the party's role in the agreement (e.g., buyer, seller, proposer, voter, claimant, insurer). Role labels are defined by the contract_type and are not restricted by this standard.
  • resolver -- REQUIRED. The address authorized to call resolve on the settlement contract.
  • resolver_policy -- REQUIRED. A human-readable label describing the resolver's governance model. Examples: centralized_single_resolver, multisig_3_of_5, dao_vote, oracle. This field is for human interpretation; it does not constrain onchain behavior.
  • deadline -- REQUIRED. An ISO 8601 timestamp after which the agreement MAY expire according to implementation-specific rules. MUST include a timezone designator.

Optional Frontmatter

Agreements MAY include additional frontmatter fields for domain-specific data. Common optional fields include:

  • 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.

Conforming consumers MUST ignore unknown frontmatter fields.

Required Markdown Sections

The markdown body MUST contain the following sections in order:

1. # Agreement

The document MUST begin with a level-1 heading. The heading text SHOULD describe the agreement (e.g., # Agreement, # Governance Proposal #42, # Bug Bounty: Authentication Bypass).

2. ## Terms

The ## Terms section MUST describe what the agreement covers: the obligations, deliverables, conditions, proposals, or claims at stake. This section is free-form markdown. It SHOULD be specific enough that a resolver can evaluate compliance without external context not referenced in the document.

3. ## Review Question

The ## Review Question section MUST define exactly one bounded question that the resolver answers. The question MUST be phrased so that each possible answer maps to exactly one outcome defined in ## Resolution Effects.

The question SHOULD be:

  • 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

The ## Allowed Evidence section MUST list the evidence classes the resolver MAY inspect when answering the review question. Each evidence 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 in this section.

5. ## Resolution Effects

The ## Resolution Effects section MUST map each possible answer to the review question to 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.

The section MUST define at least two outcomes. Common outcome labels include:

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

Canonical Hash Computation

The canonical agreement hash (termsHash) for IAutoContract.create(..., termsHash) MUST be computed as:

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

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

This standard imposes the following normalization requirements:

  1. Line endings MUST be normalized to \n (LF) before hashing.
  2. The document MUST NOT contain a trailing newline after the final non-whitespace character, OR it MUST contain exactly one trailing newline. The publisher MUST choose one convention and apply it consistently. Whichever convention is chosen, the resulting bytes are the canonical form.
  3. The document MUST NOT contain a byte-order mark (BOM).

This standard does not mandate a transport or publication layer. It mandates 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 MUST satisfy:

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

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

  • outcome MUST equal keccak256(bytes(label)) where label is the outcome string from ## Resolution Effects (e.g., keccak256(bytes("release"))).
  • resolutionHash MUST be 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.

Such extensions MUST NOT remove or redefine any field or section required by this standard. A document that conforms to an extension standard MUST also conform to this base standard.

Invariants

  1. Hash determinism. Given identical document bytes, the termsHash MUST be identical. Given any difference in document bytes, the termsHash MUST differ.

  2. Frontmatter completeness. A conforming agreement MUST contain all required frontmatter fields. A consumer that encounters a document missing any required field MUST reject it as non-conforming.

  3. Section completeness. A conforming agreement MUST contain all required markdown sections. Additional sections MAY appear between or after the required sections, but the required sections MUST be present.

  4. Outcome coverage. Every possible answer to the review question MUST map to exactly one outcome in ## Resolution Effects. There MUST be no answer that lacks a mapping.

  5. Outcome computability. Every outcome label in ## Resolution Effects MUST be deterministically convertible to a bytes32 value via keccak256(bytes(label)). The settlement contract MUST use this value and no other.

  6. Party-address binding. The addresses in the parties array MUST correspond to the addresses used in the onchain create call. A mismatch between the agreement's parties and the onchain participants makes the agreement non-conforming.

  7. Resolver exclusivity. Only the address in the resolver field MAY call resolve on the settlement contract for this agreement. The settlement contract MUST enforce this constraint.

  8. Evidence boundary. The resolver MUST NOT consider evidence outside the classes enumerated in ## Allowed Evidence. A resolution that relies on excluded evidence is non-conforming.

  9. Immutability after hashing. Once the termsHash has been submitted onchain, the document bytes MUST NOT be modified. Any amendment requires a new agreement with a new hash.

  10. Forward compatibility. Conforming consumers MUST ignore unknown frontmatter fields and unknown markdown sections. This ensures that extension standards do not 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.