CirculatingPolicyResolver

CirculatingPolicyResolver is a reusable GenLayer Intelligent Contract that answers one deliberately narrow question:

Under a methodology committed in advance, which entries in a bounded, caller-supplied supply partition count as circulating at one fixed block?

It is contract-only. There is no frontend.

What it does

A creator registers:

• one chain, token, and immutable block reference;
• an integer reported total supply in indivisible base units;
• a natural-language inclusion/exclusion methodology;
• two to twelve sorted candidate accounts or categories;
• an integer balance and frozen evidence snapshot for every candidate; and
• an explicit assertion that the candidates form a complete, disjoint partition.

The contract deterministically rejects a partition unless every balance is a canonical non-zero decimal integer, all arithmetic fits u256, and the balances sum exactly to the reported supply. GenLayer validators then independently classify every candidate as included, excluded, or indeterminate. They also mark the subset whose indeterminacy comes from directly conflicting policy rules.

The contract derives all totals and one status:

• RESOLVED: every candidate is included or excluded;
• POLICY_CONFLICT: at least one candidate is indeterminate because applicable methodology provisions conflict; or
• INSUFFICIENT_EVIDENCE: at least one candidate remains indeterminate for another reason.

What it does not do

This contract does not enumerate arbitrary blockchain state, discover every holder, prove that the registered universe is globally complete, authenticate a snapshot, fetch current URLs, calculate current market capitalization, set a token price, or decide solvency. An evidence_url is attribution only; validators classify the frozen evidence_snapshot committed in the fingerprint.

The output therefore means “resolved under this exact bounded record and methodology,” never “the universally correct circulating supply.”

Contract API

Constructor:

CirculatingPolicyResolver(policy_version: u256)

Write methods:

register_case(
    case_key,
    chain_reference,
    token_reference,
    token_symbol,
    block_reference,
    unit_decimals,
    reported_total_supply_units,
    methodology_text,
    candidates_json,
    universe_assertion,
) -> case_id

audit_case(case_id) -> None

Only the case creator may trigger its first audit. The first successful audit is immutable.

Consumer gate:

matches_resolved_supply(
    case_id,
    expected_case_fingerprint,
    expected_circulating_supply_units,
) -> bool

The gate returns true only for a structurally valid stored case and audit, exact fingerprint, RESOLVED status, zero indeterminate/conflict masks, and the exact expected integer included supply. It returns false for malformed, missing, conflicting, insufficient, altered, or mismatched records.

Other views provide case/audit records, counts, stable indexes, IDs, and policy metadata. The ABI contains 12 methods: 10 view and 2 write.

Candidate JSON

Candidate IDs must be unique, uppercase canonical codes, and sorted ascending. Every object has exactly these fields:

[
  {
    "candidate_id": "PUBLIC",
    "category": "PUBLIC_DISTRIBUTION",
    "account_scope": "0x... public-distribution vault",
    "balance_units": "600",
    "evidence_url": "https://evidence.example.org/fixed-block-record",
    "evidence_snapshot": "At the registered block, the exact token and account scope held 600 base units without issuer transfer restriction."
  },
  {
    "candidate_id": "TREASURY",
    "category": "ISSUER_TREASURY",
    "account_scope": "0x... issuer-controlled treasury",
    "balance_units": "400",
    "evidence_url": "",
    "evidence_snapshot": "At the registered block, the exact token and account scope held 400 base units under issuer control."
  }
]

The required assertion is exactly:

CALLER_ASSERTS_COMPLETE_DISJOINT_PARTITION_AT_REGISTERED_BLOCK

It is an attributable caller assertion, not validator proof.

Verification

Frozen contract source:

• File: contracts/circulating_policy_resolver.py
• SHA-256: 7B081BD07497564F18901D7F85F07CA1B7282015E15411388B3BED8EBF87F540
• Size: 42,296 bytes
• Pinned runner: py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6

Completed local gates:

• GenVM lint and schema validation: pass
• strict typecheck: zero diagnostics
• direct tests: 101 passed
• five-validator GLSim integration tests: 5 passed
• deployment-helper strict TypeScript check: pass

Verified StudioNet evidence:

• Contract: 0x734d3f0449E926b32e7E025205736b5d276cf85c
• Deployment transaction: 0xdaeea647d730804e3184e9ecc05eec8d33a0d7a0a783168d6a074ad96b3cbee1
• Deployment lifecycle: FINALIZED; consensus: MAJORITY_AGREE; execution: SUCCESS
• Deployed-source SHA-256: byte-identical to the frozen source above
• Smoke registration transaction: 0x25e539be75f5f4735b1d065167a8363ba2e4980ec03864174be4b5942947244e
• Smoke audit transaction: 0xf2304b89e7ae5977725d53ad1456379cf1767f7d71deb62c00117dae1ff0be28
• Final smoke result: RESOLVED, included 600, excluded 400, indeterminate 0; exact fingerprint gate true, altered fingerprint gate false, and wrong-supply gate false

All three StudioNet transactions are finalized and recorded in deployments/studionet.json.

Verified Bradbury evidence for the same frozen source:

• Contract: 0xB4c15B82C30961735Dbf1e0083E7a79c0FD6EFb8
• Deployment transaction: 0x52039a9e543557b57cb6adc0c26cc5dbc233e5283846894c4e416a4e3116ab6b
• Smoke registration transaction: 0x543cd0957656a4367f569c2cb72be32e7185a09199b6e205f6b42c4b801150e6
• Smoke audit transaction: 0x9aaba06a3ac04a729a3ef5d352c3ae4daeba8706aba3078e7087f89b9fd25127
• All three receipts: FINALIZED, AGREE, FINISHED_WITH_RETURN, with five of five validator votes agreeing
• Deployed source: 42,296 bytes and byte-identical to the frozen SHA-256
• Final smoke result: RESOLVED, included 600, excluded 400, indeterminate 0; exact fingerprint gate true, altered fingerprint gate false, and wrong-supply gate false

Bradbury state was independently read at LATEST_FINAL; the complete record is deployments/bradbury.json. Both network records are finalized and passing. See HANDOFF.md for repository setup, verification, and deployment guidance.

Clone and verify

Clone this repository, then work from its root:

git clone <private-repository-url> circulatingpolicyresolver
Set-Location circulatingpolicyresolver
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
pnpm install --frozen-lockfile
python -m pytest tests/direct -v
pnpm run typecheck:deploy

The repository intentionally excludes local dependencies, virtual environments, compiled deployment helpers, caches, generated artifacts, environment files, wallets, and credentials. Copy .env.example only as a reference for non-secret runtime controls; the GenLayer CLI manages the active account separately.

License

MIT. See LICENSE.