README
¶
Microvault
A headless SEP-0056 tokenized vault standard engine for microlending built on the Stellar network.
Vault Contract Address: CDZVKARLUCAYYIV2TPSR6PLWLETPS4TYE2QXVXSQT27QNFYE3GEE5IS5
Governance Contract Address: CAL3RYRW6MJ2BMKP2J7G47BPBFWKZ7K2BMRG2EXZWQI5ZZAHFPM7NO7B
Technical Architecture
A high-level technical architecture of the engine implementation:
Micro-lending Journey
A successful microlending journey:
Proposal
https://drive.google.com/file/d/1vPvQThVGg2bDMLYC4Yd_cYwavyDlSrsj/view?usp=sharing
Documentation
Full developer documentation lives in docs/ — covering the Soroban contracts, the Stellar Go client, and the off-ramp.
Contributing
Contributions are welcome! We are excited to see this project grow with help from the community.
Before we can merge your contribution, you will need to sign our Contributor License Agreement (CLA). When you open a Pull Request, a bot will automatically check if you've signed and will guide you through the quick, one-time process if needed.
Why a CLA? By signing the CLA, you grant us the copyright to your contribution. This is essential for us to be able to manage the dual-licensing of the project, allowing us to offer it to the community under the AGPL while also providing a separate commercial license.
License
This project is licensed under the AGPL-3.0. This means you are free to use, modify, and distribute it, but if you use it in a derivative work, you must also open-source your derivative work under the same license.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd holds the application's entry points.
|
Package cmd holds the application's entry points. |
|
microvault
command
Command microvault is the API server and composition root for the Microvault platform.
|
Command microvault is the API server and composition root for the Microvault platform. |
|
microvault/docs
Package docs Code generated by swaggo/swag.
|
Package docs Code generated by swaggo/swag. |
|
migrate
command
Command migrate is the database migration CLI.
|
Command migrate is the database migration CLI. |
|
mpesa-register
command
Command mpesa-register performs the one-time Daraja registrations.
|
Command mpesa-register performs the one-time Daraja registrations. |
|
vault-backfill
command
Command vault-backfill finds every address that has ever participated in a vault deposit, mint, or transfer, and allowlists whichever of them are not already allowed — the backfill the vault's own allowlist_enforced doc comment calls for before enforcement is turned on.
|
Command vault-backfill finds every address that has ever participated in a vault deposit, mint, or transfer, and allowlists whichever of them are not already allowed — the backfill the vault's own allowlist_enforced doc comment calls for before enforcement is turned on. |
|
internal
|
|
|
core/pkg/routes
Package routes wires the public HTTP route group onto a Fiber app.
|
Package routes wires the public HTTP route group onto a Fiber app. |
|
pkg
|
|
|
account
Package account is the business-logic layer for Stellar accounts.
|
Package account is the business-logic layer for Stellar accounts. |
|
auth
Package auth authenticates the admin by proving control of a Stellar key, then issues a JWT session token.
|
Package auth authenticates the admin by proving control of a Stellar key, then issues a JWT session token. |
|
compliance
Package compliance defines the provider-neutral contract for screening a blockchain address before it is trusted with money — the vault allowlist's upstream decision, not the allowlist itself (see pkg/services/vaultwatch and the vault contract's own allow_depositor/disallow_depositor for the enforcement side).
|
Package compliance defines the provider-neutral contract for screening a blockchain address before it is trusted with money — the vault allowlist's upstream decision, not the allowlist itself (see pkg/services/vaultwatch and the vault contract's own allow_depositor/disallow_depositor for the enforcement side). |
|
compliance/elliptic
Package elliptic implements compliance.Screener against Elliptic's AML API — wallet screening for a Stellar depositor address, the verdict policy that turns a risk score into a decision, and Standard Webhooks verification for rescreening callbacks.
|
Package elliptic implements compliance.Screener against Elliptic's AML API — wallet screening for a Stellar depositor address, the verdict policy that turns a risk score into a decision, and Standard Webhooks verification for rescreening callbacks. |
|
config
Package config is the single source of application configuration.
|
Package config is the single source of application configuration. |
|
contracts
Package contracts holds the interface seams between the platform's modules, together with the data types those interfaces exchange.
|
Package contracts holds the interface seams between the platform's modules, together with the data types those interfaces exchange. |
|
controllers
Package controllers is the HTTP handler layer, built on Fiber.
|
Package controllers is the HTTP handler layer, built on Fiber. |
|
errors
Package errors holds sentinel errors shared across packages that would otherwise have to import one another to match on them.
|
Package errors holds sentinel errors shared across packages that would otherwise have to import one another to match on them. |
|
health
Package health exposes liveness and readiness probes as Fiber handlers, in the shape an orchestrator like Kubernetes expects.
|
Package health exposes liveness and readiness probes as Fiber handlers, in the shape an orchestrator like Kubernetes expects. |
|
jobs
Package jobs is the background-work layer, wrapping the Redis-backed asynq library behind a single Scheduler.
|
Package jobs is the background-work layer, wrapping the Redis-backed asynq library behind a single Scheduler. |
|
loanref
Package loanref generates and validates short loan references.
|
Package loanref generates and validates short loan references. |
|
middleware
Package middleware holds the Fiber middleware that wraps the HTTP layer: authentication, a uniform response envelope, and the standard cross-cutting stack every request passes through.
|
Package middleware holds the Fiber middleware that wraps the HTTP layer: authentication, a uniform response envelope, and the standard cross-cutting stack every request passes through. |
|
mobile
Package mobile is the umbrella for the platform's mobile-channel surface.
|
Package mobile is the umbrella for the platform's mobile-channel surface. |
|
mobile/sms
Package sms sends outbound SMS messages and ingests delivery-report callbacks.
|
Package sms sends outbound SMS messages and ingests delivery-report callbacks. |
|
mobile/ussd
Package ussd is the interactive USSD application: the menu-driven flow a mobile subscriber walks through to register, request a loan, pick a payout method, repay, and manage their PIN.
|
Package ussd is the interactive USSD application: the menu-driven flow a mobile subscriber walks through to register, request a loan, pick a payout method, repay, and manage their PIN. |
|
mobile/ussd/adapters
Package adapters holds the USSD-to-domain glue: each file implements a narrow port interface declared elsewhere against the concrete user, account, off-ramp, and Stellar services.
|
Package adapters holds the USSD-to-domain glue: each file implements a narrow port interface declared elsewhere against the concrete user, account, off-ramp, and Stellar services. |
|
mobile/ussd/providers/africastalking
Package africastalking implements the USSD provider adapter for AfricasTalking.
|
Package africastalking implements the USSD provider adapter for AfricasTalking. |
|
models
Package models holds the GORM persistence models — the database schema expressed as Go structs.
|
Package models holds the GORM persistence models — the database schema expressed as Go structs. |
|
notifications
Package notifications delivers user-facing messages — loan lifecycle and account/PIN events — and is the concrete implementation of the notifier ports declared in the contracts package.
|
Package notifications delivers user-facing messages — loan lifecycle and account/PIN events — and is the concrete implementation of the notifier ports declared in the contracts package. |
|
payment
Package payment is the umbrella for the platform's off-ramp surface.
|
Package payment is the umbrella for the platform's off-ramp surface. |
|
payment/airtel
Package airtel is a client for Airtel Africa's Open API, Kenya op-co.
|
Package airtel is a client for Airtel Africa's Open API, Kenya op-co. |
|
payment/airtel/airtelstub
Package airtelstub is an in-process Airtel Open API, Kenya op-co.
|
Package airtelstub is an in-process Airtel Open API, Kenya op-co. |
|
payment/cashin
Package cashin is the collection-side counterpart to offramp.
|
Package cashin is the collection-side counterpart to offramp. |
|
payment/fonbnk
Package fonbnk is the client for Fonbnk's server-to-server Merchant API, covering both on-ramp (fiat in, crypto out) and off-ramp (crypto in, fiat out).
|
Package fonbnk is the client for Fonbnk's server-to-server Merchant API, covering both on-ramp (fiat in, crypto out) and off-ramp (crypto in, fiat out). |
|
payment/moneygram
Package moneygram is the MoneyGram-flavoured wrapper around the generic stellaranchor SDK.
|
Package moneygram is the MoneyGram-flavoured wrapper around the generic stellaranchor SDK. |
|
payment/mpesa
Package mpesa is a client for Safaricom's Daraja API gateway.
|
Package mpesa is a client for Safaricom's Daraja API gateway. |
|
payment/mpesa/darajastub
Package darajastub is an in-process Daraja.
|
Package darajastub is an in-process Daraja. |
|
payment/offramp
Package offramp defines the off-ramp Provider contract that every provider in the platform satisfies.
|
Package offramp defines the off-ramp Provider contract that every provider in the platform satisfies. |
|
payment/relay
Package relay routes one transaction to whichever ramp provider offers the best price for it.
|
Package relay routes one transaction to whichever ramp provider offers the best price for it. |
|
payment/stellaranchor
Package stellaranchor provides the reusable Stellar-anchor primitives that any SEP-24-compliant anchor implementation can compose on top of.
|
Package stellaranchor provides the reusable Stellar-anchor primitives that any SEP-24-compliant anchor implementation can compose on top of. |
|
payment/yellowcard
Package yellowcard is the low-level HTTP client for the YellowCard mobile-money API, in both directions.
|
Package yellowcard is the low-level HTTP client for the YellowCard mobile-money API, in both directions. |
|
phone
Package phone holds the platform's shared phone-number helpers: redaction for logs, and three normalisers with deliberately different contracts.
|
Package phone holds the platform's shared phone-number helpers: redaction for logs, and three normalisers with deliberately different contracts. |
|
pin
Package pin manages user PINs for USSD-based authentication: setting and verifying them, enforcing strength and lockout, changing and resetting them, and the security-question recovery flow.
|
Package pin manages user PINs for USSD-based authentication: setting and verifying them, enforcing strength and lockout, changing and resetting them, and the security-question recovery flow. |
|
repository
Package repository is the data-access layer.
|
Package repository is the data-access layer. |
|
services
Package services holds the primitives shared by the business-logic service layer.
|
Package services holds the primitives shared by the business-logic service layer. |
|
services/airtelpoller
Package airtelpoller holds the core-side Airtel Money tickers.
|
Package airtelpoller holds the core-side Airtel Money tickers. |
|
services/compliance
Package compliance orchestrates the KYB lifecycle described in elliptic-compliance-integration.md §13: a counterparty submits an address, KYB approval triggers screening via pkg/compliance.Screener, and the verdict is applied to pkg/repository.CounterpartyRepository's three tables.
|
Package compliance orchestrates the KYB lifecycle described in elliptic-compliance-integration.md §13: a counterparty submits an address, KYB approval triggers screening via pkg/compliance.Screener, and the verdict is applied to pkg/repository.CounterpartyRepository's three tables. |
|
services/mgpoller
Package mgpoller drives both directions of the MoneyGram SEP-24 rail: withdrawal (cash out at an agent) and deposit (cash in, settling a loan).
|
Package mgpoller drives both directions of the MoneyGram SEP-24 rail: withdrawal (cash out at an agent) and deposit (cash in, settling a loan). |
|
services/mpesapoller
Package mpesapoller holds the core-side M-Pesa tickers.
|
Package mpesapoller holds the core-side M-Pesa tickers. |
|
services/vaultwatch
Package vaultwatch is the on-chain allowlist's detect-and-quarantine watcher (Option D of the compliance design, defense-in-depth alongside the contract's own gating).
|
Package vaultwatch is the on-chain allowlist's detect-and-quarantine watcher (Option D of the compliance design, defense-in-depth alongside the contract's own gating). |
|
stellar
Package stellar is the single entry point for everything the platform does on the Stellar network — both classic operations (accounts, trustlines, payments) and Vault smart-contract calls.
|
Package stellar is the single entry point for everything the platform does on the Stellar network — both classic operations (accounts, trustlines, payments) and Vault smart-contract calls. |
|
stellar/classic
Package classic holds the platform's non-Soroban Stellar operations: creating accounts, establishing trustlines, and moving USDC.
|
Package classic holds the platform's non-Soroban Stellar operations: creating accounts, establishing trustlines, and moving USDC. |
|
stellar/rpc
Package rpc waits for a submitted Stellar transaction to be applied to the ledger.
|
Package rpc waits for a submitted Stellar transaction to be applied to the ledger. |
|
stellar/soroban
Package soroban is the Go client for the Vault smart contract.
|
Package soroban is the Go client for the Vault smart contract. |
|
stellar/testing
Package testing provides the shared test doubles for the stellar packages.
|
Package testing provides the shared test doubles for the stellar packages. |
|
stellar/types
Package types holds the request and response DTOs shared across the stellar packages, plus the error values they return.
|
Package types holds the request and response DTOs shared across the stellar packages, plus the error values they return. |
|
transaction
Package transaction is the business-logic layer for the platform's transaction ledger — the durable record of every money movement, whether it settled on the Stellar network, through an external provider, or internally.
|
Package transaction is the business-logic layer for the platform's transaction ledger — the durable record of every money movement, whether it settled on the Stellar network, through an external provider, or internally. |
|
urlshortener
Package urlshortener turns long outbound links — MoneyGram cash-pickup interactive and support URLs — into short, tappable links that fit inside an SMS segment.
|
Package urlshortener turns long outbound links — MoneyGram cash-pickup interactive and support URLs — into short, tappable links that fit inside an SMS segment. |
|
user
Package user is the business-logic layer for registered users — the people the platform serves and the staff who administer it.
|
Package user is the business-logic layer for registered users — the people the platform serves and the staff who administer it. |
|
utils
Package utils holds small, standalone helpers shared across the platform.
|
Package utils holds small, standalone helpers shared across the platform. |
|
validation
Package validation turns struct-tag validation into user-friendly field errors.
|
Package validation turns struct-tag validation into user-friendly field errors. |
|
webhook
Package webhook reacts to off-ramp settlement outcomes.
|
Package webhook reacts to off-ramp settlement outcomes. |
|
Package platform holds the process-level infrastructure the application runs on top of.
|
Package platform holds the process-level infrastructure the application runs on top of. |
|
cache
Package cache manages Redis connection lifecycle and provides a Redis-backed idempotency store for safe request replay.
|
Package cache manages Redis connection lifecycle and provides a Redis-backed idempotency store for safe request replay. |
|
database
Package database manages PostgreSQL connection lifecycle and runs schema migrations.
|
Package database manages PostgreSQL connection lifecycle and runs schema migrations. |
Click to show internal directories.
Click to hide internal directories.