ContractGraph-QA

Documentation: English · 简体中文 · हिन्दी · Español · العربية

Bounded verification for stateful financial systems

ContractGraph-QA tests declared failure paths between intent, authorization, execution, external evidence, ledger state, reconciliation, and retry.

It is built for payment, wallet, payout, stablecoin, agentic-commerce, and smart-contract teams that need reproducible evidence for one high-risk financial promise.

The primary recovery question is:

After an execution returns an ambiguous result, can the system prove whether the economic effect happened ZERO times, ONE time, or remains UNKNOWN before another monetary action is permitted?

one authorized intent → at most one economic effect

UNKNOWN outcome → no new financial action

Read the Recovery Design Partner Lab · View the proof-backed offer · Open the Boundary Brief · See the synthetic case study · Run the local demo

---

Choose the right product route

Team / trigger	Product route	What gets verified
Payment, wallet, payout, stablecoin, or agentic-commerce team	Recovery Design Partner Lab	timeout, lost response, duplicate or delayed webhook, retry, fallback, reconciliation, policy continuity, ledger divergence
Smart-contract or protocol team	State-Machine Review	escrow, settlement, release/refund, conservation, authorization, time boundaries, terminal states, ordering, replay
Engineering or audit-readiness team	CGQA evidence pipeline	reviewed model, bounded search, minimal counterexample, deterministic replay, provenance-bound evidence bundle

ContractGraph-QA is currently delivered productized-service first: the client buys a bounded verification result; the open-source engine produces the fixture, evidence map, verdict, and replay artifacts underneath.

---

Recovery Design Partner Lab

• Capacity: maximum 5 design partners
• Design-partner price: $1,000 fixed per one-boundary pilot
• Payment: $500 upfront after written scope agreement; $500 within 3 business days after acceptance of the initial evidence pack
• Scope: one named recovery boundary
• Target delivery window: five business days after the confirmed Boundary Brief, required inputs or authorized sandbox/test access, and upfront payment are accepted
• Communication: email-only and asynchronous
• Effort cap: up to 12 hours — 10 hours for the initial package and 2 hours for one bounded retest
• Retest: one bounded retest for an in-scope fix delivered within 14 calendar days

A typical boundary looks like:

intent / mandate
→ policy or authorization ALLOW
→ execution dispatched
→ timeout or ambiguous acknowledgement
→ provider / rail / wallet / chain / ledger evidence arrives
→ classify ZERO / ONE / UNKNOWN
→ retry, stop, or hold
→ deterministic evidence pack

The pilot includes:

• a compact expected-state contract;
• an evidence-precedence map;
• one local or sandbox-backed executable fixture;
• positive, negative, duplicate, delayed, out-of-order, and retry cases;
• deterministic pass/fail output with violation codes;
• a minimized counterexample when an unsafe path is reachable;
• bounded remediation guidance;
• one retest inside the agreed scope.

The initial fixture can start from public documentation, synthetic traces, status definitions, webhook schemas, and a declared authoritative-evidence rule. Production credentials, customer data, and real-value transactions are not required.

Lab workflow, checkpoints, and acceptance criteria → · Proof-backed commercial offer → · One-page Boundary Brief →

---

Why ordinary local signals are not enough

A component can be locally correct while the economic result remains unresolved:

• a policy engine can prove that an action was allowed;
• a credential layer can prove that capacity was reserved;
• an API can prove that a request was accepted;
• a webhook can prove that a provider state changed;
• a ledger can prove that one internal posting exists.

None of those signals alone necessarily proves the full cross-system outcome.

ContractGraph-QA therefore preserves the distinctions between:

logical operation identity
≠ concrete execution attempt
≠ idempotency / replay identity
≠ policy decision
≠ provider state
≠ external economic evidence
≠ internal ledger state
≠ reconciliation state
≠ retry permission

---

Run a local proof

The latest verified release is distributed as a GitHub release wheel.

python -m pip install \
  https://github.com/safal207/ContractGraph-QA/releases/download/v1.9.0/contractgraph_qa-1.9.0-py3-none-any.whl

cgqa demo --output-dir cgqa-demo
cgqa verify-bundle cgqa-demo/CGQA-005.evidence.zip

The demo is repository-owned, performs no external financial action, and is not presented as a third-party audit.

