Documentation
¶
Overview ¶
Package formance is the Formance Ledger adapter for the treasury: it satisfies ledger.Backend by posting the reserve fund's double-entry through a live Formance Ledger service (Postgres-backed, the production ledger of record) over its v2 HTTP API. Formance guarantees the double-entry + the overdraw guard — a transaction whose source (@fund:reserve) is underfunded is refused by Numscript source semantics (400 INSUFFICIENT_FUND), which this adapter maps to "not backed". We do NOT reimplement double-entry here; we drive Formance's.
Integration shape (b) of the finance-stack plan: Formance Ledger runs as its own all-Go service against the prod Postgres (hanzo-sql); the unified cloud binary CLIENTS to it. Selecting it is one env var (FORMANCE_LEDGER_URL); absent it the treasury uses the native engine, so the reserve fund works offline and Formance is a drop-in upgrade to the ledger of record.
FORMANCE_LEDGER_URL base URL of the Formance Ledger service (e.g.
http://ledger.finance.svc:8080)
FORMANCE_LEDGER_NAME the ledger name to post into (default "hanzo-treasury")
FORMANCE_LEDGER_TOKEN optional bearer token (client-credentials) for auth
The Hanzo revenue-share POLICY is not a Formance concept (it is Hanzo config, not accounting), so it is held in the injected ledger.PolicyStore (the native Base store) regardless of which backend owns the journal.
Index ¶
- type Backend
- func (b *Backend) AccountsWithPrefix(ctx context.Context, prefix string) (map[string]int64, error)
- func (b *Backend) Accrue(ctx context.Context, period string, revenueCents, now int64) (ledger.JournalEntry, bool, error)
- func (b *Backend) Balance(ctx context.Context, account string) (int64, error)
- func (b *Backend) DebitReserve(ctx context.Context, program, ref, memo string, amountCents, now int64) (ledger.JournalEntry, bool, bool, error)
- func (b *Backend) Entries(ctx context.Context, limit int) ([]ledger.JournalEntry, error)
- func (b *Backend) Name() string
- func (b *Backend) Policy(ctx context.Context) (ledger.SharePolicy, error)
- func (b *Backend) ReserveCents(ctx context.Context) (int64, error)
- func (b *Backend) Root(ctx context.Context) ([32]byte, int, error)
- func (b *Backend) Seed(ctx context.Context, ref, memo string, amountCents, now int64) (ledger.JournalEntry, bool, error)
- func (b *Backend) SetPolicy(ctx context.Context, bps, now int64) (ledger.SharePolicy, error)
- func (b *Backend) Snapshot(ctx context.Context) (ledger.TreasuryReport, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend drives a Formance Ledger service. It satisfies ledger.Backend.
func New ¶
func New(base, ledgerName, token string, policy ledger.PolicyStore) *Backend
New builds the adapter. base/ledgerName must be non-empty (the caller selects this backend only when FORMANCE_LEDGER_URL is set); policy is the native config store for the revenue-share policy.
func (*Backend) AccountsWithPrefix ¶
AccountsWithPrefix lists accounts and returns account→USD balance for those under prefix — the scope-aware read (a per-org caller's "org:<tenant>:" accounts, or the house prefixes for SuperAdmin). Best-effort: an unreachable Formance degrades to an empty map (honest empty, never a fabricated balance).
func (*Backend) Accrue ¶
func (b *Backend) Accrue(ctx context.Context, period string, revenueCents, now int64) (ledger.JournalEntry, bool, error)
Accrue posts the revenue-share for a period (world → fund:reserve), idempotent by the Formance transaction reference "accrual:<period>". A zero share is a no-op.
func (*Backend) Balance ¶
Balance reads an account's USD balance via the aggregate-balances endpoint (an exact address returns just that account's balance). A missing account is 0.
func (*Backend) DebitReserve ¶
func (b *Backend) DebitReserve(ctx context.Context, program, ref, memo string, amountCents, now int64) (ledger.JournalEntry, bool, bool, error)
DebitReserve posts a backed payout (fund:reserve → payout:<program>). Formance refuses it (400 INSUFFICIENT_FUND) when the reserve is underfunded — mapped to backed=false, nothing posted. A duplicate reference (409) is an idempotent replay → backed=true, created=false. This is the reserve overdraw guard, enforced by Formance's Numscript source semantics — not reimplemented here.
func (*Backend) Entries ¶
Entries lists recent Formance transactions and maps them to ledger.JournalEntry for the admin journal view + the anchor root.
func (*Backend) ReserveCents ¶
ReserveCents is the reserve fund's available balance.
func (*Backend) Root ¶
Root fetches the whole journal + reserve and commits it with the SHARED root hash, so the on-chain anchor is computed the one way regardless of backend.
func (*Backend) Seed ¶
func (b *Backend) Seed(ctx context.Context, ref, memo string, amountCents, now int64) (ledger.JournalEntry, bool, error)
Seed posts a bootstrap capital injection (world → fund:reserve), idempotent by ref.
Source Files