atlas-bank

Summary

atlas-bank is the domain crate for institution-oriented financial rules that sit on top of the shared ledger primitives. It packages institution registration, institution-level issuance permissions, account opening rules, a simple accounting engine for transfer and issuance entry generation, and a lightweight compliance rule framework.

Compared with atlas-common, this crate is more business-specific. It does not define canonical transaction types or the ledger state machine itself. Instead, it translates business actions into atlas-common ledger primitives and policy checks.

Why This Crate Exists

• keep institution and banking rules out of the low-level shared types crate
• provide a business-domain layer between application APIs and ledger execution
• generate balanced ledger entries for transfers and issuance using shared accounting primitives
• centralize institution authorization and account-opening checks

Current Role In The Workspace

atlas-bank currently owns five related concerns:

1. institution registry and authorization
2. institution issuance permissions
3. account opening services and account registry
4. accounting entry generation for transfer and issuance flows
5. pluggable compliance rules over shared transactions

This crate is already wired into ledger execution and admin APIs. The observed runtime path is not theoretical.

Public Surface

Top-Level Modules

• compliance_engine
• institution_core
• institution_permissions
• institution_subledger
• services

Public Reexports

• InstitutionRegistry
• AccountingEngine
• AccountRegistry
• AccountService
• IssuanceService

Important Internal Types

• TransactionNature
• PermissionManager
• ComplianceService
• ComplianceRule
• KycRule
• Account
• AccountType

Key Modules

• `lib.rs`: public export surface
• `institution_core/registry.rs`: in-memory institution registry keyed by UUID
• `institution_core/institution.rs`: reexports the canonical institution type from atlas-common
• `institution_permissions/mod.rs`: issuance permission and collateral check gate
• `institution_subledger/accounts.rs`: account path model and account-type inference
• `institution_subledger/engine.rs`: creates transfer ledger entries via atlas_common::accounting::DoubleEntryBuilder
• `services/account.rs`: account registry plus account-opening rules
• `services/issuance.rs`: issuance flow that builds a ledger entry after institution permission checks
• `compliance_engine/service.rs`: pluggable compliance service over shared transactions
• `compliance_engine/kyc.rs`: current minimal KYC/AML rule implementation

Inputs And Outputs

Inputs

• institution registration data
• bank account registration requests
• transaction data from atlas-common
• institution IDs, asset symbols, wallet addresses, and issuance amounts

Outputs

• accepted or rejected institution registrations
• accepted or rejected bank account openings
• balanced LedgerEntry values for transfers and issuance
• compliance approval or rejection results

Internal Dependencies

Workspace Dependencies

• atlas-common
• atlas-kyc

In practice, the business logic here is heavily built on top of atlas-common. The atlas-kyc dependency is present in Cargo.toml, but the current source usage appears negligible or absent.

External Dependencies That Shape The Design

• uuid for institution identity
• serde and serde_json for serializable registries and state
• tracing for warnings around invalid account path prefixes

Used By

These packages depend directly on atlas-bank today:

• atlas-ledger
• atlas-node-admin
• atlas-node

Observed usage in the codebase includes:

• `executor/logic.rs`: ledger execution uses AccountingEngine::process_transfer to generate base transfer entries
• `state/mod.rs`: ledger state embeds atlas_bank::InstitutionRegistry
• `handlers/accounts.rs`: admin account creation goes through AccountService
• `main.rs`: node runtime initializes an AccountRegistry

Testing

atlas-bank has both module-local tests and a crate integration test:

• registry tests for duplicate handling and authorization checks
• account service tests for institution existence and owner validation
• issuance tests for permissions and balanced ledger generation
• compliance tests for rule registration and failure wrapping
• `bank_domain_integration.rs`: cross-module test that registers an institution, opens accounts, generates a transfer entry, and checks double-entry balance

That test coverage is useful because this crate is mostly orchestration over smaller policy pieces.

Risks Or Design Tension

Heavy Reuse Of atlas-common

This crate depends on atlas-common for:

• institution shape
• bank account shape
• transaction shape
• ledger entry primitives
• error types
• accounting builder

That is efficient, but it also means atlas-bank is less of a standalone domain model than the folder name might suggest.

Some Services Are Still Thin

The current KYC rule only checks whether sender and receiver addresses are empty. The issuance permission manager also leaves collateral checking as a TODO. So the compliance and permission boundaries exist, but some policy logic is still intentionally shallow.

Direct Construction Of Ledger Entries

AccountingEngine and IssuanceService create LedgerEntry values with placeholder metadata such as pending hashes or caller-filled context. That works, but it means these services stop short of being fully authoritative.

Unclear atlas-kyc Dependency

atlas-bank declares atlas-kyc in Cargo.toml, but the current source does not appear to use that crate directly. That is a good candidate for cleanup or future clarification.

Open Questions

• should Institution remain reexported from atlas-common, or eventually become owned here
• should atlas-bank define richer institution and compliance policies instead of delegating most shapes to atlas-common
• should entry generation keep using placeholder metadata, or should this crate accept a richer execution context
• should the unused atlas-kyc dependency be removed until there is real coupling

Relevant Files

• `Cargo.toml`
• `lib.rs`
• `institution_core/registry.rs`
• `institution_core/institution.rs`
• `institution_permissions/mod.rs`
• `institution_subledger/accounts.rs`
• `institution_subledger/engine.rs`
• `services/account.rs`
• `services/issuance.rs`
• `compliance_engine/service.rs`
• `compliance_engine/kyc.rs`
• `bank_domain_integration.rs`
• `executor/logic.rs`
• `state/mod.rs`
• `handlers/accounts.rs`