OpenTrust Core

English | 简体中文

OpenTrust Core is a deterministic, fixture-based prototype for verifying whether observed Ethereum transaction effects match a declared user or agent intent before signing.

Current release: v0.1.0.

What OpenTrust Is Not

OpenTrust is not a smart contract audit, a malicious-address database, a transaction simulator, or a probabilistic risk scorer. It does not sign, broadcast, custody assets, call Ethereum RPC, or decide whether a contract is safe. PASS only means the supplied observed effects satisfy the declared intent under the implemented assertions.

30 Second Example

M6 includes synthetic smoke fixtures for /v1/verify:

docker compose up --build
curl -X POST http://localhost:8000/v1/verify \
  -H "Content-Type: application/json" \
  --data @examples/requests/verify_pass.json

curl -X POST http://localhost:8000/v1/verify \
  -H "Content-Type: application/json" \
  --data @examples/requests/verify_violation.json

curl -X POST http://localhost:8000/v1/verify \
  -H "Content-Type: application/json" \
  --data @examples/requests/verify_unknown.json

Or run the local in-process demo:

python scripts/run_demo.py

All demo and golden data is synthetic. It is not real chain simulation output and is not an address reputation dataset.

Status Meanings

PASS means at least one applicable assertion passed and no supported assertion failed or returned unknown.

VIOLATION means at least one supported assertion has explicit evidence of a declared intent mismatch.

UNKNOWN means evidence is missing, incomplete, conflicting, unsupported, or no executable assertion exists. UNKNOWN is not safe.

Architecture

Wallet / DApp / AI Agent
          |
          v
      OpenTrust API
          |
          +--> Request Validator
          +--> ERC-7730 v2 Calldata Adapter
          +--> Fixture / Effects Provider
          +--> Effect Aggregator
          +--> Assertion Engine
          +--> Policy Mapper
          v
 Structured Verification Result

/v1/verify-effects validates caller-supplied ObservedEffects.

/v1/verify uses the offline FixtureEffectsProvider to look up synthetic effects by transaction fingerprint.

/v1/erc7730/derive-intent converts a trusted, locally supplied ERC-7730 v2 calldata subset descriptor into a DeclaredIntent. Descriptor derivation cannot produce PASS.

Quick Start

python -m pip install ".[dev]"
uvicorn app.main:app --reload

OpenAPI is available at http://localhost:8000/docs when the service is running.

Support Matrix

Area	Status
Python 3.12 project config	Present
FastAPI app	Present
/health and /ready	Present
Domain schemas and raw amount validation	Present
Effect identity and aggregation	Present
Five core assertions and policy mapping	Present
/v1/verify-effects	Present
/v1/verify with fixture provider	Present
/v1/erc7730/derive-intent limited calldata adapter	Present
30 deterministic golden fixtures	Present
Real Ethereum RPC or remote simulation provider	Not included in v0.1.0

ERC-7730 Compatibility

M5/M6 support the active ERC-7730 v2 schema URL as a calldata subset adapter for ERC-20 transfer, ERC-20 approve, Uniswap V2 swapExactTokensForTokens, and selected Uniswap V3 exactInputSingle tuple signatures. SUPPORTED means parseable by this subset, not verified or trusted. Successful derivation includes ERC7730_PROVENANCE_UNVERIFIED.

See docs/erc7730.md.

Security Boundaries

OpenTrust treats API input, descriptors, token metadata, fixture data, and provider output as untrusted. It never promotes incomplete or unknown critical evidence to PASS.

See docs/security-model.md and docs/limitations.md.

Tests

pytest -q
pytest --cov=app --cov-branch --cov-report=term-missing
python3 -m ruff check .
python3 -m ruff format --check .
python3 -m mypy
python3 -m compileall -q app scripts tests

Golden fixtures:

python scripts/validate_fixtures.py
python scripts/update_golden.py

scripts/update_golden.py is dry-run by default. Use --write only after intentionally accepting a deterministic semantics change.

Roadmap

See docs/roadmap.md. The v0.1.0 target stops at fixture-based deterministic verification and limited ERC-7730 derivation.

Contributing

See CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.