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. |
|
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. |
|
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. |
|
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/fonbnk
Package fonbnk is a placeholder for the Fonbnk on-ramp client.
|
Package fonbnk is a placeholder for the Fonbnk on-ramp client. |
|
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/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/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 off-ramp API.
|
Package yellowcard is the low-level HTTP client for the YellowCard mobile-money off-ramp API. |
|
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/mgpoller
Package mgpoller polls MoneyGram for SEP-24 transaction status changes and drives the existing disbursement state machine accordingly.
|
Package mgpoller polls MoneyGram for SEP-24 transaction status changes and drives the existing disbursement state machine accordingly. |
|
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.