From a repository checkout, run the recovery benchmark:

git clone https://github.com/safal207/ContractGraph-QA.git
cd ContractGraph-QA

cgqa payment-recovery-evaluate \
  --scenario benchmarks/agent-payment-recovery-v0.1/cases/pass_committed_stop.json

The vendor-neutral benchmark includes seed cases for:

• committed outcome followed by stop;
• explicit failure followed by retry under the same logical operation;
• retry before reconciliation;
• idempotency drift across retry.

See Agent Payment Recovery Benchmark v0.1 →

---

Smart-contract quickstart

For an unfamiliar local smart-contract repository:

cgqa quickstart --target /path/to/project

The safe default does not execute project code. It inventories recognized sources and frameworks, computes a source fingerprint, surfaces bounded review prompts, plans the native test command, and writes:

<project>/.cgqa/quickstart/
  quickstart.json
  REPORT.md

Native tests remain explicit:

cgqa quickstart --target /path/to/project --run-native

Detected routes include Foundry, Hardhat, Truffle, Ape/Brownie/Vyper, Soroban, Anchor, Move, and Cairo/Scarb.

Universal quickstart documentation →

For a reviewed saved trace, TSSE keeps time, protocol topology, state, environment, actor, authority, and value changes separate:

cgqa tsse --model scenarios/tsse-payment-lifecycle.json

It checks exact-subject/evidence binding, monotonic time, causal continuity, declared boundary changes, and forbidden phase transitions. It does not execute or scan the target represented by the model.

TSSE transition model documentation →

Reviewed Cargo/Soroban, Foundry, Echidna, and Medusa replay observations can be compiled into that model while Slither findings remain static challenge seeds:

cgqa tsse-adapt \
  --capture scenarios/tsse-tools/foundry-capture.json \
  --profile scenarios/tsse-tools/foundry-profile.json

The separately reviewed profile anchors the expected subject, tool version, exit semantics, observation hash, and policy. The adapter reopens and hashes every declared source/tool artifact, parses the selected native receipt, computes the TSSE subject and hashes, locks all requirements on, and never treats a nested trace pass as a scan/security verdict.

TSSE tool adapter documentation →

To make verification coverage visible, keep intent, planned checks, and observed evidence in separate graph layers and compare them deterministically:

cgqa-graph-layers \
  --input outputs/soroban-five-graph-layers.json \
  --output outputs/soroban-five-graph-layer-diff.json

The diff exposes specification drift, actual bad transition geometry, and unexecuted or unexpected transitions; blocked/static-gap facts remain un-evidenced. An aligned result is a coverage signal, never a security verdict.

For high-capability audit workflows, run the separate Agent Action Guard before and after tool use. It binds the exact subject, authorization envelope, allowlists, independent monitor, denial/canary controls, receipts, and witness state without executing any command:

cgqa action-guard \
  --input scenarios/action-guard/soroban-five-preflight.json \
  --output outputs/action-guard-result.json

pass means the declared action is within the supplied envelope; hold keeps safe denials or evidence debt visible; fail marks a control bypass. This is a policy/evidence gate, not a scan or bounty verdict. See AGENT_ACTION_GUARD.md.

The LIVE_WRITE capability also requires a separate liveWriteApprovalRef; raising the envelope ceiling alone cannot authorize a live write. The tsse, tsse-adapt, graph-layers, and action-guard commands analyze saved evidence: they start no target process or network connection and write only requested result files. This boundary applies to those commands, not to the whole package: legacy run, engagement-run, quickstart --run-native, and RPC tools remain available under their existing controls. An isolated runner for the new evidence workflow is a separate roadmap item. See AGENT_ACTION_GUARD.md and the Astra-6 roadmap.

For end-to-end request, transaction-attempt, receipt/event, indexer, backend, and API continuity, see the Smart Contract Continuity Bridge v0.1. ContractGraph-QA produces reviewed evidence envelopes; the existing LTP verifier remains the only source of continuity verdicts.

For the reciprocal, file-first ContractGraph-QA ↔ LiminalQA adapter, including bounded-evidence export and non-authoritative candidate import, see LiminalQA interop v0.1.

Run the portable golden and fail-closed vectors before shipping any language adapter:

cgqa liminalqa-conformance

