This directory contains all design docs, API references, and operational guides for the Credence Soroban contracts.
| Document | Audience | Summary |
|---|---|---|
| architecture.md | Contributor / Operator | System-wide component diagram, data flows, trust boundaries |
These compact pages list the main public entrypoints, required roles, and backend integration notes for each contract crate. They are intended to be quick review aids for contributors and downstream integrators.
- credence-bond.md
- credence-delegation.md
- credence-timelock.md
| access-control.md | Contributor / Integrator | RBAC modifiers, entrypoint authority matrix, event schemas |
| CONSTRUCTOR_PATTERNS.md | Contributor | One-shot
initializepattern: re-init guard, auth, storage, event | | DEDUP_POLICY.md | Contributor | When we dedupe input, when we reject on duplicate, and why | | admin-roles.md | Operator / Integrator | Hierarchical admin system (SuperAdmin / Admin / Operator), assignment, suspension, rotation | | HISTORICAL_ROLES.md | Operator / Auditor | How role assignments are tracked over time, event stream for indexing, audit queries | | governance.md | Operator | Multi-sig pause, emergency mode, upgrade flow | | upgrade.md | Operator | Contract upgrade procedure, data migration, verification | | BYTES32_CANONICALISATION.md | Contributor / Integrator | Canonicalisation rules for BytesN<32> and zero value rejection | | TIME_UNITS.md | Contributor | Time representation (seconds, days, epochs) and mocking time in tests | | ADMIN_EPOCHS.md | Contributor | Admin pause-proposal epochs: motivation, bumping cadence, stale-epoch guard | | SIGNER_EPOCHS.md | Contributor | Multisig signer pause-proposal epochs: motivation, bumping cadence,StaleSignerEpochguard |
| Document | Audience | Summary |
|---|---|---|
| credence-bond.md | Integrator | High-level overview of the identity bond contract |
| credence_bond_api.md | Integrator | Complete API reference (entrypoints, types, errors) |
| BOND_ISSUANCE.md | Contributor | Who can call create_bond/top_up and the conditions enforced |
| bond-state-transitions.md | Contributor | State machine for bond lifecycle |
| tier-system.md | Contributor / Operator | Auto-upgrade/downgrade tier logic |
| rolling-bonds.md | Integrator | request_withdrawal / renew_if_rolling flow |
| early-exit.md | Integrator | Penalty calculation, treasury routing |
| slashing.md | Contributor / Operator | Slash entrypoints, available-balance enforcement |
| slashing-history.md | Integrator / Auditor | Append-only slash record storage |
| withdrawal.md | Integrator | Normal and early withdrawal flows |
| bond-invariants.md | Contributor | Mathematical invariants tested in fuzz suite |
| bond-upgrade-auth-checklist.md | Operator / Auditor | Pre-upgrade authorization & safety checklist |
| bond-drift-detection.md | Operator | Detecting storage drift across deployments |
| bond-introspection.md | Integrator | Read-only view functions |
| bond-crate-layout.md | Contributor | Module map, public re-exports |
| bond-token-custody.md | Operator | Token custody semantics during bond lifecycle |
| fixed-duration-bond.md | Integrator | Non-rolling bond variant |
| multi-identity-bonds.md | Integrator | Multiple identities per bond |
| budget-ceilings.md | Operator | Protocol fee caps |
| cooldown.md | Integrator | Cooldown periods between operations |
| expiry-boundaries.md | Contributor | Ledger timestamp edge cases |
| fees.md | Integrator | Fee calculation and collection |
| fund-flow.md | Operator | Token flows through the contract |
| liquidation.md | Operator | Liquidation mechanics |
| SNAPSHOT_GENERATIONS.md | Operator | Liquidation-scan snapshot generations: semantics and when they bump |
| treasury.md | Operator | Treasury configuration and sweeping |
| TREASURY_INVARIANTS.md | Contributor / Auditor | Treasury flow invariants and balance tracking |
| weighted-attestations.md | Contributor | Attestation weighting system |
| Document | Audience | Summary |
|---|---|---|
| delegation.md | Integrator | Delegation types, expiry, revocation, cleanup |
| credence_delegation_api.md | Integrator | Full API reference |
| delegation-failure-modes.md | Contributor | Error code taxonomy, replay protection |
| delegation-summary-view.md | Integrator | Aggregated delegation queries |
| LEASE_SIGNATURES.md | Integrator | Signature format, scheme tags, and verification model for relayed lease-style payloads |
| Document | Audience | Summary |
|---|---|---|
| EVENTS.md | Integrator / Indexer | Canonical event catalog with topics and payloads |
| event-indexing.md | Backend Consumer / Indexer | Indexing guidance, idempotency patterns, versioning strategy, query patterns |
| EVENT_INDEXING_MIGRATION.md | Operator | Migration guide for indexer schema changes |
| indexer-replay-contract.md | Operator | Replay contract for backfilling |
| Document | Audience | Summary |
|---|---|---|
| security.md | Contributor / Auditor | Security model, trust assumptions |
| THREAT_MODEL.md | Auditor | STRIDE analysis, mitigations |
| auth-tree-threats.md | Auditor | Auth tree specific threats |
| credence_bond ATTACK_TREE | Contributor / Auditor | Per-entrypoint STRIDE attack tree for the bond contract |
| credence_delegation ATTACK_TREE | Contributor / Auditor | Per-entrypoint STRIDE attack tree for the delegation contract |
| reentrancy.md | Contributor | Reentrancy guards, patterns |
| arbitration.md | Contributor | Dispute resolution flow |
| dispute-resolution.md | Integrator | Arbitration API |
| emergency.md | Operator | Emergency mode, drain, audit log |
| emergency-drain.md | Operator | Emergency withdrawal procedure |
| pause-proposal-view.md | Integrator | Pause multi-sig proposal view |
| pause-signer-invariant.md | Contributor | Pause signer guarantees |
| pause-state-snapshots.md | Contributor | Pause state serialization |
| SECURITY_SCANNING.md | Contributor | cargo audit workflow, triage |
| Document | Audience | Summary |
|---|---|---|
| DEPLOYMENT.md | Operator | Testnet/mainnet deploy runbook, cross-contract wiring |
| admin-cli.md | Operator | CLI for admin operations |
| STORAGE_KEYS.md | Contributor / Operator | Storage key enum, TTL policies |
| STORAGE_KEY_LAYOUT.md | Contributor | Per-contract storage key catalog and collision-safety rules |
| storage-ttl.md | Contributor | TTL extension strategies |
| wasm-reproducibility.md | Operator | Reproducible build verification |
| wasm-size-budget.md | Contributor | Per-contract size ceilings, CI gate |
| Document | Audience | Summary |
|---|---|---|
| testing.md | Contributor | Test organization, patterns, coverage |
| TEST_HELPER_LIBRARY.md | Contributor | Available test helpers in the testutils crate and feature-gated helpers |
| doctest-style.md | Contributor | Doc-test conventions |
| fuzz-testing.md | Contributor | Cargo-fuzz targets, invariants |
| chaos-testing.md | Contributor | Chaos engineering scenarios |
| differential-testing.md | Contributor | Cross-implementation diff testing |
| tier-fuzz.md | Contributor | Tier system fuzz invariants |
| Document | Audience | Summary |
|---|---|---|
| datakey-fingerprint.md | Contributor | Storage key fingerprinting for upgrades |
| ARITHMETIC_HELPERS.md | Contributor | Complete reference for all credence_math arithmetic helpers, rounding modes, and overflow semantics |
| decimal-handling.md | Contributor | Fixed-point arithmetic patterns |
| PERCENT_SPLIT_MODEL.md | Integrator | Multi-recipient percent splits in bps; must sum to 10_000 |
| error-codes-wire.md | Integrator | On-chain error code → off-chain mapping |
| errors.md | Contributor | Error enum definitions |
| proposal-id-derivation.md | Contributor | Deterministic proposal ID scheme |
| registry.md | Integrator | Contract registry pattern |
| signature-scheme-upgrade.md | Contributor | Ed25519 → secp256k1 migration plan |
| status-snapshot.md | Integrator | On-chain status snapshots |
| supported-tokens.md | Operator | Allowlisted token configuration |
| templates.md | Contributor | Code generation templates |
| token-integration.md | Integrator | Adding new token types |
| verifiers.md | Integrator | Verifier registration and stake |
| arbitration_api.md | Integrator | Arbitration contract API |
| credence-timelock.md | Integrator | Timelock contract |
| multisig.md | Integrator | Multi-sig wallet contract |
| migration-prohibitions.md | Contributor | What we forbid during migrations: error code renumbering, storage key changes, event topic shifts, and other silent breakage |
| known-simplifications.md | Contributor / Auditor | Intentional simplifications and production paths |
| Document | Audience | Summary |
|---|---|---|
| GAS_BUDGET_BREAKDOWN.md | Contributor | Per-contract gas cost tables for every entrypoint |
| bond_gas_benchmarks.md | Contributor | Bond contract gas costs |
| dispute_resolution_gas_benchmarks.md | Contributor | Arbitration gas costs |
See CONTRIBUTING.md for code style, testing requirements, and PR process. Maintainer review and routine contributor support hours are defined in BUSINESS_HOURS.md.
- Root README — Workspace overview, build/test commands
- CHANGELOG.md — Release history