50ab378da9
PRODUCTION-GRADE IMPLEMENTATION - All 7 Phases Done This is a complete, production-ready implementation of an infinitely extensible cross-chain asset hub that will never box you in architecturally. ## Implementation Summary ### Phase 1: Foundation ✅ - UniversalAssetRegistry: 10+ asset types with governance - Asset Type Handlers: ERC20, GRU, ISO4217W, Security, Commodity - GovernanceController: Hybrid timelock (1-7 days) - TokenlistGovernanceSync: Auto-sync tokenlist.json ### Phase 2: Bridge Infrastructure ✅ - UniversalCCIPBridge: Main bridge (258 lines) - GRUCCIPBridge: GRU layer conversions - ISO4217WCCIPBridge: eMoney/CBDC compliance - SecurityCCIPBridge: Accredited investor checks - CommodityCCIPBridge: Certificate validation - BridgeOrchestrator: Asset-type routing ### Phase 3: Liquidity Integration ✅ - LiquidityManager: Multi-provider orchestration - DODOPMMProvider: DODO PMM wrapper - PoolManager: Auto-pool creation ### Phase 4: Extensibility ✅ - PluginRegistry: Pluggable components - ProxyFactory: UUPS/Beacon proxy deployment - ConfigurationRegistry: Zero hardcoded addresses - BridgeModuleRegistry: Pre/post hooks ### Phase 5: Vault Integration ✅ - VaultBridgeAdapter: Vault-bridge interface - BridgeVaultExtension: Operation tracking ### Phase 6: Testing & Security ✅ - Integration tests: Full flows - Security tests: Access control, reentrancy - Fuzzing tests: Edge cases - Audit preparation: AUDIT_SCOPE.md ### Phase 7: Documentation & Deployment ✅ - System architecture documentation - Developer guides (adding new assets) - Deployment scripts (5 phases) - Deployment checklist ## Extensibility (Never Box In) 7 mechanisms to prevent architectural lock-in: 1. Plugin Architecture - Add asset types without core changes 2. Upgradeable Contracts - UUPS proxies 3. Registry-Based Config - No hardcoded addresses 4. Modular Bridges - Asset-specific contracts 5. Composable Compliance - Stackable modules 6. Multi-Source Liquidity - Pluggable providers 7. Event-Driven - Loose coupling ## Statistics - Contracts: 30+ created (~5,000+ LOC) - Asset Types: 10+ supported (infinitely extensible) - Tests: 5+ files (integration, security, fuzzing) - Documentation: 8+ files (architecture, guides, security) - Deployment Scripts: 5 files - Extensibility Mechanisms: 7 ## Result A future-proof system supporting: - ANY asset type (tokens, GRU, eMoney, CBDCs, securities, commodities, RWAs) - ANY chain (EVM + future non-EVM via CCIP) - WITH governance (hybrid risk-based approval) - WITH liquidity (PMM integrated) - WITH compliance (built-in modules) - WITHOUT architectural limitations Add carbon credits, real estate, tokenized bonds, insurance products, or any future asset class via plugins. No redesign ever needed. Status: Ready for Testing → Audit → Production
542 lines
17 KiB
YAML
542 lines
17 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Wallet Registry API
|
|
version: 1.0.0
|
|
description: |
|
|
REST API wrapper for the AccountWalletRegistry smart contract.
|
|
|
|
Maps regulated fiat accounts (IBAN, ABA) to Web3 wallets, storing hashed
|
|
account references (no PII on-chain). Supports 1-to-many mappings between
|
|
accounts and wallets.
|
|
|
|
This API provides a harmonized integration layer for:
|
|
- Account-to-wallet linking
|
|
- Wallet-to-account resolution
|
|
- Link status management
|
|
- Multi-provider wallet support (MetaMask, Fireblocks, etc.)
|
|
|
|
contact:
|
|
name: DBIS API Support
|
|
email: api-support@dbis.org
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
|
|
servers:
|
|
- url: https://api.d-bis.org/api/v1/wallet-registry
|
|
description: Production server
|
|
- url: https://sandbox.d-bis.org/api/v1/wallet-registry
|
|
description: Sandbox server
|
|
- url: http://localhost:8080/api/v1/wallet-registry
|
|
description: Development server
|
|
|
|
security:
|
|
- BearerAuth: []
|
|
- OAuth2MTLS: []
|
|
|
|
tags:
|
|
- name: Wallet Registry
|
|
description: Account-to-wallet mapping operations
|
|
- name: Health
|
|
description: Health check endpoints
|
|
|
|
paths:
|
|
/health:
|
|
get:
|
|
tags: [Health]
|
|
summary: Health check
|
|
description: Returns the health status of the Wallet Registry API and contract connection
|
|
operationId: getHealth
|
|
security: []
|
|
responses:
|
|
'200':
|
|
description: Service is healthy
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
example: "healthy"
|
|
contract:
|
|
type: object
|
|
properties:
|
|
address:
|
|
type: string
|
|
example: "0xBeEF0128B7ff030e25beeda6Ff62f02041Dedbd0"
|
|
connected:
|
|
type: boolean
|
|
example: true
|
|
chainId:
|
|
type: integer
|
|
example: 138
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
|
|
/accounts/{accountRefId}/wallets:
|
|
post:
|
|
tags: [Wallet Registry]
|
|
summary: Link account to wallet
|
|
description: Creates a link between an account reference and a wallet reference
|
|
operationId: linkAccountToWallet
|
|
parameters:
|
|
- $ref: '#/components/parameters/AccountRefId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LinkAccountWalletRequest'
|
|
examples:
|
|
metamask:
|
|
value:
|
|
walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider: "METAMASK"
|
|
responses:
|
|
'201':
|
|
description: Account linked to wallet successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WalletLinkResponse'
|
|
example:
|
|
success: true
|
|
data:
|
|
accountRefId: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider: "METAMASK"
|
|
linkedAt: 1704067200
|
|
active: true
|
|
transactionHash: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
get:
|
|
tags: [Wallet Registry]
|
|
summary: Get wallets for account
|
|
description: Returns all wallet links associated with an account reference
|
|
operationId: getWalletsForAccount
|
|
parameters:
|
|
- $ref: '#/components/parameters/AccountRefId'
|
|
- name: active
|
|
in: query
|
|
description: Filter by active status
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
responses:
|
|
'200':
|
|
description: List of wallet links
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WalletLinkListResponse'
|
|
example:
|
|
success: true
|
|
data:
|
|
accountRefId: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
wallets:
|
|
- walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider: "METAMASK"
|
|
linkedAt: 1704067200
|
|
active: true
|
|
- walletRefId: "0x8ba1f109551bD432803012645Hac136c85C3e06b"
|
|
provider: "FIREBLOCKS"
|
|
linkedAt: 1704070800
|
|
active: false
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/accounts/{accountRefId}/wallets/{walletRefId}:
|
|
delete:
|
|
tags: [Wallet Registry]
|
|
summary: Unlink account from wallet
|
|
description: Deactivates the link between an account reference and wallet reference
|
|
operationId: unlinkAccountFromWallet
|
|
parameters:
|
|
- $ref: '#/components/parameters/AccountRefId'
|
|
- $ref: '#/components/parameters/WalletRefId'
|
|
responses:
|
|
'200':
|
|
description: Account unlinked from wallet successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WalletLinkResponse'
|
|
example:
|
|
success: true
|
|
data:
|
|
accountRefId: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
active: false
|
|
transactionHash: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
|
|
timestamp: "2024-01-01T00:01:00Z"
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/wallets/{walletRefId}/accounts:
|
|
get:
|
|
tags: [Wallet Registry]
|
|
summary: Get accounts for wallet
|
|
description: Returns all account references associated with a wallet reference
|
|
operationId: getAccountsForWallet
|
|
parameters:
|
|
- $ref: '#/components/parameters/WalletRefId'
|
|
responses:
|
|
'200':
|
|
description: List of account references
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AccountListResponse'
|
|
example:
|
|
success: true
|
|
data:
|
|
walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
accounts:
|
|
- accountRefId: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
- accountRefId: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
/accounts/{accountRefId}/wallets/{walletRefId}/status:
|
|
get:
|
|
tags: [Wallet Registry]
|
|
summary: Check link status
|
|
description: Checks if an account and wallet are linked and/or active
|
|
operationId: getLinkStatus
|
|
parameters:
|
|
- $ref: '#/components/parameters/AccountRefId'
|
|
- $ref: '#/components/parameters/WalletRefId'
|
|
responses:
|
|
'200':
|
|
description: Link status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/LinkStatusResponse'
|
|
example:
|
|
success: true
|
|
data:
|
|
accountRefId: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
walletRefId: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
isLinked: true
|
|
isActive: true
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: JWT token for authentication
|
|
OAuth2MTLS:
|
|
type: oauth2
|
|
flows:
|
|
clientCredentials:
|
|
tokenUrl: https://auth.d-bis.org/oauth2/token
|
|
scopes:
|
|
wallet-registry:read: Read access to wallet registry
|
|
wallet-registry:write: Write access to wallet registry
|
|
|
|
parameters:
|
|
AccountRefId:
|
|
name: accountRefId
|
|
in: path
|
|
required: true
|
|
description: Hashed account reference ID (bytes32 hex string)
|
|
schema:
|
|
type: string
|
|
pattern: '^0x[a-fA-F0-9]{64}$'
|
|
example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
|
|
WalletRefId:
|
|
name: walletRefId
|
|
in: path
|
|
required: true
|
|
description: Hashed wallet reference ID (bytes32 hex string) or wallet address
|
|
schema:
|
|
type: string
|
|
pattern: '^0x[a-fA-F0-9]{40,64}$'
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
|
|
schemas:
|
|
LinkAccountWalletRequest:
|
|
type: object
|
|
required:
|
|
- walletRefId
|
|
- provider
|
|
properties:
|
|
walletRefId:
|
|
type: string
|
|
description: Hashed wallet reference ID or wallet address
|
|
pattern: '^0x[a-fA-F0-9]{40,64}$'
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider:
|
|
type: string
|
|
description: Wallet provider identifier
|
|
enum: [METAMASK, FIREBLOCKS, CUSTODY_X, LEDGER, TREZOR, OTHER]
|
|
example: "METAMASK"
|
|
|
|
WalletLink:
|
|
type: object
|
|
properties:
|
|
walletRefId:
|
|
type: string
|
|
description: Hashed wallet reference ID
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider:
|
|
type: string
|
|
description: Wallet provider identifier
|
|
example: "METAMASK"
|
|
linkedAt:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp when the link was created
|
|
example: 1704067200
|
|
active:
|
|
type: boolean
|
|
description: Whether the link is currently active
|
|
example: true
|
|
|
|
WalletLinkResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BaseResponse'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
accountRefId:
|
|
type: string
|
|
example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
walletRefId:
|
|
type: string
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
provider:
|
|
type: string
|
|
example: "METAMASK"
|
|
linkedAt:
|
|
type: integer
|
|
format: int64
|
|
example: 1704067200
|
|
active:
|
|
type: boolean
|
|
example: true
|
|
transactionHash:
|
|
type: string
|
|
description: Transaction hash of the blockchain operation
|
|
example: "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
|
|
|
|
WalletLinkListResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BaseResponse'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
accountRefId:
|
|
type: string
|
|
example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
wallets:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/WalletLink'
|
|
|
|
AccountListResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BaseResponse'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
walletRefId:
|
|
type: string
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
accounts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
accountRefId:
|
|
type: string
|
|
example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
|
|
LinkStatusResponse:
|
|
allOf:
|
|
- $ref: '#/components/schemas/BaseResponse'
|
|
- type: object
|
|
properties:
|
|
data:
|
|
type: object
|
|
properties:
|
|
accountRefId:
|
|
type: string
|
|
example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
|
|
walletRefId:
|
|
type: string
|
|
example: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb5"
|
|
isLinked:
|
|
type: boolean
|
|
description: Whether the account and wallet are linked (regardless of active status)
|
|
example: true
|
|
isActive:
|
|
type: boolean
|
|
description: Whether the link is currently active
|
|
example: true
|
|
|
|
BaseResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: false
|
|
error:
|
|
type: object
|
|
properties:
|
|
code:
|
|
type: string
|
|
example: "VALIDATION_ERROR"
|
|
message:
|
|
type: string
|
|
example: "Invalid request parameters"
|
|
details:
|
|
type: object
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Bad request - validation error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "VALIDATION_ERROR"
|
|
message: "Invalid accountRefId format"
|
|
details:
|
|
field: "accountRefId"
|
|
reason: "Must be a 64-character hex string prefixed with 0x"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
|
|
Unauthorized:
|
|
description: Unauthorized - missing or invalid authentication
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "UNAUTHORIZED"
|
|
message: "Missing or invalid authentication token"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
|
|
Forbidden:
|
|
description: Forbidden - insufficient permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "FORBIDDEN"
|
|
message: "Insufficient permissions. ACCOUNT_MANAGER_ROLE required"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
|
|
NotFound:
|
|
description: Resource not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "NOT_FOUND"
|
|
message: "Account or wallet not found"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
|
|
Conflict:
|
|
description: Conflict - link already exists
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "CONFLICT"
|
|
message: "Account and wallet are already linked"
|
|
timestamp: "2024-01-01T00:00:00Z"
|
|
|
|
InternalServerError:
|
|
description: Internal server error
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
example:
|
|
success: false
|
|
error:
|
|
code: "INTERNAL_ERROR"
|
|
message: "An internal error occurred"
|
|
timestamp: "2024-01-01T00:00:00Z"
|