Repository navigation
Coxy Product Specification
Document type: Product, architecture, engineering, security, integration, and delivery specification
Version: 1.0.0
Date: 9 August 2026
Company: Coxygen Global
Developer: Bernard Sibanda
Project: Coxy Wallet / Coxy Financial Platform
Road Map Road Map
Application license: MIT License
Primary implementation stack: Vanilla JavaScript, HTML, CSS, PHP, and MySQL
Architecture style: Modular, atomic, loosely coupled, provider-driven, event-aware, security-first, and horizontally scalable
Target product modes: Silver, Gold, Diamond, and Platinum
Important implementation rule: Coxy is one platform with four capability modes. Silver, Gold, Diamond, and Platinum MUST NOT become four independent codebases. Every higher mode reuses the same tested core and enables additional modules through capability profiles and feature flags.
Important regulatory rule: Coxy can provide identity, KYC/AML orchestration, privacy-preserving proofs, policy enforcement, Travel Rule support, sanctions integrations, reporting integrations, and programmable-asset controls. Those technical capabilities do not automatically make Coxy, a token issuer, or a financial partner legally compliant or licensed in every jurisdiction. Regulated financial services must be enabled only through the licences, authorisations, policies, and institutional partnerships applicable to each market and payment corridor.
- 🌍 Product Vision and Purpose
- 🧭 Product Principles
- 🏅 Four Coxy Modes
- 🏗️ Platform Architecture
- 🧩 Atomic Module Standard
- 🧱 Repository and Folder Structure
- ⚙️ Shared Coxy Core
- 🥈 Silver Mode — Training and New-User Wallet
- 🥇 Gold Mode — Full Cardano and External Wallet Interoperability
- 💎 Diamond Mode — Identity, Programmable Assets, Compliance, and Privacy
- 🏆 Platinum Mode — Global Finance, RealFi, Multi-Chain, Stablecoins, Banking, and Remittances
- 🤖 AI Assistant and AI Guardian
- 🔐 Security Architecture
- 🪪 SSI, CIP-0170, KERI, ACDC, and vLEI
- 🪙 Programmable Assets and CIP-113
- 🌑 Privacy and Midnight
- 🧾 KYC, AML, CFT, Sanctions, and Policy Engine
- 🏠 Real-World Assets
- 🌐 Multi-Chain Architecture
- 💵 Stablecoins and Fiat
- 🌍 Cross-Border Remittances and Banking
- 🏦 RealFi and Financial Protocol Integrations
- 🗄️ MySQL Data Architecture
- 🔌 APIs, Providers, Events, and Integration Contracts
- 💻 Reference Code Patterns
- 🧪 Code Quality and Test Strategy
- 📜 Logging, Auditability, and Observability
- 📈 Performance, Availability, and Scalability
- 🛡️ Security Review and Audit Requirements
- 👥 Resources Required
- 🚀 Beginning-to-End Delivery Plan
- ✅ Release Gates and Acceptance Criteria
- 🤝 Multi-Developer Contribution Model
- 📱 Web, iOS, and Android Scope
- 📄 MIT Licence
- 📚 Glossary
- 🔗 Sources and Reference Links
Coxy began as a simplified Cardano training wallet designed to help students and first-time cryptocurrency users understand wallet creation, addresses, transactions, tokens, staking, and blockchain concepts without being overwhelmed by advanced terminology. That educational purpose remains strategically important. The product must continue to provide a safe and approachable entry point into Cardano while growing into a platform that can serve experienced users, businesses, institutions, asset issuers, remittance customers, and users who already keep their funds in other wallets.
The long-term product is therefore not merely a cryptocurrency wallet. Coxy is intended to become a modular financial operating layer in which wallets, signers, identities, credentials, programmable assets, privacy systems, blockchains, stablecoins, fiat payment rails, banks, remittance providers, RealFi protocols, and artificial-intelligence services can be connected through stable internal interfaces. The purpose of the architecture is to make new technologies additive. A new Cardano Improvement Proposal, hardware wallet, privacy network, blockchain, stablecoin, bank, identity provider, or payment institution should normally be integrated by adding or replacing a module or provider rather than rewriting the application.
Coxy will be presented through four capability modes. Silver preserves the simple training wallet. Gold provides complete Cardano interoperability and professional wallet functionality. Diamond adds verifiable identity, compliance orchestration, programmable assets, real-world asset controls, and privacy capabilities. Platinum adds global finance, multi-chain assets, stablecoins, fiat, bank integrations, cross-border remittances, settlement routing, and RealFi services. AI assistance and AI-supported security are shared capabilities across all four modes, but artificial intelligence is never allowed to become the cryptographic authority that signs transactions or bypasses deterministic security policy.
The product must be suitable for multiple independent development teams. The implementation therefore uses a deliberately small web stack: vanilla JavaScript, semantic HTML, CSS, PHP, and MySQL, without an application framework. Small audited libraries may be used when implementing cryptography, Cardano serialization, KERI, hardware-wallet transport, standards compliance, or testing, but business modules must not depend on a large frontend or backend framework. This keeps deployment simple, makes code ownership clear, reduces dependency risk, and allows developers with ordinary web skills to participate.
Silver, Gold, Diamond, and Platinum are capability profiles. A user can move between modes without migrating to a different codebase or creating an unrelated account. Higher modes enable additional navigation, adapters, policy checks, providers, and workflows while retaining the same shared services and security rules.
Every advanced module must be optional. If identity, programmable assets, Midnight, remittances, RealFi, AI, or a third-party provider is unavailable, ordinary Coxy Cardano wallet functionality must continue to operate. Feature flags, module health checks, and graceful degradation are therefore mandatory.
Each business module owns its frontend, off-chain logic, backend logic, SQL migrations, server-side tasks, integrations, tests, documentation, and on-chain assets where applicable. One module MUST NOT write directly into another module's private tables or import another module's internal files. Communication happens through declared interfaces, HTTP/service calls, shared read-only contracts, or events.
A Cardano seed, Cardano private key, KERI secret, issuer administration key, hardware-wallet secret, banking credential, or recovery secret must never be passed through a general event bus, written to logs, sent to AI, inserted into analytics, or exposed through normal module APIs. Modules receive the minimum signing capability that they require, not raw keys.
Coxy-managed non-custodial wallet keys must remain under the user's control. Server services may provide indexing, metadata, token information, exchange rates, AI explanations, identity lookup, KERI discovery, compliance orchestration, quotes, and transaction submission, but a server outage must not transform Coxy into a custodial wallet or make the user's seed dependent on a Coxy database.
Standards that are still evolving, especially CIP-0170 and CIP-113, must be behind versioned interfaces. The codebase must not scatter assumptions about a draft standard across UI, database, and transaction code. A codec or adapter can be upgraded while the rest of Coxy continues to use a stable internal representation.
Diamond and Platinum privacy features exist so the user or institution can disclose the minimum information required for a lawful purpose. Privacy must never be marketed or implemented as a mechanism for hiding information from a party that is legally entitled to receive it. Midnight and zero-knowledge proofs are therefore integrated through policy-aware disclosure workflows.
AI may explain, summarize, detect unusual patterns, classify risks, recommend actions, guide new users, and prepare transaction plans. AI MUST NOT independently sign a transaction, export a secret, change a recipient, change an amount, disable policy, override sanctions controls, approve a seizure, or approve a bank transfer. Deterministic rules and explicit human/device authorization remain authoritative.
Threat modeling, test vectors, dependency review, logging, audit trails, reproducible builds, penetration testing, contract auditing, recovery testing, and incident response are not end-stage tasks. Every module definition includes security and testing obligations from the beginning.
| Mode | Product Purpose | Required Capabilities |
|---|---|---|
| 🥈 Silver | Silver gives students and new users a simple Cardano wallet and an educational environment. It deliberately hides unnecessary complexity while still using production-quality wallet security. | Coxy-managed Cardano wallet, recovery, ADA and native assets, minting where currently supported, transactions, staking basics, learning content, transaction explanations, AI assistance, and AI-supported security warnings. |
| 🥇 Gold | Gold serves experienced Cardano users and users who already hold funds in another compatible wallet or hardware device. It extends the simple Silver experience with professional Cardano functionality while allowing users to retain control of assets held in external wallets. | Everything in Silver, advanced Cardano controls, CIP-30 provider support, external CIP-30 wallet connections, wallet capability negotiation, hardware signer adapters such as Trezor, governance support, advanced dApp use, advanced transaction inspection, and multiple account and wallet-session handling. |
| 💎 Diamond | Diamond serves business, identity, Real-World Asset (RWA), regulated-asset, compliance, and privacy-oriented use cases. It builds on Gold without replacing the underlying wallet architecture and adds identity, policy, programmable-asset, and privacy capabilities as independently controlled modules. | Everything in Gold, CIP-0170 identity, KERI, KEL, ACDC, credential verification, optional vLEI support, KYC and AML provider adapters, the shared Coxy Policy Engine, CIP-113 programmable-asset support behind appropriate maturity and security gates, RWA controls, Midnight privacy adapters, selective disclosure, and business identity workflows. |
| 🏆 Platinum | Platinum is Coxy's global financial mode. It combines Coxy's identity, privacy, policy, compliance, and programmable-asset systems with multiple blockchain networks, stablecoins, fiat services, banking integrations, cross-border payments, RealFi, and institutional financial services. | Everything in Diamond, Bitcoin, Ethereum, and future blockchain adapters, advanced stablecoin services, fiat accounts through appropriately licensed providers, foreign exchange services, cross-border remittances, settlement routing, financial-institution and banking integrations, Travel Rule support, reconciliation, RealFi adapters, treasury features, liquidity and routing services, and consolidated global portfolio views. |
Important stablecoin architecture note: Stablecoins are not restricted to Platinum merely because advanced stablecoin services are a Platinum capability. Gold must already recognize, display, receive, and transfer supported Cardano stablecoins in the same way that it handles other supported Cardano assets.
Diamond extends stablecoin functionality with identity-aware, compliance-aware, privacy-aware, programmable, and RWA-oriented workflows. This can include credential requirements, KYC and AML policy checks, programmable transfer rules, selective disclosure, issuer controls, and other regulated-asset functionality.
Platinum adds the global financial layer. This includes cross-chain stablecoin holdings, fiat conversion, foreign exchange, payments, treasury management, settlement routing, banking integration, liquidity management, and domestic or cross-border remittance services.
Coxy must maintain explicit security zones rather than storing every sensitive capability in a single vault.
The zones can cooperate, but secrets do not cross them. For example, the Identity module may request a Cardano transaction signature from a WalletSession, but it does not receive the Cardano seed. The remittance module may receive a verified KYC status from the Compliance module, but it does not receive the customer's complete KYC document set unless a specific regulated workflow requires and authorizes that disclosure.
The application platform uses vanilla JavaScript, HTML, CSS, PHP, and MySQL. There is no frontend application framework and no PHP application framework. Browser-native Web Components may be used because they are part of the web platform rather than a third-party framework. PHP uses standard language features and PDO. MySQL owns durable relational state.
Blockchain contracts are a necessary exception to the list of application languages because Cardano and Midnight execute chain-native compiled programs, not PHP or browser JavaScript. Each blockchain module therefore isolates contract source and compiled artifacts inside its own onchain/ directory. For Cardano, Coxy may continue using a JavaScript-driven compiler/tooling path such as its existing Helios-based approach so that transaction construction remains JavaScript-centric while the final on-chain artifact is valid Plutus Core/CBOR. Midnight contracts must remain isolated behind a Midnight adapter and its required contract tooling. No chain-specific contract language is allowed to leak into ordinary frontend or PHP modules.
Every production module MUST follow the same minimum layout and contract. A module is considered atomic when it can be enabled, disabled, tested, migrated, documented, deployed, and reasoned about without requiring developers to edit unrelated module internals.
modules/<module-name>/
├── README.md
├── module.json
├── CHANGELOG.md
├── LICENSE-NOTICE.md
│
├── public/
│ ├── index.html
│ ├── index.js
│ ├── index.css
│ ├── components/
│ └── assets/
│
├── offchain/
│ ├── index.js
│ ├── service.js
│ ├── types.js
│ ├── validators.js
│ └── codecs/
│
├── onchain/
│ ├── README.md
│ ├── src/
│ ├── artifacts/
│ ├── scripts/
│ └── test-vectors/
│
├── backend/
│ ├── api/
│ │ ├── routes.php
│ │ └── controllers/
│ ├── service/
│ ├── repository/
│ ├── validation/
│ └── security/
│
├── server/
│ ├── bootstrap.php
│ ├── config.example.php
│ ├── cron/
│ ├── workers/
│ └── health.php
│
├── sql/
│ ├── schema.sql
│ ├── migrations/
│ ├── indexes.sql
│ ├── rollback/
│ └── fixtures/
│
├── integrations/
│ ├── contracts/
│ ├── adapters/
│ └── mocks/
│
├── tests/
│ ├── unit/
│ ├── integration/
│ ├── property/
│ ├── security/
│ ├── e2e/
│ └── fixtures/
│
├── docs/
│ ├── architecture.md
│ ├── api.md
│ ├── threat-model.md
│ ├── operations.md
│ └── runbook.md
│
└── logs/
└── .gitkeep
The public/ directory contains only the user interface owned by the module. The offchain/ directory contains browser-safe domain logic such as codecs, transaction-plan creation, and validation that does not require the PHP server. The onchain/ directory contains blockchain-specific scripts and compiled artifacts when the module requires them. The backend/ directory contains PHP domain services, API controllers, repositories, and validation. The server/ directory contains process entry points, scheduled work, worker scripts, and health checks. The sql/ directory contains the module's complete database lifecycle. The integrations/ directory is the only place where third-party or cross-module provider adapters should normally be implemented.
Each module declares its capabilities and dependencies through module.json rather than through hidden imports.
{
"id": "coxy.identity",
"version": "1.0.0",
"modes": ["diamond", "platinum"],
"requires": ["coxy.wallet-session", "coxy.policy", "coxy.audit"],
"optional": ["coxy.midnight", "coxy.vlei"],
"permissions": [
"wallet.read_public",
"wallet.request_sign",
"identity.store_encrypted"
],
"events": {
"publishes": ["identity.created", "credential.verified"],
"subscribes": ["wallet.account_changed"]
},
"healthEndpoint": "/api/identity/health"
}The module loader must reject circular hard dependencies. Optional integrations must use capability checks. A Diamond module may ask whether Midnight is available, but the Identity module must still work when the privacy module is disabled.
- A module MUST NOT import a file from another module's
backend/,offchain/,sql/, oronchain/directory. - Cross-module behavior MUST use a declared contract from
/shared/contracts, an HTTP/service API, or an event. - A module MUST NOT write directly to another module's MySQL tables.
- A module MUST provide a health check and a safe disabled state.
- A module MUST include database rollback instructions for every schema-changing release.
- A module MUST include unit, integration, property-based, security, and end-to-end tests appropriate to its risk.
- A module MUST document the secrets it can access and MUST fail review if it requests a secret it does not need.
- A module MUST provide structured logs without sensitive values.
- A module MUST have a threat model before production activation.
- A high-risk module MUST support feature-flag shutdown without breaking Silver/Gold wallet operation.
coxy/
├── README.md
├── LICENSE
├── SECURITY.md
├── CONTRIBUTING.md
├── CODEOWNERS
├── CHANGELOG.md
│
├── app/
│ ├── index.html
│ ├── index.js
│ ├── index.css
│ ├── router.js
│ ├── mode-manager.js
│ └── shell/
│
├── extension/
│ ├── manifest.json
│ ├── service-worker.js
│ ├── content-script.js
│ ├── injected-cip30.js
│ ├── popup/
│ └── security/
│
├── shared/
│ ├── contracts/
│ ├── crypto/
│ ├── events/
│ ├── http/
│ ├── logging/
│ ├── validation/
│ ├── config/
│ └── testkit/
│
├── modules/
│ ├── wallet-core/
│ ├── wallet-session/
│ ├── portfolio/
│ ├── transaction-engine/
│ ├── cardano-chain/
│ ├── cip30-provider/
│ ├── cip30-consumer/
│ ├── hardware-signers/
│ ├── governance/
│ ├── token-minting/
│ ├── metadata/
│ ├── policy-engine/
│ ├── identity-cip170/
│ ├── keri/
│ ├── credentials-acdc/
│ ├── vlei/
│ ├── compliance/
│ ├── programmable-assets/
│ ├── rwa/
│ ├── midnight-privacy/
│ ├── stablecoins/
│ ├── chain-router/
│ ├── bitcoin-chain/
│ ├── ethereum-chain/
│ ├── fiat/
│ ├── banking/
│ ├── fx/
│ ├── remittance/
│ ├── settlement-router/
│ ├── travel-rule/
│ ├── realfi/
│ ├── reconciliation/
│ ├── ai-assistant/
│ ├── ai-guardian/
│ ├── audit-log/
│ └── provider-health/
│
├── api/
│ ├── index.php
│ ├── bootstrap.php
│ ├── router.php
│ ├── auth.php
│ └── health.php
│
├── sql/
│ ├── core/
│ └── migrate.php
│
├── tools/
│ ├── build-extension.js
│ ├── check-module-boundaries.js
│ ├── property-runner.js
│ ├── security-scan.sh
│ └── release-check.sh
│
├── tests/
│ ├── smoke/
│ ├── regression/
│ └── cross-module/
│
└── docs/
├── product/
├── architecture/
├── security/
├── standards/
├── operations/
└── adr/
The root shared/ directory must remain deliberately small. It is not a place for miscellaneous business logic. It contains only stable contracts, cryptographic primitives that are required by multiple modules, validation helpers, logging, configuration, event definitions, and a common test kit. If code is specific to identity, remittance, programmable assets, or another business capability, it belongs in that module even when another module might eventually use it. Reuse should occur through an interface, not by turning shared/ into a second monolith.
The following catalogue defines the intended ownership boundary for the principal modules. Every listed module uses the standard atomic directory layout from Section 5 even when a particular subdirectory is intentionally empty. For example, banking/onchain/README.md explicitly states that banking has no direct on-chain contract rather than omitting the directory and leaving future developers unsure whether it was forgotten.
| Module | Modes | Atomic responsibility |
|---|---|---|
wallet-core |
Silver+ | This module owns Coxy-managed wallet creation, restoration, encrypted client storage, account discovery, lock/unlock state, and public account information. It never contains Identity, banking, RWA, AI, or external-wallet business logic. |
wallet-session |
Silver+ | This module owns the normalized session contract used by every feature that needs wallet state or a signing request. It isolates higher-level modules from whether the signer is Coxy, an external CIP-30 wallet, or a hardware-backed account. |
portfolio |
Silver+ | This module aggregates normalized balances and positions from chain, stablecoin, RWA, and financial adapters. It does not sign transactions or directly query arbitrary third-party services; it consumes provider contracts and cached projections. |
transaction-engine |
Silver+ | This module owns semantic TransactionPlan creation, transaction preview, serialization delegation, fee estimation orchestration, simulation results, signing handoff, submission, and normalized status tracking. |
cardano-chain |
Silver+ | This module owns Cardano network configuration, address validation, UTxOs, protocol parameters, transaction serialization, provider adapters, submission, confirmation, and Cardano-specific error normalization. |
cip30-provider |
Gold+ | This extension module exposes Coxy through window.cardano.coxy, manages dApp origins and permissions, validates requests, and sends signing actions into the trusted Coxy approval flow. |
cip30-consumer |
Gold+ | This web module discovers external CIP-30 providers, negotiates capabilities, normalizes provider differences, manages session/account changes, and produces Cip30WalletSession instances without accessing external private keys. |
hardware-signers |
Gold+ | This module owns hardware-device discovery, supported-device capabilities, transaction serialization requirements, device prompts, signing requests, and device error normalization. Trezor is implemented as an adapter rather than as a special case scattered through Cardano code. |
governance |
Silver/Gold+ | This module owns DRep/governance discovery, delegation and voting transaction plans, governance metadata display, and supported CIP-30 governance capabilities. Beginner presentation can be limited in Silver while the underlying module remains shared. |
token-minting |
Silver+ | This module owns Coxy's existing native-token mint/burn workflows, minting-policy integration, metadata preparation, and mint transaction plans. Programmable tokens are not added here; they are delegated to programmable-assets. |
metadata |
Silver+ | This module provides generic Cardano metadata building, validation, canonicalization rules, size checks, and serialization contracts. CIP-specific modules build on this service rather than rewriting metadata handling. |
policy-engine |
Diamond+ | This module evaluates versioned deterministic policies and evidence into ALLOW, DENY, or REVIEW. It is shared by identity, programmable assets, RWA, remittance, banking, and issuer administration but owns none of their provider-specific business logic. |
identity-cip170 |
Diamond+ | This module owns CIP-0170 codecs, authority windows, Cardano metadata mapping, attestation construction, attestation verification orchestration, and Cardano-indexed identity evidence. It delegates KERI and credential cryptography to their dedicated modules. |
keri |
Diamond+ | This module owns AID creation/management, KEL interaction, key-event rotation workflows, KERIA/Signify adapters, OOBI/watcher discovery, and KERI verification. KERI secrets are isolated from Cardano wallet secrets. |
credentials-acdc |
Diamond+ | This module owns credential import/receipt, schema references, ACDC parsing, credential-chain verification, registry/revocation status, and normalized credential evidence. It remains trust-framework neutral. |
vlei |
Diamond+ optional | This module adds GLEIF/vLEI-specific trust roots, credential types, QVI integration, and organizational-role interpretation on top of the generic credential engine. It can be disabled without disabling generic identity. |
compliance |
Diamond+ | This module owns KYC, AML-risk, sanctions, enhanced-review, jurisdiction, and compliance-provider orchestration. It stores minimum evidence/status and never treats a vendor's API response as universal legal compliance. |
programmable-assets |
Diamond+ | This module owns CIP-113-versioned adapters, programmable-token registry discovery, programmable balances, transfer plans, capability disclosure, issuer actions, and on-chain test artifacts. Experimental/mainnet behavior is independently feature-flagged. |
rwa |
Diamond+ | This module owns real-world-asset definitions, issuer references, legal-document digests, subscription/redemption workflow state, corporate actions, valuation adapters, holder policies, and issuer-operation evidence. |
midnight-privacy |
Diamond+ | This module owns Midnight network/provider integration and narrowly defined selective-disclosure or proof workflows. It does not convert ordinary Cardano transactions into private transactions and it does not own KYC data. |
stablecoins |
Gold+ | This module classifies supported stablecoins, records chain/issuer/collateral/risk metadata, and provides normalized stablecoin representations. Platinum adds conversion and settlement providers without changing Gold's ability to hold or send Cardano stablecoins. |
chain-router |
Platinum | This module resolves a normalized asset/account/action to the appropriate ChainAdapter and prevents chain-specific branching from spreading through UI and finance modules. |
bitcoin-chain |
Platinum | This module owns Bitcoin-specific account, address, UTXO, fee, signing-plan, provider, transaction, broadcast, and confirmation semantics behind ChainAdapter. It has no Cardano imports. |
ethereum-chain |
Platinum | This module owns Ethereum/EVM account, fee, token-contract, transaction, network, provider, and confirmation semantics behind ChainAdapter. Smart-contract risk metadata is exposed to TransactionPlan and AI Guardian. |
fiat |
Platinum | This module owns normalized fiat currency amounts, rounding rules, provider-account references, money formatting, and non-chain balance semantics. It deliberately remains separate from cryptocurrency ChainAdapters. |
banking |
Platinum | This module owns bank/provider account linking, consent state, beneficiary creation/verification, payment initiation, payment status, encrypted provider-token handling, and bank-specific adapters. It never stores online-banking passwords. |
fx |
Platinum | This module owns FX quote normalization, expiry, spread/fee disclosure, currency precision, provider selection, and conversion evidence. It does not release funds by itself. |
remittance |
Platinum | This module owns corridors, source/destination payment intents, beneficiary workflows, transfer lifecycle, user receipts, provider interactions, refunds/failures, and remittance-specific disclosures. |
settlement-router |
Platinum | This module scores only policy-approved settlement routes across bank, stablecoin, crypto, or other supported rails using cost, speed, liquidity, provider health, finality, and operational risk. |
travel-rule |
Platinum | This module owns collection, validation, packaging, secure institutional exchange, retention, and evidence for required originator/beneficiary information in applicable regulated crypto-asset transfers. It does not write personal Travel Rule data to public chain metadata. |
realfi |
Platinum | This module owns FinancialProtocolAdapter implementations, market/position normalization, action quotes, protocol-risk disclosure, and transaction-plan generation for supported RealFi/financial protocols. |
reconciliation |
Platinum | This module independently reconciles Coxy transfer records, bank/provider statements, blockchain confirmations, fees, FX results, and settlement outcomes. Unreconciled customer-money discrepancies generate operational alerts and can halt affected routes. |
ai-assistant |
All modes | This module owns sanitized context creation, provider/model adapters, educational prompts, explanations, and user-facing assistance. It has no signer capability and no direct secret-vault permission. |
ai-guardian |
All modes | This module combines deterministic security signals with advisory model analysis and produces explainable risk observations. It cannot approve or mutate a transaction. |
audit-log |
All modes | This module owns append-oriented audit records, correlation IDs, integrity metadata, retention/export policy, and evidence queries for authorized auditors/operators. |
provider-health |
All modes | This module measures provider latency, errors, rate limits, supported capabilities, circuit-breaker state, and maintenance status so other modules can fail over or degrade safely. |
Every atomic module keeps the standard top-level subdirectories even when one category has no executable code. For example, the Banking module's onchain/README.md should state that bank payment execution is off-chain and provider-driven. The CIP-30 provider module's sql/README.md can state which permissions are stored locally versus server-side. This convention makes repository reviews faster because missing capabilities are documented rather than ambiguous.
The shared core provides the stable abstractions upon which all four modes depend. The most important services are ModeManager, ModuleRegistry, WalletSession, SignerProvider, TransactionPlan, PolicyDecision, ChainAdapter, EventBus, AuditWriter, ProviderHealth, and FeatureFlags.
The Mode Manager decides which user-facing capabilities are available. It does not contain business logic. A mode is a capability set, and a feature may still be disabled within a mode if it is experimental, jurisdiction-limited, or temporarily unavailable.
export const COXY_MODES = Object.freeze({
silver: {
cardanoNative: true,
education: true,
externalWallets: false,
hardwareWallets: false,
identity: false,
programmableAssets: false,
privacy: false,
multiChain: false,
globalFinance: false
},
gold: {
cardanoNative: true,
education: true,
externalWallets: true,
hardwareWallets: true,
identity: false,
programmableAssets: false,
privacy: false,
multiChain: false,
globalFinance: false
},
diamond: {
cardanoNative: true,
externalWallets: true,
hardwareWallets: true,
identity: true,
programmableAssets: true,
privacy: true,
compliance: true,
rwa: true,
multiChain: false,
globalFinance: false
},
platinum: {
cardanoNative: true,
externalWallets: true,
hardwareWallets: true,
identity: true,
programmableAssets: true,
privacy: true,
compliance: true,
rwa: true,
multiChain: true,
stablecoinServices: true,
fiat: true,
remittance: true,
banking: true,
realFi: true,
globalFinance: true
}
});The example uses ordinary JavaScript objects and does not require a state-management framework. Server-side entitlements must also be checked in PHP; hiding a menu item in JavaScript is never a security boundary.
The WalletSession abstraction is mandatory before advanced modules are allowed to depend on wallet functionality. It prevents identity, RWA, programmable assets, and finance modules from becoming coupled to Coxy's existing private-key implementation.
/** @typedef {'coxy'|'cip30'} WalletSource */
export class WalletSession {
async getNetworkId() { throw new Error('Not implemented'); }
async getUtxos() { throw new Error('Not implemented'); }
async getBalance() { throw new Error('Not implemented'); }
async getUsedAddresses() { return []; }
async getUnusedAddresses() { return []; }
async getChangeAddress() { throw new Error('Not implemented'); }
async getRewardAddresses() { return []; }
async signTx(unsignedTxHex, partialSign = false) {
throw new Error('Not implemented');
}
async signData(address, payloadHex) {
throw new Error('Not supported');
}
async submitTx(signedTxHex) { throw new Error('Not implemented'); }
async capabilities() { return {}; }
}CoxyNativeWalletSession wraps the existing Coxy wallet functions. Cip30WalletSession wraps external wallet APIs such as Lace or Eternl. Modules above this boundary ask a session to sign; they never ask for a key.
Hardware wallets are not modeled as ordinary CIP-30 providers. A hardware wallet is primarily a secure signer/key-custody device and may be used by different wallet/account implementations. Coxy therefore introduces a separate signer abstraction. Cardano also has explicit interoperability considerations for hardware-wallet transaction serialization in CIP-0021.
export class SignerProvider {
async connect() { throw new Error('Not implemented'); }
async getPublicIdentity() { throw new Error('Not implemented'); }
async signTransaction(txPlan) { throw new Error('Not implemented'); }
async signMessage(message) { throw new Error('Not supported'); }
async disconnect() {}
}A Coxy software vault, Trezor adapter, later Ledger adapter, or other supported hardware signer can implement this interface without changing business modules.
Advanced modules must build a normalized transaction plan before producing serialized chain-specific data. This allows the UI, AI Guardian, policy engine, audit logger, simulator, and signer to inspect the same intent.
export function createTransactionPlan({ chain, actions, fees, metadata, warnings }) {
return Object.freeze({
version: 1,
chain,
actions: structuredClone(actions),
fees: structuredClone(fees ?? {}),
metadata: structuredClone(metadata ?? {}),
warnings: [...(warnings ?? [])],
createdAt: new Date().toISOString()
});
}The serialized transaction is derived from a reviewed plan. A dApp or AI component must not be able to show one plan and silently submit a materially different transaction body.
Silver is the protected educational mode and must remain the simplest user experience even as the codebase becomes more sophisticated. New users should be able to create or restore a wallet, understand their balance, receive ADA, send ADA and tokens, view recent activity, understand basic staking, mint tokens where Coxy currently supports that workflow, and access contextual education without being exposed to unnecessary protocol terminology.
Silver uses production-grade key derivation and recovery standards rather than simplified cryptography. Cardano wallet generation and deterministic derivation must follow the relevant Cardano wallet standards, including CIP-0003 and CIP-1852. Simplicity belongs in the interface, not in reduced cryptographic quality.
COXY SILVER
Balance
₳ 125.50
[ Send ] [ Receive ]
My Tokens
COXY 2,500
STUDENT 100
Learn
• What is ADA?
• What is a seed phrase?
• How does staking work?
• How do I avoid wallet scams?
Home | Learn | Wallet | Settings
The AI Assistant in Silver explains unfamiliar concepts in beginner language. The AI Guardian warns about suspicious or unusual transaction behavior, but it should avoid overwhelming beginners with false certainty or excessive security jargon. Every security warning must also provide a deterministic reason such as "new recipient", "unusually large amount", "unknown dApp origin", or "transaction includes token minting" rather than simply saying that AI considers a transaction dangerous.
Silver primarily enables wallet-core, wallet-session, portfolio, transaction-engine, cardano-chain, token-minting, governance-basic, ai-assistant, ai-guardian, audit-log, and provider-health. Advanced modules exist in the codebase but are disabled by the Mode Manager.
Every pull request for Diamond or Platinum functionality must run Silver regression tests. If Identity is completely disabled, Silver MUST still create, restore, unlock, send, receive, stake, display tokens, and update the extension. This is a hard architecture gate rather than a best-effort goal.
Gold transforms Coxy from a training wallet into a complete Cardano-facing product while preserving the simple Silver experience for users who prefer it. Gold supports Coxy-managed Cardano accounts and external wallet sessions. A user who already trusts Lace, Eternl, Yoroi, NuFi, or another compatible provider must be able to use Coxy services without importing that wallet's seed into Coxy.
CIP-0030 is Active and defines the Cardano dApp-wallet web bridge. It is fundamentally a webpage/dApp-to-wallet interface in which a wallet injects a namespaced provider under window.cardano, requests user consent through enable(), and exposes read/signing APIs. Gold therefore implements interoperability in two directions. Coxy itself becomes a CIP-30 provider for other dApps, while the Coxy web application becomes a CIP-30 consumer that can discover and connect external wallets. [S1]
Cardano dApp
|
v
window.cardano.coxy
|
v
Coxy extension
|
v
Coxy Native WalletSession
|
v
Coxy signer / user approval
The extension must use Manifest V3, bundle executable code locally, minimize extension permissions, enforce a strict content-security policy, and keep injected-page code separated from privileged extension code. Chrome's Manifest V3 removes general remotely hosted executable code and uses service workers for extension background execution. [S12]
Coxy MUST NOT hard-code business logic for individual wallet brands. The connector discovers providers, validates the CIP-30 shape, negotiates extensions/capabilities, and normalizes addresses, CBOR, UTxOs, errors, network IDs, and partial-signing behavior. Wallet-specific workarounds, if unavoidable, live inside a compatibility adapter and are accompanied by integration tests.
CIP-30 has an accepted extension mechanism. Current accepted extensions include CIP-0095 for Conway-era governance, CIP-0103 for bulk transaction signing, CIP-0104 for an account public key, and CIP-0106 for multisig wallets. Gold records the capabilities actually exposed by the connected wallet instead of assuming that every provider supports every optional API. [S2]
export async function readWalletCapabilities(provider) {
const supported = Array.isArray(provider.supportedExtensions)
? provider.supportedExtensions
: [];
return {
cip30: true,
governance: supported.some(x => x?.cip === 95),
bulkSign: supported.some(x => x?.cip === 103),
accountPublicKey: supported.some(x => x?.cip === 104),
multisig: supported.some(x => x?.cip === 106)
};
}Coxy identity must not assume that a KERI identity belongs only to a Coxy address. A Diamond or Platinum user can link an external wallet by asking the wallet to sign a domain-separated challenge through the appropriate signing API, verifying the signature, and recording a revocable wallet-to-identity binding. The proof must include nonce, origin, network, address, timestamp, and an explicit purpose string to prevent replay across contexts.
Trezor currently supports Cardano and can work with its own suite as well as compatible wallet applications. Gold therefore includes a hardware-signer provider boundary rather than treating Trezor as a CIP-30 extension. [S11]
The hardware module owns device discovery, connection state, compatible transaction serialization, device prompts, signing requests, firmware/support checks, and error normalization. The Cardano transaction engine remains responsible for constructing the intent and transaction plan; the hardware signer remains responsible for key custody and confirmation on the device.
Diamond is where Coxy becomes more than a conventional Cardano wallet. It combines Gold's Cardano interoperability with verifiable digital identity, credentials, configurable compliance policy, programmable assets, real-world asset workflows, and privacy-preserving proof or disclosure mechanisms. The modules are independent but become more valuable when composed through the shared Policy Engine.
Diamond's essential design principle is that identity proves who or what is authorized, policy determines whether an operation may proceed, privacy determines which information must be disclosed, and the on-chain programmable-asset script provides authoritative enforcement when a token requires transfer-time rules. The user interface may preflight a transaction to avoid unnecessary fees, but an off-chain green check is never a substitute for on-chain enforcement where the asset's security model requires it.
Platinum extends Diamond into a global financial wallet. It combines crypto assets, Cardano and non-Cardano chains, stablecoins, fiat balances exposed through financial partners, FX, cross-border payments, remittances, settlement routing, RealFi, banking interfaces, treasury, and advanced portfolio services under the same identity, policy, privacy, and security architecture.
Platinum must not pretend that US dollars or South African rand are cryptocurrencies. Fiat is represented through regulated banking/payment providers, safeguarded accounts, e-money or similar partner structures according to jurisdiction. The Fiat module is therefore separate from ChainAdapter. Stablecoins are chain assets and are handled through chain and asset adapters. Bank money is handled through BankingProvider and FiatAccount interfaces.
Coxy should initially integrate licensed and authorized partners rather than attempting to become a bank or money-transfer operator merely because it has KYC technology. In South Africa, exchange-control matters are handled through Authorised Dealers or Authorised Dealers in foreign exchange with limited authority, and SARB's current materials describe ADLA categories that include money-remittance and independent value-transfer activities. Cross-border foreign-exchange transactions handled by these entities are reportable through the Financial Surveillance framework. [S14] [S15]
The platform architecture must therefore be able to operate in multiple regulatory models. In one corridor, Coxy may provide only the technology and customer experience while a licensed provider is the regulated payment entity. In another market, a Coxy affiliate may later hold an appropriate authorization. The module contracts remain the same while the provider configuration, disclosures, limits, reporting, and legal responsibilities change by jurisdiction.
AI is a cross-cutting Coxy capability rather than a mode-specific product. It is divided into two separate modules because teaching a user and evaluating risk are different responsibilities.
The Assistant provides contextual education and workflow guidance. In Silver it explains seed phrases, fees, addresses, staking, tokens, and scams in simple language. In Gold it can explain dApp permissions, collateral, governance actions, hardware-wallet prompts, and external-wallet sessions. In Diamond it can explain credentials, identity status, programmable-asset restrictions, RWA terms, and privacy disclosures. In Platinum it can explain FX quotes, settlement routes, stablecoin exposure, remittance status, RealFi positions, and bank integration workflows.
The Assistant receives a sanitized context object, never direct secret storage. A context builder must redact addresses where full addresses are unnecessary, remove personal documents, remove bank credentials, remove KERI secrets, remove seeds, and convert complex transactions into a safe semantic representation.
The Guardian combines deterministic checks with optional model-based analysis. Deterministic checks always run first and produce explainable flags. Examples include a new recipient, a transaction materially larger than recent transactions, a new dApp origin, a token with issuer seizure rights, an unknown smart contract, a changed destination after quote generation, a mismatched network, or a beneficiary created moments before a large cross-border transfer.
The AI Guardian cannot sign, approve, change the transaction, suppress a mandatory compliance check, or override a denial returned by a deterministic security or regulatory policy. If the AI system is offline, transaction signing remains available subject to deterministic security policy. AI failure must never make the wallet unusable.
The AI module stores prompt/response telemetry only when the user and deployment policy permit it. It must never persist seed phrases, private keys, raw biometric data, complete KYC documents, banking passwords, API secrets, hardware-wallet secrets, or unredacted issuer administration material. External AI providers must be accessed only through a server-side adapter with explicit data-minimization policy and tenant configuration. Coxy should be able to replace a model provider or use a local model without rewriting wallet modules.
Security is divided into cryptographic security, application security, transaction security, identity security, on-chain security, financial integration security, and operational security.
The wallet password is not merely a UI lock. Sensitive wallet material must be encrypted at rest using authenticated encryption and a deliberately expensive password-derived key. The stored record must contain only ciphertext, salt, nonce/IV, KDF parameters, version, and non-secret metadata. Password changes rewrap or re-encrypt according to a versioned migration policy.
A high-level vault record can look like this:
{
"version": 2,
"kdf": {
"name": "argon2id",
"salt": "base64...",
"parameters": {
"memoryKiB": 65536,
"iterations": 3,
"parallelism": 1
}
},
"cipher": {
"name": "AES-256-GCM",
"nonce": "base64...",
"ciphertext": "base64..."
}
}Exact KDF parameters must be benchmarked for target devices and reviewed periodically. The vault format is versioned so stronger parameters or algorithms can be introduced without breaking recovery.
The Coxy extension uses Chrome Manifest V3 security practices. Privileged APIs stay in the extension service worker or privileged pages. Page-injected CIP-30 code is considered untrusted input. Messages between page, content script, service worker, and popup include origin, request ID, method allowlist, schema validation, and explicit user-approval state. Remote executable code is not loaded by the extension. [S12]
Fingerprint, Face ID, or similar device authentication is treated as an operating-system authorization gate to device-protected key material, not as data Coxy stores or processes. The application receives an authorization result or access to a device-protected cryptographic operation. The platform does not store fingerprint templates.
Every signing request must show semantic effects rather than a generic "Sign transaction" prompt. The approval view should include assets leaving and entering the wallet, recipient(s), fees, deposits, withdrawals, staking/governance certificates, mint/burn actions, script interactions, collateral, programmable-token restrictions, and issuer powers relevant to the asset.
Mint, freeze, unfreeze, seize, forced-transfer, redemption, or policy-administration authority must not default to the same key used for ordinary consumer spending. High-value issuer functions should support multisignature, hardware signing, role credentials, dual control, policy thresholds, and an immutable audit record. The UI must clearly distinguish an ordinary transfer from an issuer administration action.
CIP-0170 is currently Proposed. It defines KERI-backed Cardano metadata attestations in which KERI Autonomic Identifiers can establish signing authority through credential chains and later create verifiable records. Its lifecycle includes AUTH_BEGIN, ATTEST, and AUTH_END, and verification requires access to the relevant KERI Key Event Logs and credential state. KELs may be off-chain, so a verifier/indexer path is a first-class part of the architecture. [S3]
modules/identity-cip170/
├── offchain/
│ ├── cip170-codec.js
│ ├── authority-state.js
│ ├── attestation-builder.js
│ └── digest.js
├── onchain/
│ └── README.md
├── backend/
│ ├── service/IdentityService.php
│ ├── service/VerificationService.php
│ └── repository/
├── integrations/
│ ├── keri.adapter.js
│ ├── credential.adapter.js
│ ├── cardano-indexer.adapter.php
│ └── vlei.adapter.php
├── sql/
└── tests/
KERI protocol handling may be implemented through a standards-compatible KERI stack such as KERIA/Signify where appropriate rather than by inventing a proprietary Coxy identity cryptosystem. KERIA's published architecture keeps client secrets at the edge and lets hosted agents perform non-secret agent work, which aligns with Coxy's desired separation between client-held keys and server infrastructure. [S9]
The Cardano Foundation's Veridian wallet is a useful reference implementation because it is an open-source identity wallet built around KERI and ACDC concepts. Coxy should study its interoperability and security decisions while maintaining its own modular boundaries. [S8]
Coxy Secure Storage
├── Cardano Wallet Vault
│ └── Cardano seed and derived keys
└── Identity Vault
└── KERI client secrets / identity key material
A Cardano mnemonic must not automatically become a KERI identity key. Separate key domains permit independent KERI rotation and reduce the blast radius of compromise.
export class Cip170Codec {
constructor(version) {
this.version = version;
}
encode(record) {
if (!record || typeof record !== 'object') {
throw new TypeError('CIP-0170 record must be an object');
}
return { 170: structuredClone(record) };
}
decode(metadata) {
const value = metadata?.[170] ?? metadata?.['170'];
if (!value) throw new Error('CIP-0170 metadata not found');
return structuredClone(value);
}
}Production validation must be stricter than this shortened example. It must validate transaction type, field encoding, version compatibility, credential chain, KERI event sequence, anchored digest, authority window, revocation state, and the trust policy applicable to the ecosystem.
ACDC credentials answer questions about authorization and attributes associated with an identity. vLEI is one important organizational trust ecosystem and is based on KERI/ACDC infrastructure under GLEIF governance. Coxy's credential engine must remain trust-framework agnostic so it can verify a vLEI, an enterprise credential, a professional credential, or another approved credential without replacing the identity core. [S10]
Coxy should initially act as a credential holder/presenter/verifier and integrate qualified issuers rather than representing itself as a vLEI issuer without completing the required governance and qualification process.
CIP-113 programmable tokens are highly relevant to Coxy's existing token-minting direction because they add validation logic to token circulation rather than limiting control to mint and burn. The Cardano Developer Portal currently describes CIP-113 as a draft in active development and explicitly states that its reference implementation has not yet reached production-ready maturity. Coxy must therefore integrate the concept behind a versioned experimental adapter and must not make unaudited mainnet issuance a default Diamond feature. [S4]
The Cardano Foundation's 2026 development reporting describes candidate functionality such as registration, mint/burn, transfer, freeze/unfreeze, and seize, with audit work underway. Coxy can build its interface and testnet architecture while using independent security gates for mainnet activation. [S5]
modules/programmable-assets/
├── public/
├── offchain/
│ ├── registry-client.js
│ ├── token-definition.js
│ ├── transfer-plan.js
│ └── capability-descriptor.js
├── onchain/
│ ├── src/
│ ├── artifacts/
│ └── test-vectors/
├── backend/
│ ├── service/
│ ├── repository/
│ └── api/
├── integrations/
│ ├── identity-policy.adapter.js
│ ├── compliance.adapter.js
│ └── cardano.adapter.js
├── sql/
└── tests/
Every programmable asset displayed by Coxy should expose its powers and restrictions in machine-readable form.
export function normalizeProgrammableCapabilities(raw) {
return {
requiresIdentity: Boolean(raw.requiresIdentity),
requiresKyc: Boolean(raw.requiresKyc),
transferRestricted: Boolean(raw.transferRestricted),
jurisdictionRestricted: Boolean(raw.jurisdictionRestricted),
canFreeze: Boolean(raw.canFreeze),
canSeize: Boolean(raw.canSeize),
canBurn: Boolean(raw.canBurn),
canMintAdditionalSupply: Boolean(raw.canMintAdditionalSupply),
hasTransferLimits: Boolean(raw.hasTransferLimits)
};
}The wallet must display these powers before a user accepts or purchases an asset. Issuer powers such as freeze or seizure must never be hidden behind a generic token-details screen.
The off-chain preflight improves user experience and prevents unnecessary fees, but the on-chain validator is authoritative for rules that are part of the token's security model. Coxy must assume that a user could attempt to move an asset through another wallet.
Coxy can make programmable issuance understandable through templates such as Unrestricted Programmable Token, Verified Holders, KYC Required, RWA Basic, Regulated RWA, Stablecoin Control, and Custom Policy. A template does not become a legal claim. It is a technical configuration that a qualified issuer and its legal/compliance team must approve for the intended jurisdiction.
Midnight is now a live privacy-oriented network, and its developer documentation emphasizes zero-knowledge proofs and selective disclosure. It is a separate network and must therefore be integrated as a ChainAdapter/PrivacyProvider rather than being described as a switch that makes an ordinary Cardano transaction private. [S6] [S7]
Diamond / Platinum Workflow
|
v
PrivacyService
|
+-- DisclosurePolicy
+-- ProofRequest
+-- ProofVerifier
|
v
MidnightAdapter
|
v
Midnight network / proof-capable application
A high-value Diamond use case is selective compliance proof. For example, a user may prove that a valid KYC credential exists, that the credential is not revoked, that the user satisfies an age or jurisdiction policy, or that an institutional role is valid without publishing the full identity record on a transparent blockchain. The exact statement and legal acceptability must be defined by the relying party.
Coxy must never publish passports, identity numbers, residential addresses, complete KYC files, complete bank statements, or other sensitive personal data to Cardano metadata. Public chains should contain cryptographic commitments, digests, attestations, identifiers, or other specifically reviewed data. Private records remain encrypted off-chain or within a privacy-preserving protocol appropriate to the use case.
KYC, AML, counter-terrorist-financing controls, sanctions screening, Travel Rule requirements, transaction monitoring, and jurisdiction restrictions are separate concerns even when a provider exposes them through one commercial API. Coxy models each concern through a provider-neutral contract so providers can be replaced without changing programmable-token or remittance modules.
export const PolicyDecision = Object.freeze({
ALLOW: 'ALLOW',
DENY: 'DENY',
REVIEW: 'REVIEW'
});
export async function evaluatePolicy(policy, context, providers) {
const checks = [];
for (const rule of policy.rules) {
const result = await rule.evaluate(context, providers);
checks.push(result);
if (result.decision === PolicyDecision.DENY) {
return { decision: PolicyDecision.DENY, checks };
}
}
const requiresReview = checks.some(
x => x.decision === PolicyDecision.REVIEW
);
return {
decision: requiresReview ? PolicyDecision.REVIEW : PolicyDecision.ALLOW,
checks
};
}A REVIEW outcome is necessary because not every unusual condition should automatically block a transaction. Institutional workflows may require human compliance approval, additional evidence, enhanced due diligence, or a second signatory.
export class KycProvider {
async getStatus(subjectRef) { throw new Error('Not implemented'); }
}
export class RiskProvider {
async screenAddress(address, chain) { throw new Error('Not implemented'); }
async screenTransaction(transactionContext) { throw new Error('Not implemented'); }
}
export class SanctionsProvider {
async screenIdentity(identityContext) { throw new Error('Not implemented'); }
}A provider returns evidence, version, timestamps, confidence/status, and expiry where relevant. Coxy stores only the minimum information required by policy and law. Sensitive provider responses may require encrypted storage and retention schedules.
South Africa's FIC Directive 9 Travel Rule requirements for crypto-asset transfers took effect on 30 April 2025. Platinum's crypto and stablecoin transfer architecture must therefore make Travel Rule data orchestration an independent module rather than embedding it inside a single exchange integration. [S16]
FATF updated Recommendation 16 payment-transparency standards in June 2025 with an emphasis on standardized information in cross-border payment messages and fraud/error protections. The Coxy payment model should be designed so originator and beneficiary information, where legally required, can be attached to the regulated payment message or delivered between participating institutions without putting that information on a public blockchain. [S17]
The RWA module coordinates asset metadata, issuer identity, legal-document references, programmable-asset rules, compliance policy, corporate actions, redemption, valuations, and audit evidence. It does not itself determine whether a token legally represents ownership of a particular asset. The legal wrapper, issuer agreements, custody, registries, and jurisdiction-specific enforceability remain part of the RWA product and partner design.
RWA Module
├── Asset definition
├── Issuer identity reference
├── Legal document hashes/references
├── Programmable token definition
├── Holder eligibility policy
├── Subscription workflow
├── Redemption workflow
├── Corporate actions
├── Valuation feed adapters
├── Distribution/payment events
├── Freeze/seizure workflow references
└── Audit evidence
An issuer action such as forced transfer should require an explicit authority record, role authorization, reason/reference, approval threshold, cryptographic signatures, and an audit event. The action should optionally be attested through CIP-0170 so an auditor can verify who performed the action and whether the relevant credential was valid at that time.
Platinum requires a chain abstraction before Bitcoin, Ethereum, or any future network is added. Chain-specific data structures must not spread throughout the portfolio, UI, remittance, or AI modules.
export class ChainAdapter {
get chainId() { throw new Error('Not implemented'); }
async listAccounts() { return []; }
async getBalances(account) { return []; }
async estimateFees(intent) { throw new Error('Not implemented'); }
async buildTransaction(intent) { throw new Error('Not implemented'); }
async broadcast(signedTransaction) { throw new Error('Not implemented'); }
async getTransactionStatus(id) { throw new Error('Not implemented'); }
}The cardano-chain module is the first implementation. midnight-privacy can expose chain-specific operations through its own adapter. bitcoin-chain and ethereum-chain are Platinum modules. Each chain module owns address validation, fee estimation, serialization, network configuration, provider selection, confirmation semantics, and chain-specific security tests.
A normalized AssetId must include chain, network, namespace/contract/policy, and asset identifier. A symbol such as USDC is not a safe unique identifier because the same symbol can exist on multiple networks or bridges.
Cardano currently lists multiple active native stablecoins, including USDCx, USDM, USDA, DJED, and iUSD, with additional bridged assets also present in the ecosystem. Gold therefore needs stablecoin-aware display and risk metadata even before Platinum financial services are enabled. [S13]
Gold provides ordinary Cardano receive/send/display for supported stablecoins. Diamond can combine stablecoins with identity, policy, programmable assets, and RWA use cases. Platinum adds multi-chain stablecoin aggregation, FX, treasury, conversion, fiat on/off ramps, settlement routing, liquidity, and provider-specific redemption workflows.
export class FiatAccountProvider {
async listAccounts(customerRef) { return []; }
async getBalance(accountRef) { throw new Error('Not implemented'); }
async createPayee(payee) { throw new Error('Not implemented'); }
async createPayment(paymentIntent) { throw new Error('Not implemented'); }
async getPaymentStatus(paymentRef) { throw new Error('Not implemented'); }
}Fiat balances shown in Coxy must clearly state the responsible regulated provider and legal nature of the balance. Coxy must not display a provider's off-chain balance as if it were a self-custodied blockchain asset.
Cross-border remittances are a core Platinum pillar because the identity, compliance, stablecoin, multi-chain, privacy, and settlement capabilities can be composed into a single consumer experience. The architecture must nevertheless recognize that technical KYC and privacy capabilities do not remove banking, exchange-control, licensing, safeguarding, reporting, and institutional requirements.
The user sees the source amount, destination amount, FX rate, all fees, estimated arrival window, beneficiary, payment method, provider, compliance status, and any required declarations before authorizing the transfer. The settlement route may be more complex internally, but the user must never be surprised by an undisclosed conversion or intermediary fee.
export async function chooseSettlementRoute(routes, policy, preferences) {
const allowed = routes.filter(route => policy.allows(route));
if (!allowed.length) throw new Error('No compliant settlement route');
const scoring = {
cheapest: route => route.totalCostMinor,
fastest: route => route.estimatedSeconds,
recommended: route =>
route.totalCostMinor + route.riskPenalty + route.liquidityPenalty
};
const score = scoring[preferences.mode] ?? scoring.recommended;
return [...allowed].sort((a, b) => score(a) - score(b))[0];
}Real production scoring must also consider corridor availability, provider limits, settlement finality, liquidity, treasury balances, outage status, sanctions restrictions, cut-off times, bank holidays, refundability, beneficiary method, and legal rules.
SARB states that exchange-control matters are handled through Authorised Dealers or ADLAs and that cross-border foreign-exchange transactions handled by these entities are reported through the Financial Surveillance framework. ADLA categories include entities authorized for money-remittance and independent value-transfer services. Coxy's South African implementation should therefore support partner-led regulated flows and FinSurv-related data/reporting integration where the regulated partner's model requires it. [S14] [S15]
Coxy should expand remittance corridor by corridor. Each corridor has its own source/destination currencies, limits, payout methods, required information, provider set, disclosures, compliance policy, settlement routes, and reporting obligations. A configuration-driven corridor engine is safer than claiming global support based only on whether Coxy can technically transfer a stablecoin.
The CPMI's 2026 work continues to emphasize harmonized ISO 20022 data for cross-border payments and API interoperability. Coxy does not need to implement an entire bank messaging network in the first release, but the internal payment model should be able to map cleanly to structured payer, beneficiary, purpose, account, remittance, and regulatory fields rather than relying on free-form text. [S18] [S19]
The Banking module provides provider-neutral account linking, balance retrieval, beneficiary validation, payment initiation, payment status, consent lifecycle, and account disconnect. It never stores a customer's online-banking password. OAuth/open-banking tokens or other provider credentials must be encrypted server-side and constrained to the scopes required by the integration.
RealFi is implemented as a financial-protocol adapter rather than being built into the wallet core. The same interface can later support lending, borrowing, liquidity, credit, RWA financing, or other financial protocols without modifying the core transaction engine.
export class FinancialProtocolAdapter {
async discoverMarkets() { return []; }
async getPositions(walletSession) { return []; }
async quoteAction(action) { throw new Error('Not implemented'); }
async buildAction(action) { throw new Error('Not implemented'); }
}A RealFi module must expose protocol risk, smart-contract addresses, chain, collateral terms, rates, liquidation conditions where applicable, fees, and transaction effects in a normalized format that the AI Assistant and Guardian can explain. Coxy must not turn an opaque third-party protocol call into a one-click action without meaningful user review.
MySQL is used for durable server-side state, indexes, non-secret preferences, provider state, audit metadata, quotes, workflow state, and service projections. It is not used to store unencrypted wallet seeds or raw private keys. Client-side self-custody secrets remain encrypted in the appropriate client vault.
Each module prefixes tables so ownership is obvious. Examples include identity_profiles, identity_credentials, pa_token_registry, compliance_checks, rwa_assets, remit_transfers, bank_accounts, fx_quotes, audit_events, and provider_health.
Cross-module hard foreign keys should be used sparingly. A module normally stores another domain's public reference, such as identity_id or wallet_account_ref, rather than coupling its schema migration to another module's private table. Referential correctness across module boundaries is enforced through service contracts and background reconciliation.
A transactional outbox allows reliable module events without requiring a large message-broker framework at the beginning.
CREATE TABLE core_event_outbox (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
event_id CHAR(36) NOT NULL,
topic VARCHAR(120) NOT NULL,
aggregate_ref VARCHAR(190) NULL,
payload_json JSON NOT NULL,
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
published_at DATETIME(6) NULL,
attempts INT UNSIGNED NOT NULL DEFAULT 0,
PRIMARY KEY (id),
UNIQUE KEY uq_event_id (event_id),
KEY idx_unpublished (published_at, id),
KEY idx_topic_created (topic, created_at)
) ENGINE=InnoDB;A module writes its business state and its outbox event in the same MySQL transaction. A small worker publishes or dispatches the event and marks it published. If the application later adopts a dedicated event broker, the module event contracts remain unchanged.
CREATE TABLE identity_profiles (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
profile_uuid CHAR(36) NOT NULL,
user_ref VARCHAR(190) NOT NULL,
aid VARCHAR(255) NOT NULL,
alias_name VARCHAR(120) NOT NULL,
status ENUM('creating','active','rotating','revoked','error') NOT NULL,
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
ON UPDATE CURRENT_TIMESTAMP(6),
PRIMARY KEY (id),
UNIQUE KEY uq_profile_uuid (profile_uuid),
UNIQUE KEY uq_aid (aid),
KEY idx_user_status (user_ref, status)
) ENGINE=InnoDB;This table stores identity references, not KERI private keys. KERI secret material belongs in the encrypted Identity Vault or standards-compatible edge key store.
CREATE TABLE audit_events (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
event_uuid CHAR(36) NOT NULL,
actor_type VARCHAR(40) NOT NULL,
actor_ref VARCHAR(190) NULL,
action VARCHAR(120) NOT NULL,
resource_type VARCHAR(80) NOT NULL,
resource_ref VARCHAR(190) NULL,
result VARCHAR(40) NOT NULL,
correlation_id CHAR(36) NULL,
details_json JSON NULL,
previous_hash CHAR(64) NULL,
event_hash CHAR(64) NOT NULL,
created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
PRIMARY KEY (id),
UNIQUE KEY uq_event_uuid (event_uuid),
KEY idx_actor_time (actor_ref, created_at),
KEY idx_resource_time (resource_ref, created_at),
KEY idx_correlation (correlation_id)
) ENGINE=InnoDB;Hash chaining can make later tampering more detectable, but it is not a substitute for access control, backups, write-once archival, or an external audit anchor for high-assurance workflows.
The server uses a small front controller and explicit route registration. It does not require a PHP framework. Each module registers only its own routes.
<?php
// api/router.php
final class Router
{
private array $routes = [];
public function add(string $method, string $path, callable $handler): void
{
$key = strtoupper($method) . ' ' . $path;
$this->routes[$key] = $handler;
}
public function dispatch(string $method, string $path): void
{
$key = strtoupper($method) . ' ' . $path;
$handler = $this->routes[$key] ?? null;
if (!$handler) {
http_response_code(404);
header('Content-Type: application/json');
echo json_encode(['error' => 'not_found']);
return;
}
$handler();
}
}Input is validated before calling domain services. Authentication and authorization are server-side. Error responses use stable error codes and correlation IDs rather than leaking stack traces.
<?php
function db(array $cfg): PDO
{
$dsn = sprintf(
'mysql:host=%s;port=%d;dbname=%s;charset=utf8mb4',
$cfg['host'],
$cfg['port'],
$cfg['database']
);
return new PDO($dsn, $cfg['user'], $cfg['password'], [
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
PDO::ATTR_EMULATE_PREPARES => false
]);
}All queries use prepared statements. Database users receive the minimum privileges required for the service. Production credentials never live in Git.
Every external dependency is wrapped in a Coxy contract. Examples include CardanoProvider, KeriProvider, KycProvider, RiskProvider, SanctionsProvider, FxProvider, BankingProvider, RemittanceProvider, StablecoinLiquidityProvider, PriceProvider, and AiProvider.
Provider adapters normalize authentication, timeouts, retries, error codes, rate limits, health, request IDs, and response validation. Business modules cannot call third-party URLs directly. This is central to scalability because Coxy can add failover providers, change vendors, run regional providers, or move a service in-house without rewriting the product workflow.
Events use versioned topics and schemas such as:
wallet.account_changed.v1
wallet.transaction_submitted.v1
identity.created.v1
identity.credential_verified.v1
policy.decision.v1
programmable_asset.registered.v1
rwa.issuer_action_requested.v1
remittance.quote_created.v1
remittance.transfer_status_changed.v1
provider.health_changed.v1
security.risk_detected.v1
Consumers must be idempotent because an event can be delivered more than once. Every event has eventId, occurredAt, correlationId, schemaVersion, and a payload that contains no secrets.
export class ModuleRegistry {
#modules = new Map();
register(module) {
if (!module?.id) throw new Error('Module id is required');
if (this.#modules.has(module.id)) {
throw new Error(`Duplicate module: ${module.id}`);
}
this.#modules.set(module.id, module);
}
has(id) {
return this.#modules.has(id);
}
async startEnabled(context) {
for (const module of this.#modules.values()) {
if (context.features.isEnabled(module.id)) {
await module.start(context);
}
}
}
}This pattern keeps activation explicit. Modules do not self-start merely because their JavaScript file was included.
// shared/contracts/policy-client.js
export class PolicyClient {
constructor(transport) {
this.transport = transport;
}
async evaluate(policyId, context) {
return this.transport.request('policy.evaluate.v1', {
policyId,
context
});
}
}The Programmable Assets module depends on PolicyClient, not on files inside modules/compliance/.
<?php
function logEvent(string $level, string $event, array $context = []): void
{
$blocked = ['seed', 'mnemonic', 'private_key', 'password', 'access_token'];
foreach ($blocked as $key) {
if (array_key_exists($key, $context)) {
$context[$key] = '[REDACTED]';
}
}
$record = [
'ts' => gmdate('c'),
'level' => $level,
'event' => $event,
'correlation_id' => $context['correlation_id'] ?? null,
'context' => $context
];
error_log(json_encode($record, JSON_UNESCAPED_SLASHES));
}Production redaction must be recursive and schema-aware; this short example illustrates the policy that logs are structured and secrets are explicitly excluded.
Node's built-in test runner can be combined with a small generator utility so the project does not require a frontend framework or heavy testing framework.
import test from 'node:test';
import assert from 'node:assert/strict';
import { randomBytes } from 'node:crypto';
import { encodeMetadata, decodeMetadata } from '../../offchain/codec.js';
test('metadata round-trip property', () => {
for (let i = 0; i < 1000; i += 1) {
const value = randomBytes(32).toString('hex');
const original = { 170: { t: 'ATTEST', d: value } };
const encoded = encodeMetadata(original);
const decoded = decodeMetadata(encoded);
assert.deepEqual(decoded, original);
}
});Property tests are especially important for address handling, serialization, metadata round trips, amount arithmetic, transaction-plan normalization, policy evaluation, identifier parsing, and any codec that processes adversarial blockchain data.
Coxy adopts a test pyramid plus protocol vectors and security tests. The required test categories are not optional labels; each module must document which behaviors are covered in each category.
Unit tests cover deterministic functions, validators, parsers, domain services, repository logic through mocks or an isolated database, UI components that can be tested without a real chain, and security helpers. JavaScript should prefer Node's built-in node:test and assert modules where practical. PHP may use small self-contained test scripts or an approved lightweight testing library if it materially improves correctness, but no web framework is required.
Integration tests exercise real boundaries. Examples include Coxy-to-Cardano provider, Coxy-to-CIP-30 test wallet, Coxy-to-Trezor test environment where available, KERIA/Signify test services, MySQL migrations, KYC provider sandbox, bank/FX provider sandbox, Midnight test environment, and end-to-end remittance provider sandboxes.
Property tests generate many valid and invalid values. Required high-value areas include Cardano address parsing, CBOR/metadata codecs, CIP-0170 record round trips, transaction value conservation, multi-asset arithmetic, policy determinism, programmable-asset capability parsing, quote math, FX rounding, amount boundary behavior, idempotency, and normalization of provider responses.
The project keeps committed known-good vectors for Cardano key derivation, addresses, transaction serialization, metadata, KERI events, ACDC credential fixtures, programmable-token artifacts, and remittance message mapping. A change that intentionally updates a golden vector requires a reviewer to explain why the old result became invalid.
Silver and Gold core wallet flows form a permanent regression suite. The suite includes wallet creation, 15/24-word restoration where supported, lock/unlock, ADA receive/send, native assets, transaction history, staking, delegation, governance operations supported by the mode, token minting, CIP-30 connect/sign/submit, network switching, extension upgrade, database migration, and recovery after provider errors.
Security tests include malformed CBOR, oversized metadata, invalid addresses, cross-network requests, malicious dApp origins, replayed signData challenges, manipulated transaction plans, injected HTML, CSRF against server endpoints, SQL injection attempts, rate-limit abuse, permission escalation, stale KYC evidence, revoked credentials, malicious KEL data, programmable-token policy bypass attempts, and settlement-route tampering.
A required Diamond end-to-end test should create an identity, verify a credential, establish CIP-0170 authority, attest a document digest, verify the attestation, rotate KERI keys, verify the old attestation remains attributable where appropriate, revoke authority, and confirm that a later attestation is rejected by the authority-window logic.
A required programmable-asset test should register a test asset, mint, transfer between permitted holders, reject a non-compliant holder, freeze/unfreeze according to the candidate implementation, execute an approved issuer action where supported, and prove that ordinary native-asset transfers are unaffected when the module is disabled.
A required Platinum test should create a beneficiary, obtain competing route quotes, perform policy screening, choose a permitted route, capture explicit user authorization, submit through a provider sandbox, process asynchronous status changes, reconcile provider and internal balances, create the required reporting/audit record, and safely handle provider timeout or duplicate callback delivery.
Logging serves debugging and operations. Audit records serve accountability. Analytics serves product measurement. These purposes must not be mixed into a single unrestricted stream.
Application logs are structured JSON and include timestamp, level, module, event name, correlation ID, provider request ID where safe, duration, status, and sanitized context. Logs never contain seeds, private keys, wallet passwords, decrypted identity secrets, full KYC documents, full banking credentials, authentication tokens, or biometric data.
High-risk actions have audit records: wallet-vault migrations, identity creation, credential verification/revocation, AUTH_BEGIN, AUTH_END, issuer freeze/seize actions, policy administration, compliance overrides, bank beneficiary changes, remittance approvals, provider configuration changes, administrator actions, and security settings changes.
Audit events are append-only from the application perspective. Where regulations or institutional agreements require stronger evidence, Coxy can export or anchor audit digests to an external immutable store without exposing private event contents.
Metrics include API latency, error rate, provider availability, transaction submission time, Cardano confirmation latency, KERI resolution latency, compliance-provider latency, remittance quote success, payment state age, callback failures, database connection usage, queue/outbox backlog, and cache hit rates. Security metrics include repeated unlock failure, suspicious origin requests, policy denial rate, and abnormal provider error patterns, subject to privacy constraints.
Coxy scales primarily by keeping stateless request handling separate from durable module data and by avoiding hard dependencies on one external provider.
Cardano blockchain reads, transaction submission, market data, FX, compliance, and other high-availability services use provider pools where commercially and technically possible. ProviderHealth tracks latency, recent failures, rate limits, maintenance, supported features, and circuit-breaker state.
Public or semi-public data such as token metadata, protocol parameters, price data, KERI public state, credential schemas, and trust roots may be cached with explicit TTL and invalidation rules. A verified=true result is never cached forever because credentials, policies, issuer authority, and sanctions state can change.
MySQL InnoDB is the primary relational store. Read-heavy modules may use read replicas. Large audit or historical tables should use time-aware indexes and archival policy. Tables are designed with integer primary keys for locality plus UUID/external IDs for distributed references. Background workers process outbox events, reconciliation, provider polling, and asynchronous verification rather than blocking user requests.
PHP API nodes should remain stateless except for explicitly externalized session/auth state. This allows multiple web servers behind a load balancer. Uploaded documents, if a regulated workflow requires them, must go to encrypted object storage rather than local server disks.
If the AI provider fails, normal wallet signing still works. If a KYC provider fails, compliance-required workflows may pause while ordinary wallet features continue. If CIP-113 infrastructure is unavailable, standard native assets remain available. If Midnight is unavailable, privacy-dependent workflows pause but Gold wallet features remain. If one bank/remittance provider is unavailable, the Settlement Router can use another permitted route or clearly tell the user that the corridor is temporarily unavailable.
Before unrestricted production usage, Coxy requires independent review of the software vault, Cardano key derivation/recovery, transaction builder and semantic preview, CIP-30 bridge, browser-extension messaging, hardware signer integration, identity key handling, KERI/KEL verification, ACDC credential verification, CIP-0170 metadata codec, programmable-token contracts, issuer administration, Midnight privacy integration, remittance/banking APIs, authentication/authorization, and AI data boundaries.
A draft or unaudited reference implementation is never treated as production-ready solely because it is part of a CIP discussion. Every Coxy-controlled on-chain contract that can lock, transfer, freeze, seize, mint, burn, or otherwise affect customer assets requires a professional contract audit appropriate to its value at risk. Mainnet activation occurs only after critical and high-severity findings are fixed or formally accepted through a documented risk process.
The no-framework architecture reduces dependency count but does not remove supply-chain risk. Every third-party JavaScript/PHP/cryptographic package must be pinned, license-reviewed, vulnerability-scanned, and periodically updated. Extension builds must be reproducible or at least deterministically verifiable where possible. Release artifacts must be generated by controlled CI and checksummed.
Each module's docs/threat-model.md identifies assets, trust boundaries, attackers, abuse cases, controls, residual risk, and required monitoring. High-risk modules use a structured method such as STRIDE as a checklist, but the output must remain specific to Coxy rather than becoming generic security paperwork.
Coxy maintains runbooks for compromised release keys, malicious dependency discovery, provider breach, suspected seed exposure, fraudulent dApp campaign, identity-verifier compromise, issuer-key compromise, programmable-contract vulnerability, bank-provider incident, remittance misrouting, AI data leak, and database compromise. Feature flags and provider kill switches are part of incident response.
The full four-mode vision is a multi-disciplinary programme. The following roles do not all need to be full-time at once, but every responsibility requires a named owner before its module enters production.
| Resource | Responsibility |
|---|---|
| Product lead | The product lead owns mode definitions, customer journeys, release scope, partner requirements, and the boundary between educational and advanced capabilities. |
| Architecture lead | The architecture lead enforces module contracts, dependency direction, shared-core stability, versioning, and architecture decision records. |
| Cardano wallet engineers | These engineers own key derivation, transaction construction, staking/governance, CIP-30, metadata, native assets, provider integration, and Cardano regression tests. |
| Browser-extension engineers | These engineers own Manifest V3, content/injected/service-worker boundaries, permissions, signing approvals, extension updates, and dApp security. |
| Vanilla web engineers | These engineers build HTML/CSS/JavaScript interfaces and Web Components for the four modes without introducing a large application framework. |
| PHP backend engineers | These engineers own APIs, provider adapters, authorization, background jobs, reconciliation, and server-side validation. |
| MySQL/data engineer | This engineer owns schema design, indexes, migrations, backup/restore, replicas, archival, and query performance. |
| On-chain engineers | These engineers own Cardano validators/minting policies and future chain-specific contract artifacts, formal properties, and audit remediation. |
| Identity/KERI engineers | These engineers own KERI client integration, KEL discovery, ACDC credentials, trust roots, CIP-0170, and vLEI interoperability. |
| Privacy engineer | This engineer owns the Midnight adapter, proof/disclosure workflows, privacy threat model, and boundary between public and private data. |
| Security engineers | These engineers own vault review, secure coding, cryptographic review, threat models, CI security checks, penetration testing coordination, and incident response. |
| QA/test engineers | These engineers own regression, integration, property, end-to-end, failure-injection, compatibility, and release acceptance testing. |
| DevOps/SRE | These engineers own CI/CD, environments, secret management, monitoring, backups, provider health, failover, release infrastructure, and disaster recovery. |
| Compliance/legal specialists | These specialists map KYC/AML/CFT, sanctions, Travel Rule, privacy, consumer disclosure, RWA, banking, and remittance requirements to actual jurisdictions and partner responsibilities. |
| Financial-integration engineers | These engineers own bank, AD/ADLA, PSP, CASP, FX, remittance, liquidity, ISO 20022 mapping, and reconciliation adapters. |
| AI engineers | These engineers own the Assistant/Guardian model gateway, redaction, evaluation, prompt-injection defenses, deterministic-rule integration, and model monitoring. |
| UX/content specialists | These specialists preserve Silver simplicity, create advanced disclosures, explain issuer powers, and ensure financial/identity workflows are understandable. |
Required environments include local development, automated test, Cardano Preview/Preprod, controlled Cardano Mainnet, KERI/KERIA test infrastructure, identity verifier infrastructure, Midnight development/test environments, financial-provider sandboxes, MySQL test/staging/production clusters, secure object storage where legally required, secrets management, CI runners, centralized structured logging, metrics, alerting, backup storage, and isolated security-testing environments.
Issuer or institutional administration should have access to hardware signing or HSM-grade controls appropriate to the authority being exercised. Production signing/release credentials should never be stored on ordinary shared-hosting file systems.
The delivery plan is capability-gated rather than date-gated. Later phases may be developed experimentally in parallel, but a phase does not become production-enabled until its prerequisites and security gates pass.
Create a complete regression suite for the current Coxy wallet. Capture the current storage formats, transaction fixtures, restore behavior, extension behavior, token-minting behavior, and known provider dependencies. Add feature flags before integrating advanced features. The exit condition is that a clean build can prove the existing Coxy behavior without any new module enabled.
Move existing capabilities behind the atomic module layout without rewriting working logic unnecessarily. Introduce module manifests, explicit dependencies, shared contracts, code ownership, documentation templates, module health checks, and boundary linting. The exit condition is that a module can be disabled without manual code deletion.
Wrap the current Coxy wallet in CoxyNativeWalletSession. Implement normalized transaction plans and signer capability interfaces. Add transaction semantic preview. The exit condition is that Silver uses the new interface while producing the same wallet behavior as before.
Make Coxy a compliant CIP-30 provider for Cardano dApps. Implement origin permissions, connection revocation, signTx/signData approval, network handling, extension capability reporting, and malicious-origin tests. The exit condition is successful integration with representative Cardano dApps on test networks without weakening the vault boundary.
Add provider discovery and Cip30WalletSession. Normalize Lace, Eternl, and other representative providers through the same interface. Add account-change detection and capability negotiation. The exit condition is that Coxy services can build a transaction and let the external wallet remain the exclusive signer.
Add the hardware signer module, starting with a supported Trezor integration and architecture for additional signers. Test serialization, device prompts, rejection, disconnect, wrong-device/account conditions, and upgrade compatibility. The exit condition is that hardware signing does not require importing the hardware seed into Coxy.
Implement ALLOW, DENY, and REVIEW policy decisions, evidence objects, policy versions, provider adapters, audit records, and deterministic policy tests. This phase is deliberately before Diamond identity and programmable assets so both use the same policy system.
Implement generic metadata support, then versioned CIP-0170 structures and strict parsing. Use fixtures before connecting real KERI infrastructure. The exit condition is deterministic encode/decode/validation and successful testnet metadata transactions without changing standard wallet transaction behavior.
Integrate a standards-compatible KERI client/agent model. Add AID creation, KEL resolution, OOBI/watcher discovery as appropriate, interaction events, rotation, credential reception, credential verification, registry/revocation state, and trust-root configuration. The exit condition is a complete identity lifecycle in a controlled test environment.
Connect CIP-0170 authority and attestation records to KERI/KEL/credential verification. Add external-wallet identity binding. Add organization/role credential views and evidence-based verification. The exit condition is a verifier that can explain why a record is valid or invalid rather than returning only a boolean.
Integrate the current CIP-113 candidate architecture behind a versioned adapter. Build token discovery, programmable balance aggregation, transfer planning, issuer capability disclosure, policy preflight, and testnet mint/transfer/freeze/seize functionality only to the extent supported by the audited implementation in use. Mainnet remains feature-flagged until standards and audits justify activation.
Add issuer identity, asset documentation references, subscription/redemption workflows, holder eligibility, corporate actions, administration approvals, and audit evidence. Use a controlled test RWA before any production asset claim.
Add privacy-proof/disclosure adapters for selected high-value use cases, beginning with a narrow statement such as credential validity or eligibility. Prove that personal documents do not leak to Cardano logs, metadata, AI, or analytics. The exit condition is a reviewed selective-disclosure flow rather than a generic "privacy mode" switch.
Run independent security reviews, identity-verifier testing, programmable-contract audits, privacy review, and organization pilot. Diamond goes from internal to invited pilot to controlled production. Silver and Gold remain independently usable during every stage.
Add normalized chain/account/asset identifiers and implement Bitcoin/Ethereum adapters behind the ChainAdapter contract. Do not add fiat to ChainAdapter. Build portfolio aggregation and chain-specific risk/fee display.
Add stablecoin metadata/risk, FiatAccountProvider, FxProvider, BankingProvider, consent/token storage, beneficiary model, quotes, fees, and reconciliation. Complete institutional and legal onboarding with initial regulated partners before enabling customer money movement.
Implement corridor configuration, quote aggregation, compliance orchestration, settlement scoring, beneficiary verification, Travel Rule data orchestration, payment status, refunds/failures, provider callbacks, reconciliation, audit, and reporting adapters. Launch one corridor first; do not treat technical reachability as regulatory availability.
Add FinancialProtocolAdapter, risk disclosure, position aggregation, action planning, and explicit user approval. Protocols are independently feature-flagged and can be removed without breaking core wallet or banking functions.
Launch Platinum through staged limits, selected corridors, selected chains, selected stablecoins, selected financial partners, and selected RealFi protocols. Security, regulatory, operational, and liquidity readiness are separate release gates.
New chains, banks, remittance corridors, hardware wallets, CIPs, privacy capabilities, stablecoins, and identity ecosystems are added as providers/modules. The core contracts change only through backward-compatible versioning or documented architecture migrations.
Silver passes when wallet creation/recovery is deterministic, secrets are encrypted, transaction previews match serialized transactions, send/receive/staking workflows pass regression, and advanced modules can be fully disabled without affecting operation.
Gold passes when Coxy functions as a secure CIP-30 provider, external providers can be connected without seed import, capability negotiation is reliable, account/network changes are detected, hardware signing is isolated, and dApp-origin/permission security has undergone external review.
Diamond passes when KERI/credential verification is evidence-based, identity keys are separated from Cardano keys, CIP-0170 authority windows and revocation are tested, programmable-asset contracts used in production have independent audits, issuer powers are disclosed, privacy workflows have data-flow review, and KYC/AML integrations have jurisdiction-specific policy approval.
Platinum passes when chain adapters are isolated, stablecoin/fiat representations are unambiguous, regulated partners are contractually and technically integrated, corridor policy is approved, Travel Rule/reporting requirements are mapped, payment reconciliation is proven, provider failover is tested, fraud controls are active, and no payment can be released merely because an AI system recommended it.
No mode may launch a material feature when there is an unresolved critical vulnerability, a known path to expose private keys, an unreviewed production contract with custody/issuer power, a migration that can silently destroy wallet recovery data, an inability to reconcile customer money, or a compliance requirement that the responsible organization has not mapped to an accountable owner.
The modular structure is specifically intended to allow many developers to participate. Each module has code owners, an issue backlog, test command, documentation, security owner, and stable public contract. A developer working on remittance should not need to understand KERI internals. A developer working on KERI should not need to edit the Bitcoin adapter. A developer changing a Gold wallet connector should be protected by Silver regression tests and module-boundary checks.
Every significant architectural decision is recorded in docs/adr/ as an Architecture Decision Record. The ADR states the problem, decision, alternatives, security implications, migration implications, and modules affected. Pull requests that create a new shared dependency or cross-module data access require an ADR.
Feature branches should remain module-scoped where possible. High-risk modules require at least one security reviewer in addition to a domain reviewer. SQL migrations require data review. On-chain changes require on-chain/security review. Financial-provider changes require integration and compliance review. Release branches are generated only after the cross-module regression suite passes.
Every module README must explain purpose, mode availability, public API, external providers, secrets accessed, database tables, events produced/consumed, test commands, feature flags, failure behavior, and rollback. A new developer should be able to run a module locally from its documentation without reverse-engineering unrelated code.
Coxy Diamond and Platinum are intended to be available on web, iOS, and Android. This specification deliberately does not define the detailed native iOS or Android architecture because mobile secure-storage APIs, signing, background execution, application lifecycle, biometric integration, app-store policy, and mobile dApp connectivity require dedicated specifications.
The current architecture protects that future work by keeping business contracts platform-neutral. WalletSession, TransactionPlan, PolicyDecision, IdentityService, ChainAdapter, BankingProvider, and other domain contracts must be reusable by a future mobile client even if the native security/storage implementation differs. The web implementation remains vanilla JavaScript/HTML/CSS, and PHP/MySQL remains the primary server stack unless a future architecture decision explicitly changes it.
The Coxy application code should be released under the MIT License unless a specific repository or component requires a different legally reviewed licensing arrangement. Third-party libraries, Cardano specifications, KERI components, Midnight tooling, hardware-wallet SDKs, and other external works retain their own licences and are not relicensed merely because Coxy integrates them.
The root repository should contain the following standard notice:
MIT License
Copyright (c) 2026 Coxy contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
ACDC — Authentic Chained Data Container. A verifiable credential/data-container model used in the KERI ecosystem and in vLEI-related trust structures. Coxy uses ACDC through the credential layer rather than inventing a proprietary credential format.
ADA. The native asset of the Cardano network. Silver introduces ADA in beginner-friendly terms; all higher modes retain ordinary ADA functionality.
AD — Authorised Dealer. In the South African foreign-exchange context, an entity authorized to deal in foreign exchange according to the applicable SARB framework.
ADLA — Authorised Dealer in foreign exchange with Limited Authority. A South African category that may conduct specified foreign-exchange activities. Current SARB materials include categories for money-remittance and independent value-transfer activities.
AI Assistant. Coxy's constrained user-help capability that explains features, transactions, identity, finance, and security in the language appropriate to the selected mode.
AI Guardian. Coxy's advisory risk-analysis capability that combines deterministic security signals with optional model-based pattern analysis. It does not sign or override mandatory policy.
AID — Autonomic Identifier. A self-certifying identifier in KERI. Coxy's Identity module uses an AID as the persistent identity/controller identifier rather than equating an identity with a Cardano address.
AML — Anti-Money Laundering. Controls designed to detect, prevent, report, or manage money-laundering risk according to applicable law and policy. Coxy treats AML as provider-driven and jurisdiction-specific.
API — Application Programming Interface. A declared technical interface through which Coxy modules or external providers communicate.
Atomic module. A Coxy component that owns its code, UI, off-chain logic, on-chain artifacts, backend, SQL, server processes, integrations, tests, and documentation and can be enabled or disabled with minimal effect on other modules.
Audit trail. A durable record of significant security, identity, issuer, compliance, or payment events that supports investigation and accountability.
Beneficiary. The recipient of a bank or remittance payment.
CBOR — Concise Binary Object Representation. A binary serialization format used extensively in Cardano transaction structures and related standards.
ChainAdapter. Coxy's internal contract that normalizes account, balance, fee, transaction, broadcast, and status behavior for a blockchain.
CFT — Countering the Financing of Terrorism. Policies and controls addressing terrorist-financing risks.
CIP — Cardano Improvement Proposal. A Cardano ecosystem standards/proposal process. Coxy tracks a CIP's actual status and does not assume that every proposed or draft CIP is production-stable.
CIP-0003. Cardano wallet key-generation specification relevant to wallet recovery and deterministic key generation.
CIP-0021. Cardano transaction requirements for interoperability with hardware wallets.
CIP-0030. Active Cardano dApp-wallet web bridge specification used by web applications and wallet extensions.
CIP-0095. Active CIP-30 extension for Conway-era governance capabilities.
CIP-0170. Proposed KERI-backed Cardano metadata-attestation specification that defines authority establishment, attestations, and authority revocation using Cardano metadata and KERI/ACDC evidence.
CIP-113. Draft programmable-token work that adds transfer-time validation and issuer/asset control capabilities. Coxy treats this as an evolving adapter and requires audit/maturity gates before production use.
CIP-1852. Active Cardano hierarchical deterministic wallet derivation scheme using purpose 1852' and Cardano-specific roles.
Compliance evidence. Structured information showing which policy checks were performed, by which provider/version, at what time, and with what result.
Coxy Native WalletSession. The WalletSession implementation that uses Coxy's own encrypted wallet vault and transaction-signing path.
CIP-30 WalletSession. The WalletSession implementation that delegates key custody and signing to an external compatible Cardano wallet.
Diamond. Coxy mode that combines Gold functionality with identity, compliance, programmable assets, RWA capabilities, and privacy integration.
Event outbox. A MySQL-backed pattern that stores domain events in the same transaction as business state so asynchronous publication can be retried safely.
Feature flag. A runtime or configuration control that enables/disables a capability without deleting code or changing unrelated modules.
Fiat. Government-issued currency such as ZAR, USD, EUR, or GBP. Coxy represents fiat through banking/payment providers rather than pretending it is a blockchain asset.
FinSurv. South African Financial Surveillance reporting context operated by SARB for relevant cross-border flows.
FX — Foreign Exchange. Conversion between currencies, including quote, spread, fees, settlement, and reporting considerations.
Gold. Coxy mode for advanced Cardano users, external CIP-30 wallets, hardware signers, dApps, and advanced Cardano functionality.
Hardware signer. A device such as a supported Trezor model that keeps signing keys in dedicated hardware and authorizes transaction signatures without exposing the private key to Coxy.
Identity Vault. The security zone containing KERI/identity client secret material, separate from the Cardano seed vault.
Issuer administration. High-authority asset functions such as mint, freeze, seize, forced transfer, redemption, or policy changes. These require stronger controls than ordinary wallet transfers.
KEL — Key Event Log. A KERI identifier's cryptographically verifiable history of inception, rotation, interaction, and related key events.
KERI — Key Event Receipt Infrastructure. A key-event-based identity protocol supporting self-certifying identifiers and portable key-state verification.
KERIA. A KERI agent architecture that can handle agent operations while keeping client signing/secret operations at the edge through the Signify model.
KYC — Know Your Customer. Identity/customer verification controls required by particular institutions, products, or jurisdictions. Coxy treats KYC results as policy evidence, not as public blockchain data.
Midnight. A privacy-oriented blockchain/network integrated by Coxy through a separate privacy/chain adapter for selective-disclosure and zero-knowledge use cases.
Mode Manager. The Coxy core component that maps Silver, Gold, Diamond, and Platinum profiles to enabled capabilities and feature flags.
Module manifest. module.json, which declares a module's identifier, version, mode availability, dependencies, permissions, events, and health endpoint.
Multi-chain. Platinum capability to represent and operate across Cardano, Bitcoin, Ethereum, Midnight, and future networks through independent ChainAdapters.
On-chain. Logic or data executed/stored by a blockchain network. Coxy isolates chain-native contract source and compiled artifacts inside each relevant module's onchain/ directory.
Off-chain. Logic performed by the wallet, browser, server, identity verifier, indexer, or provider rather than by blockchain consensus.
Out-of-Band Introduction (OOBI). A KERI mechanism used to discover/introduce identifier-related network information and infrastructure.
Platinum. Coxy's global-finance mode, adding multi-chain, stablecoin services, fiat, banks, cross-border remittances, settlement routing, RealFi, and advanced financial integrations to Diamond.
Policy Engine. The shared deterministic Coxy service that combines rules and evidence into ALLOW, DENY, or REVIEW decisions.
Programmable asset. An asset whose transfer/mint/burn behavior is subject to on-chain or protocol-defined validation logic beyond ordinary native-token behavior.
Provider adapter. A small component that converts a third-party API or infrastructure provider into a stable Coxy internal contract.
RealFi. Real-world/decentralized finance integrations that connect blockchain-based assets and financial protocols with real economic or credit activity. In Coxy, RealFi is provider/protocol-driven rather than hard-coded into the wallet core.
RWA — Real-World Asset. A digital asset or token workflow linked to a real-world legal, financial, physical, or contractual asset/claim. The token technology alone does not establish legal enforceability.
Sanctions screening. A policy process that checks relevant parties or transactions against applicable sanctions restrictions using approved data/providers.
Settlement Router. Platinum service that selects among legally and operationally available bank, stablecoin, crypto, or other settlement routes according to policy, price, speed, liquidity, and risk.
Silver. Coxy's original simplified training and beginner wallet mode.
SignerProvider. An internal interface through which Coxy requests a cryptographic signature without receiving the private key.
SSI — Self-Sovereign Identity. A broad identity model in which users or organizations control portable cryptographic identifiers and credentials. Coxy's Diamond architecture uses KERI/ACDC capabilities in this direction.
Stablecoin. A digital asset designed to track a reference value, commonly a fiat currency. Stablecoins can be fiat-backed, crypto-backed, synthetic, bridged, or implemented through other mechanisms and therefore have different risks.
Travel Rule. Payment/virtual-asset transparency requirements that require specified originator and beneficiary information to accompany certain regulated transfers. Required data should be exchanged through regulated channels rather than written publicly to a blockchain.
TransactionPlan. Coxy's chain-neutral semantic representation of the actions, values, fees, metadata, warnings, and expected effects that the user reviews before serialization and signing.
vLEI — verifiable Legal Entity Identifier. A GLEIF-governed verifiable organizational identity ecosystem built using KERI/ACDC-related technology and qualified issuers.
WalletSession. Coxy's normalized wallet interface that lets modules query public wallet state, request signatures, and submit transactions without depending on where keys are held.
ZAR. The South African rand, a fiat currency. It belongs in the Fiat/Banking layer, not the cryptocurrency ChainAdapter.
Zero-Knowledge Proof (ZKP). A cryptographic proof that can establish a statement without revealing all underlying private information. Coxy uses ZKP/privacy capabilities only through defined disclosure and policy workflows.
The following sources informed the product and architecture decisions in this specification. Standards and product status can change, so Coxy engineering must re-check the current version/status before every production release that depends on a specific external standard.
[S1] CIP-0030 — Cardano dApp-Wallet Web Bridge (Active)
https://cips.cardano.org/cip/CIP-0030
[S2] CIP-30 Accepted Extensions Register
https://cips.cardano.org/cip/CIP-30/annex/extensions-register
[S20] CIP-0095 — Web-Wallet Bridge, Conway ledger era (Active)
https://cips.cardano.org/cips/cip95
[S21] CIP-0003 — Wallet Key Generation
https://cips.cardano.org/cip/CIP-0003
[S22] CIP-1852 — HD Wallets for Cardano (Active)
https://cips.cardano.org/cip/CIP-1852
[S23] CIP-0021 — Transaction requirements for interoperability with hardware wallets
https://cips.cardano.org/cip/CIP-0021
[S3] CIP-0170 — KERI-backed metadata attestations (Proposed)
https://cips.cardano.org/cip/CIP-0170
[S8] Cardano Foundation — Veridian Wallet
https://github.com/cardano-foundation/veridian-wallet
[S9] WebOfTrust — KERIA
https://github.com/WebOfTrust/keria
[S10] GLEIF — vLEI Ecosystem Governance Framework
https://www.gleif.org/en/organizational-identity/become-a-vlei-issuer-qvi/vlei-ecosystem-governance-framework
[S4] Cardano Developer Portal — Programmable Tokens / CIP-113
https://developers.cardano.org/docs/developers/curriculum/native-tokens/programmable-tokens/
[S5] Cardano Foundation Q1 2026 Development Report — CIP-113 progress
https://developers.cardano.org/blog/2026-01-31-quarterly-development-report/
[S24] CIP-0143 — Interoperable Programmable Tokens (historical/inactive predecessor incorporated into candidate CIP-113 work)
https://cips.cardano.org/cip/CIP-0143
[S6] Midnight — Midnight Network is Live
https://midnight.network/blog/midnight-network-is-live
[S7] Midnight Developer Documentation
https://docs.midnight.network/
[S25] Midnight Network Overview — selective disclosure and public/private state
https://midnight.network/overview
[S11] Trezor — Cardano wallet support
https://trezor.io/coins/wallet/cardano
[S12] Chrome for Developers — Manifest V3
https://developer.chrome.com/docs/extensions/develop/migrate/what-is-mv3
[S26] Chrome for Developers — Improve extension security
https://developer.chrome.com/docs/extensions/develop/migrate/improve-security
[S13] Cardano — Stablecoins on Cardano
https://cardano.org/stablecoins/
[S14] South African Reserve Bank — Financial Surveillance FAQ
https://www.resbank.co.za/en/home/what-we-do/financial-surveillance/FinSurvFAQ
[S15] South African Reserve Bank — Authorised Dealers in foreign exchange with Limited Authority (ADLAs)
https://www.resbank.co.za/en/home/what-we-do/financial-surveillance/adlas
[S16] Financial Intelligence Centre — Directive 9 Travel Rule advisory
https://www.fic.gov.za/2025/04/17/joint-advisory-directive-9-of-2024-on-implementation-of-the-travel-rule-to-enhance-transparency-in-crypto-asset-transactions-takes-effect-on-30-april-2025/
[S17] FATF — Updated Recommendation 16 on Payment Transparency, June 2025
https://www.fatf-gafi.org/en/publications/Fatfrecommendations/update-Recommendation-16-payment-transparency-june-2025.html
[S18] BIS/CPMI — Harmonised ISO 20022 data requirements for enhancing cross-border payments, updated February 2026
https://www.bis.org/cpmi/publ/d230.htm
[S19] BIS/CPMI — Building Block 15: Harmonising API protocols for data exchange
https://www.bis.org/cpmi/cross_border/bb15.htm
Coxy should preserve the educational simplicity that created Silver while treating every advanced capability as an independently testable provider or module. Gold makes the product interoperable with Cardano's broader wallet and hardware ecosystem. Diamond turns the wallet into an identity, credential, policy, programmable-asset, RWA, and privacy platform. Platinum extends the same architecture into multi-chain assets, stablecoins, fiat, regulated banking integrations, cross-border remittances, settlement routing, RealFi, and global financial services.
The long-term competitive advantage is not that Coxy supports one particular CIP or one particular bank. The advantage is that Coxy has a small, understandable core and a disciplined module boundary through which new standards, networks, institutions, and financial technologies can be added without destabilizing the user's wallet. Security, auditability, provider independence, explicit user authorization, privacy-aware data handling, and rigorous tests are therefore part of the product definition rather than implementation details.