MGUSD on Stellar

MGUSD is an M0-powered Stellar Asset Contract (SAC) stablecoin. It is minted and burned via a Soroban smart contract (the "Minter Gateway"). The SAC holds balances and handles standard SEP-41 transfers; the minter gateway is the sole authority for supply changes, yield accrual, and compliance controls.

This document is for developers and integrators who want to understand how MGUSD is minted, distributed, redeemed, and how yield accrues. It assumes familiarity with Stellar's account model, trustlines, and the Stellar Asset Contract.

Architecture & Core Components

MGUSD is a two-layer system:

The Minter Gateway never exposes a transfer() of its own — holders move tokens using the SAC's standard SEP-41 interface directly. The gateway's job is to be the single, authoritative gateway for everything that changes the supply or compliance state.

Actors

Lifecycle Flows

1. Minting (Bridge → Treasury)

1. MoneyGram receives fiat from an end user and notifies the Bridge.
2. Bridge calls mint(caller, treasury_address, amount) on the Minter Gateway.
3. The gateway finalizes pending yield, increases total_principal and total_supply, then mints SAC tokens to the treasury address.
4. The treasury now holds MGUSD stablecoin.

2. User Distribution (Treasury → End User)

1. An unblock operator whitelists accounts — individually via unblock_user, or in batch via batch_unblock_users (up to 40 per call).
2. The treasury transfers tokens to the user via the SAC's standard SEP-41 transfer().
3. Whitelisted (unblocked) accounts can freely transfer among themselves.
4. Non-whitelisted (blocked) accounts cannot send or receive tokens.

3. Redemption (End User → MoneyGram → Bridge)

1. The end user initiates redemption through MoneyGram.
2. Bridge calls burn(caller, user_address, amount) — removing tokens at the SAC layer via clawback.
3. The Minter Gateway finalizes pending yield and decreases both accumulators.
4. MoneyGram sends fiat to the end user off-chain.

4. Yield Claiming

1. Bridge calls set_interest_rate(caller, rate_bps) to set the current interest rate (this is a Minter permission, not Admin).
2. Yield accrues continuously on total_principal using the exponential index.
3. The Yield Recipient Manager (Bridge) calls claim_yield(caller) to mint accrued yield as new SAC tokens to the Yield Recipient (MoneyGram).
4. Claimed yield increases total_supply but not total_principal — it does not compound.

5. Forced Transfer (Compliance Action)

1. The Forced Transfer Manager identifies a need to move tokens between accounts.
2. It invokes force_transfer(caller, from, to, amount) — no authorization from the source account is required.
3. The Minter Gateway claws back tokens from the source and mints them to the destination at the SAC layer.
4. Accumulators are unchanged — this is a balance redistribution, not a supply change.
5. Works even if the source account is blocked.

Roles

Every role-gated function calls require_auth() on its caller argument and verifies the caller equals the designated role holder — no implicit trust and no admin override. All roles are single-address except Block operator, Unblock operator, and Pauser, each of which is a membership set that Admin grants and revokes.

Contract Interface

Each role can only call its own functions. Admin is not a super-role and cannot call non-admin functions without first granting itself the relevant role.

Admin-exclusive functions

Minter functions

Forced Transfer Manager functions

Yield Recipient Manager functions

Block / unblock (allowlist) functions

block_user / batch_block_users require a block operator; unblock_user / batch_unblock_users require an unblock operator. Backed by the SAC allowlist.

Pauser functions

View functions

admin, minter, yield_recipient_manager, yield_recipient, forced_transfer_manager, is_block_operator, is_unblock_operator, is_pauser, sac_token, interest_rate, current_index, latest_index, accrued_yield, total_principal, total_supply, blocked(account), balance(id), and paused.

Initialization

The contract is initialized via __constructor during deployment. It takes the SAC address plus eight role addresses (admin, minter, yield recipient manager, yield recipient, forced transfer manager, and one seed address each for the block operator, unblock operator, and pauser membership sets). The same address may be reused across arguments when one key should hold multiple permissions. The yield index starts at 1.0 (INDEX_SCALE) on first use.

Yield Mechanics

Continuous index model

Yield accrues continuously using an exponential index:

currentIndex = latestIndex × e^(rate × elapsed / SECONDS_PER_YEAR)

Where latestIndex is the last stored index (initialized to 1.0, scaled as 1e12), rate is the annual rate converted from basis points, elapsed is seconds since the last update, and SECONDS_PER_YEAR is 31,536,000. The e^x term uses a 4th-order Taylor series, accurate for all realistic rates.

Two accumulators

Only total_principal earns yield. The accrued amount is total_principal × (newIndex − oldIndex) / INDEX_SCALE, accumulated in accrued_yield on every index update.

Non-compounding

When claim_yield() is called, pending yield is finalized, accrued_yield is captured and reset to zero, total_supply increases by the claimed amount, and new SAC tokens are minted to the yield recipient. total_principal is unchanged — claimed yield does not earn more yield.

Transfers & the Issuer Burn Problem

Holders move MGUSD using the SAC's standard SEP-41 transfer() — both sender and receiver must be authorized (unblocked) for a transfer to succeed. Transfers happen entirely at the SAC layer and do not change total_principal or total_supply; they are balance redistributions, not mints or burns.

On classic Stellar, sending tokens to the issuer address burns them automatically. If MGUSD is sent to the issuer, tokens are destroyed at the SAC layer but the Minter Gateway's accumulators are never updated — so yield would keep accruing on phantom principal.

Mitigation: AUTH_REQUIRED + whitelist

The SAC is configured with AUTH_REQUIRED, so all accounts start unauthorized (blocked) by default. Accounts can only transact after an unblock operator calls unblock_user(), which limits who can move tokens at all.

Compliance & Safety

Block / unblock

The SAC operates in AUTH_REQUIRED mode — accounts are blocked by default. unblock_user maps to SAC set_authorized(true) and block_user to set_authorized(false). Only a block operator can block, and only an unblock operator can unblock. Batch operations (batch_block_users / batch_unblock_users) accept up to 40 users per call, are atomic (any failure reverts the whole transaction), and emit one event per user for indexer compatibility.

Pausable

The Minter Gateway implements a pause mechanism. When paused, the following revert immediately:

Compliance operations (block_user, unblock_user, their batch variants, and force_transfer) and all view functions remain fully accessible while paused, so regulatory actions can still be executed. reconcile_burn is also intentionally callable while paused — issuer-burn destruction happens outside Minter Gateway control and continues during a pause, so reconciliation must remain available to prevent unbounded accumulator divergence.

Events

Event names are the snake_case form of the underlying contract event struct. Topic fields are marked (topic); the rest are payload data.

Onchain Addresses

The MGUSD Minter Gateway and SAC addresses for Stellar Mainnet and Testnet can be found on the MGUSD Deployments page.

Source Code & Audits

• Minter Gateway contract & deployment tooling: m0-platform/mgusd-minter-gateway
• Audits: Security audit reports can be found on the Audits resource page.

Next Steps

• Integrate MGUSD: Use the SAC's standard SEP-41 interface to hold and transfer MGUSD once your account is whitelisted.
• Look up addresses: Find the Minter Gateway and SAC contract addresses on the MGUSD Deployments page.