Bitcoin Stratigraphy Enterprise Data Engine & Agent Notary Hub

by app.replit.bitcoin-stratigraphy-dashboard--charlesstrogish

clearing.settle_contract

Idempotent

Record a funded escrow contract as settled with a signed Groth16 preimage receipt. Production uses the Solo Founder Genesis key; opted-in local development retains its separate key and receipt domain. Requires the exact NIP-98 worker, task/escrow-bound proof and merchant-confirmed invoice funding before an atomic, idempotent evidence commit. No automated payout, arbitrary-execution guarantee or legal indemnity. Funds remain merchant-controlled. Note: Contract state polling, listing, cancellations, and automated refunds are intentionally disabled in this namespace by design to enforce strict manual payout verification and prevent automated drain attacks.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "escrow_id": "<escrow_id>",
      "execution_trace": "<execution_trace>"
    },
    "name": "clearing.settle_contract"
  }
}

Input Schema

Name	Required	Description
`escrow_id`	Yes	The escrow UUID returned by clearing.create_contract. Merchant-confirmed funding is required; an unpaid contract is not funded escrow.
`payout_invoice`	No	Worker-signed BOLT11 payout invoice. Automated payouts remain disabled pending separately reviewed fee-capped payout integration. Omit this field for proof receipt settlement.
`execution_trace`	Yes	JSON-encoded Groth16 proof envelope containing scheme, proof and publicSignals. Production scheme: 'clearing-poseidon-preimage-genesis-v1'; local development scheme: 'clearing-poseidon-preimage-development-v1'. Two canonical decimal public signals bind the exact Poseidon task hash and escrow UUID. Never include the private preimage. This proves preimage knowledge, not arbitrary task completion.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 8, 2026

changedInput schema / properties / escrow_id / description

Previous value: -"The unique UUID string identifying the escrow contract to settle, returned by clearing.create_contract (e.g., '550e8400-e29b-41d4-a716-446655440000'). Merchant-confirmed funding is required for local development settlement; an unpaid contract is not funded escrow."New value: +"The escrow UUID returned by clearing.create_contract. Merchant-confirmed funding is required; an unpaid contract is not funded escrow."

changedInput schema / properties / execution_trace / description

Previous value: -"The worker-generated Groth16 Poseidon preimage proof envelope, provided as a JSON-encoded string containing scheme, proof, and publicSignals. Use scheme 'clearing-poseidon-preimage-development-v1' and two canonical decimal-string public signals binding the exact task hash and escrow UUID. This proves preimage knowledge, not arbitrary task completion. Serialize the envelope as a string, not a bare hex string or JSON object, and never include the private preimage."New value: +"JSON-encoded Groth16 proof envelope containing scheme, proof and publicSignals. Production scheme: 'clearing-poseidon-preimage-genesis-v1'; local development scheme: 'clearing-poseidon-preimage-development-v1'. Two canonical decimal public signals bind the exact Poseidon task hash and escrow UUID. Never include the private preimage. This proves preimage knowledge, not arbitrary task completion."

changedInput schema / properties / payout_invoice / description

Previous value: -"Worker-signed BOLT11 payout invoice. Payouts remain unconditionally disabled pending independent Phase 2 MPC setup and reviewed activation."New value: +"Worker-signed BOLT11 payout invoice. Automated payouts remain disabled pending separately reviewed fee-capped payout integration. Omit this field for proof receipt settlement."

Changed2 schema fields changedNov 7, 2026

addedInput schema / properties / escrow_id / description

Added value: +"The unique UUID string identifying the escrow contract to settle, returned by clearing.create_contract (e.g., '550e8400-e29b-41d4-a716-446655440000'). Merchant-confirmed funding is required for local development settlement; an unpaid contract is not funded escrow."

addedInput schema / properties / execution_trace / description

Added value: +"The worker-generated Groth16 Poseidon preimage proof envelope, provided as a JSON-encoded string containing scheme, proof, and publicSignals. Use scheme 'clearing-poseidon-preimage-development-v1' and two canonical decimal-string public signals binding the exact task hash and escrow UUID. This proves preimage knowledge, not arbitrary task completion. Serialize the envelope as a string, not a bare hex string or JSON object, and never include the private preimage."

Changed1 schema field changedNov 7, 2026

addedInput schema / properties / payout_invoice

Added value: +{
+  "description": "Worker-signed BOLT11 payout invoice. Payouts remain unconditionally disabled pending independent Phase 2 MPC setup and reviewed activation.",
+  "maxLength": 4096,
+  "minLength": 1,
+  "type": "string"
+}

AddedNov 7, 2026

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover the mutation profile (readOnly=false, idempotent=true, destructive=false), and the description adds real context: atomic idempotent evidence commit, auth requirements, merchant-controlled funds, and no legal indemnity. However, several claims ('idempotent' commit, 'no automated payout') restate annotations or schema text, and the disclosure mixes security disclaimers with operative behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and mechanism are front-loaded in sentence one, followed by prerequisites, then scope limits, which is a sensible ordering for a high-stakes settling call. The final note is long and the disclaimer cluster ('No automated payout, arbitrary-execution guarantee or legal indemnity') is dense, but nearly every clause carries operational weight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter, no-output-schema mutation with rich annotations, the description supplies auth requirements, funding preconditions, scheme selection, failure-relevant constraints, and explicit non-goals. The one gap is that it never indicates what a successful settlement returns or confirms, which matters given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter already carries a detailed description including scheme names, the two public signals, and the caution never to include the private preimage. The prose adds little parameter-level meaning beyond emphasizing the production versus local key domains and 'no automated payout'. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a precise verb and resource ('Record a funded escrow contract as settled') plus the mechanism ('signed Groth16 preimage receipt'), which no sibling tool provides. The closing note scopes the namespace by declaring what is deliberately absent (polling, listing, cancellation, refunds), so an agent can separate this from status/listing tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Preconditions for use are explicit: exact NIP-98 worker, task/escrow-bound proof, and merchant-confirmed invoice funding, plus the distinction that an unpaid contract is not funded escrow. It also states that settlement without a payout invoice is the supported path. It stops short of naming a concrete alternative tool for the disabled operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Bitcoin Stratigraphy Enterprise Data Engine & Agent Notary Hub tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?