Application teams can validate that machine-readable report with the shipped consumer SDKs for TypeScript/JavaScript, Go, Java/JVM, and .NET. Together with the native Python, Rust, and Elixir runners, the same pinned boundary is usable from eight language ecosystems without merging verdict authority.

Download SDK v0.1.0 → · Open the SDK matrix → · Review package and registry status → · Review the adoption completion gates →

---

What the engine produces

AUTHORIZED SCOPE / EXACT SUBJECT
      ↓
REVIEWED STATE + ACTION + AUTHORITY MODEL
      ↓
EXPLICIT INVARIANTS / FORBIDDEN STATES
      ↓
BOUNDED SEARCH + NEGATIVE CONTROLS
      ↓
MINIMAL VIOLATING PATH OR BOUNDED NO-FINDING
      ↓
DETERMINISTIC REPLAY
      ↓
OBSERVED PRE/POST EVIDENCE
      ↓
PROVENANCE-BOUND FINDING + REPORT + ZIP
      ↓
INDEPENDENT VERIFICATION
      ↓
FIX → EXACT RETEST

Every declared invariant is classified as exactly one of:

violated
not_found_within_bound
inconclusive

not_found_within_bound is bounded evidence, not a security certification. inconclusive remains unresolved and fails closed.

---

What makes ContractGraph-QA different

• Stateful, not function-by-function. It searches sequences of actors, actions, retries, ordering, and time changes.
• Economic-effect oriented. It tracks the reachable effect, not only the local return value.
• Evidence first. Findings carry minimal paths, observed state, identity, provenance, and replay instructions.
• Honest assurance language. Missing coverage does not silently become a clean PASS.
• Retestable. The same historical path can be replayed after a fix, followed by alternate-path search.
• Authorization bounded. Public code or an address is not treated as permission to test a production target.

---

Advanced operator workflow

cgqa doctor --require-forge
cgqa init-engagement acme-financial-flow
# Replace generated TODOs only after explicit scope and authorization review.
cgqa engagement-run --config engagements/acme-financial-flow/cgqa.toml
cgqa verify-engagement-bundle \
  engagements/acme-financial-flow/evidence/engagement.evidence.zip

The generated scaffold starts fail-closed until the operator supplies the authorization, target, state hash, action model, invariants, and capture adapter.

Key documents:

• Recovery Design Partner Lab
• External Recovery Proof Check
• One-page Boundary Brief
• Synthetic Recovery Case Study
• Product runtime
• CLI reference
• Engagement workflow
• Adapter manifest
• LiminalQA interop v0.1
• Evidence distribution
• Client proof pack
• Agent verification protocol
• TSSE transition model
• TSSE reviewed tool adapters

---

Commercial workflow

question
→ mirror boundary
→ confirm Boundary Brief
→ $500 upfront
→ paid fixture
→ evidence pack
→ acceptance
→ $500 balance
→ bounded retest
→ product learning

A good first question is:

After dispatch returns an ambiguous result, which evidence is authoritative before another monetary attempt is permitted: platform state, external rail, processor or wallet receipt, customer ledger, or an explicit UNKNOWN reconciliation hold?

A one-line answer is enough to begin the mirror. The paid scope starts only after the one-page Boundary Brief is confirmed and the upfront payment is accepted.

---

Product status

• Python 3.11+
• Apache-2.0
• Installable cgqa CLI
• Deterministic evidence bundles
• Independent bundle verification
• Universal smart-contract quickstart
• Agent-payment recovery benchmark
• Current release: v1.9.0

Release artifacts, checksums, and release notes are published under GitHub Releases.

---

Scope and safety

ContractGraph-QA may be used on:

• repositories and fixtures you own;
• client systems with explicit written authorization;
• public bug-bounty assets strictly within their published scope and rules;
• public documentation for non-invasive modeling and synthetic fixture design.

It does not claim that:

• bounded search proves an arbitrary system secure;
• selected invariants are complete;
• a webhook, status endpoint, receipt, ledger record, or chain observation is authoritative without a declared contract;
• a clean bounded result means no vulnerability exists;
• a QA engagement is equivalent to a formal full-platform security audit.

Never commit RPC secrets, private keys, seed phrases, customer data, or client credentials.

See SECURITY.md.

License

Apache-2.0