Economy & Billing Engine

Relevant source files

The following files were used as context for generating this wiki page:

• src/stores/economy.ts
• supabase/functions/stripe-checkout/index.ts
• supabase/functions/stripe-webhook/index.ts
• supabase/migrations/20260512080845_110fe96e-4027-403f-98c8-f6d495c1bf4c.sql
• scripts/001_rdm_schema.sql
• src/lib/types.ts

The Economy & Billing Engine is a multi-layered system designed to manage financial transactions, multi-currency balances, and institutional fund distribution within the RDM Digital ecosystem. It facilitates traditional payments via Stripe integration while maintaining a sovereign economic layer through specialized credits and reputation metrics.

This engine serves as the financial backbone for the Federación Económica, supporting local commerce, digital tributes, and redistributive mechanisms. It ensures that every transaction is auditable and adheres to specific distribution rules, such as the "20/30/50 Phoenix Rule" for profit allocation.
Sources: README.md:32-34, src/stores/economy.ts:1-5, supabase/migrations/20260512080845_110fe96e-4027-403f-98c8-f6d495c1bf4c.sql:26-28

1. Multi-Currency & Balance Management

The system operates using three distinct types of balances and a reputation-based metric. These are managed via the EconomyState and persisted in the database schema.

Currency Types

Currency/Metric	Description	Source
TC Balance	Traditional Currency / Base credits.	src/stores/economy.ts:44
MSR Balance	Multi-State Record credits, likely linked to the ledger.	src/stores/economy.ts:45
TAMV Balance	Sovereign credits specific to the TAMV network.	src/stores/economy.ts:46
MXN Cents	Real-world currency (Mexican Pesos) used for Stripe transactions.	scripts/001_rdm_schema.sql:128
Reputation	A numeric value (default 100) tracking user reliability.	scripts/001_rdm_schema.sql:130

The 20/30/50 Phoenix Rule

The engine implements a specific logic for distributing profit into three institutional funds. This ensures long-term sustainability and infrastructure maintenance.
Sources: src/stores/economy.ts:68-76

2. Transaction Architecture

Transactions are designed to be auditable and support multiple types, ranging from simple credits/debits to institutional donations and staking.

Transaction Logic and Types

Transactions are defined by the Transaction interface and stored in the transactions table.

• Transaction Types: credit, debit, stake, reward, donation, purchase, tribute, tax, redistribution.
• Security: Every transaction includes a msrHash or "forensic hash" for auditability.
  Sources: src/stores/economy.ts:7-15, scripts/001_rdm_schema.sql:149-152

Transaction Data Model

Field	Type	Description
id	uuid	Primary key, automatically generated.
amount_cents	integer	Amount in cents to avoid floating point issues.
status	text	pending, paid, failed, or refunded.
hash	text	Forensic hash for immutable auditing.
type	text	Categorization of the transaction.
Sources: scripts/001_rdm_schema.sql:140-156

3. Stripe Integration & Billing

The billing system utilizes Supabase Edge Functions to bridge the sovereign economy with global payment rails via Stripe.

Checkout Flow

The stripe-checkout function initializes sessions for user payments. It requires a STRIPE_SECRET_KEY and specific price_ids configured in Supabase secrets.
Sources: supabase/functions/stripe-checkout/index.ts:50-52

Billing Schema Extensions

For merchants and businesses, the system tracks subscription statuses and monthly fees.

• monthly_fee_cents: Default fee set at 20,000 (e.g., $200.00).
• payment_status: Tracks if a merchant is active or inactive.
• next_payment_due: Timestamp for the next billing cycle.
  Sources: supabase/migrations/20260512080845_110fe96e-4027-403f-98c8-f6d495c1bf4c.sql:128-132

4. Wallet & Merchant Integration

The economy engine integrates directly with user profiles and merchant accounts to facilitate a circular economy.

Wallet Initialization

A trigger handle_new_user automatically creates a wallet for every new profile registered in the system.
Sources: scripts/001_rdm_schema.sql:244-246

Merchant Economy

Merchants within the Federación Económica are managed through the merchants table.

• Stripe Account Link: Merchants can have a stripe_account_id for payouts.
• Verification: A verified boolean flag determines if the business is officially recognized.
  Sources: scripts/001_rdm_schema.sql:85-103

5. Security & Auditing

The system places a heavy emphasis on "Sovereign Auditing" through an immutable log.

• Audit Log: The audit_log table records every action, including the actor_id, entity_type, and a JSON payload of the changes.
• Restricted Access: The log is only readable by users with arquitecto or gobierno roles.
• Forensic Signatures: Significant financial events are signed and stored in the audit_signatures table using SHA256 hashes.
  Sources: scripts/001_rdm_schema.sql:216-232, supabase/migrations/20260512080845_110fe96e-4027-403f-98c8-f6d495c1bf4c.sql:67-75

Summary

The Economy & Billing Engine is more than a payment processor; it is a governed financial system. By combining traditional Stripe payments with sovereign credit balances and institutional fund distribution, it enables a self-sustaining digital territory. Its architecture ensures that financial growth directly contributes to infrastructure and reserves through automated distribution rules.