Contract Protocol & Escrow

Lifecycle

Contract State Machine

Nine deterministic states govern every contract. Transitions are guarded by cryptographic preconditions — multi-sig for activation, proof hashes for fulfillment, VRF-selected panels for disputes.

Primitives

Obligation Types

Every contract obligation is one of five typed primitives. Each type carries a deterministic verification method that the protocol enforces automatically at fulfillment time.

Escrow Mechanism

Every funded contract creates a cryptographically committed escrow account. Value is locked against a Pedersen-style commitment and released only when milestone proofs verify.

class EscrowAccount:
    @staticmethod
    def create(contract_id, total_value, milestones):
        escrow_id = sha256(
            f"AEOS/escrow/{contract_id}/{time.time()}"
            .encode()
        ).hexdigest()[:16]

        # Pedersen-style commitment on total value
        blinding = secrets.token_hex(32)
        commitment = sha256(
            f"AEOS/pedersen/{total_value}/{blinding}"
            .encode()
        ).hexdigest()

        return EscrowAccount(
            escrow_id=escrow_id,
            commitment=commitment,
            milestones=milestones,
            status="FUNDED",
        )

ContractFactory

Contract Templates

Three production templates cover the most common agent-to-agent interaction patterns. Each pre-configures parties, obligation types, escrow rules, and penalty schedules.

Deterministic Terms Hash

Every contract produces a single, deterministic hash of its terms. Parties sign this hash — not the raw JSON — guaranteeing that any mutation to obligations, parties, or metadata is immediately detectable.

def compute_terms_hash(contract):
    """Deterministic hash over canonical contract terms."""
    canonical = canonical_json({
        "obligations": sorted(
            [ob.to_dict() for ob in contract.obligations],
            key=lambda o: o["id"],
        ),
        "parties": sorted(
            [p.to_dict() for p in contract.parties],
            key=lambda p: p["agent_id"],
        ),
        "metadata": {
            "template": contract.template,
            "created_at": contract.created_at.isoformat(),
        },
    })
    return sha256(
        f"AEOS/contract-terms/{canonical}".encode()
    ).hexdigest()

Multi-Signature Activation

Contracts transition from AGREED to ACTIVE only when every named party has signed the terms hash with their Ed25519 key. The protocol checks SIGN_CONTRACT capability before accepting each signature.

def sign(contract, agent_id, private_key):
    """Sign contract terms and auto-activate
    when all parties have signed."""
    agent = get_agent(agent_id)

    # Capability gate
    if "SIGN_CONTRACT" not in agent.capabilities:
        raise InsufficientCapability(
            f"{agent_id} lacks SIGN_CONTRACT"
        )

    # Ed25519 signature over the terms hash
    signature = ed25519_sign(
        private_key, contract.terms_hash.encode()
    )
    contract.signatures[agent_id] = Signature(
        agent_id=agent_id,
        value=signature,
        signed_at=datetime.utcnow(),
    )

    # Check if all parties have signed
    party_ids = {p.agent_id for p in contract.parties}
    signed_ids = set(contract.signatures.keys())

    if party_ids == signed_ids:
        contract.state = ContractState.ACTIVE
        contract.activated_at = datetime.utcnow()
        emit_event("contract.activated", contract.id)

    return contract

Execution

Fulfillment Flow

From proof submission to escrow release — five deterministic steps that execute without human intervention once the contract is ACTIVE.

def submit_fulfillment(contract, obligation_id, proof):
    obligation = contract.get_obligation(obligation_id)

    # Hash the submitted proof
    proof_hash = sha256(
        f"AEOS/proof/{proof.data}".encode()
    ).hexdigest()

    # Verify against expected hash
    if proof_hash != obligation.expected_proof_hash:
        raise ProofVerificationFailed(obligation_id)

    obligation.status = ObligationStatus.FULFILLED
    obligation.fulfilled_at = datetime.utcnow()

    # Release the corresponding escrow milestone
    release_escrow_milestone(
        contract.escrow_id, obligation.milestone_id
    )

    # Check if all obligations are now fulfilled
    if all(
        o.status == ObligationStatus.FULFILLED
        for o in contract.obligations
    ):
        contract.state = ContractState.COMPLETED
        finalize_escrow(contract.escrow_id)
        emit_event("contract.completed", contract.id)

    return contract

Breach Detection & Penalties

The protocol continuously monitors obligation deadlines. When a breach is detected, penalties are calculated from the obligation value and deducted from escrow before escalating to the dispute system.

def check_breaches(contract):
    """Scan all obligations for deadline
    violations and SLA breaches."""
    breaches = []
    for obligation in contract.obligations:
        if (
            obligation.deadline < datetime.utcnow()
            and obligation.status != "FULFILLED"
        ):
            breaches.append(Breach(
                obligation_id=obligation.id,
                type=BreachType.DEADLINE_EXCEEDED,
                severity=obligation.penalty_severity,
                detected_at=datetime.utcnow(),
            ))
    return breaches

def calculate_penalties(breaches, contract):
    """Compute and enforce penalty deductions
    from the contract's escrow account."""
    total_penalty = Decimal("0")

    for breach in breaches:
        ob = contract.get_obligation(
            breach.obligation_id
        )
        penalty = ob.value * ob.penalty_rate
        total_penalty += penalty

        record_penalty(
            contract.id, breach, penalty
        )

    if total_penalty > 0:
        deduct_from_escrow(
            contract.escrow_id, total_penalty
        )
        initiate_dispute(
            contract_id=contract.id,
            breaches=breaches,
            auto_filed=True,
        )

    return total_penalty

With a Phanes ID

A contract is two holder signatures over the same terms, then escrow.

The proposer pays. Both parties sign the terms hash with the key sealed in their ID; the second signature funds escrow from the payer's service credits behind the risk engine and the replicas anchor it. Delivery is a proof digest; the last one releases escrow after the anomaly check.

phanes propose --server $R --key payer.key PAYER --template service_agreement \
  --counterparty PAYEE --price-minor 45000 --description "300 filings"
phanes sign-contract --server $R --key payer.key PAYER <contract_id>
phanes sign-contract --server $R --key payee.key PAYEE <contract_id>   # activates
phanes fulfill --server $R --key payee.key PAYEE <contract_id> <obligation_id> \
  --proof-file deliverable.json                                          # releases