Protocol documentation

USD AW is a six-decimal, whitelist-restricted ERC-20 on Base. Issuance is bounded by an administrator-reported backing cap; redemption runs through an escrow that holds the user's tokens until a settler proves an off-chain payout. Every privileged action is either held by a multisig or delayed by 48 hours.

Symbol

USDAW

Decimals

6 — decimals() is pure and cannot be changed by an upgrade without changing the implementation. 1 USD AW = 1_000_000 units.

Network

Base (chain id 8453). Redemption payouts settle on any EVM network the administrator has approved.

Standard

ERC-20 plus ERC-2612 permit, via OpenZeppelin ERC20PermitUpgradeable 5.4.0.

Proxies

All five contracts are UUPS (ERC-1967). Implementations are upgradeable only by the ADMIN Safe.

The token holds balances and nothing else: it accepts mint only from the mint controller and burn/refund only from the redemption escrow, and it asks the whitelist registry about every counterparty. Policy lives in the controllers, so limits and caps can move without touching balances.

Every contract inherits SystemAccessUpgradeable, which grants DEFAULT_ADMIN_ROLE and ADMIN_ROLE to the Safe and EMERGENCY_ROLE to the emergency key in __SystemAccess_init(admin, emergency). Because DEFAULT_ADMIN_ROLE is the admin of every other role, the Safe is the only address that can grant or revoke anything.

MINTER_ROLE and REDEMPTION_ROLE are contract-to-contract capabilities, not human keys. Neither can be exercised directly: the token's only issuance path runs through the mint controller's checks, and its only burn path through the escrow's lifecycle.

Administrative authority is a Safe (Gnosis Safe) deployed by the same script that deploys the protocol, through the canonical SafeProxyFactory with a SafeL2 singleton and the standard CompatibilityFallbackHandler. The proxy address is deterministic: CREATE2 over the hash of the initialiser plus a salt nonce, so the same owner set and nonce always produce the same address.

• Threshold. Configured at deployment. Every administrative call is an execTransaction carrying at least that many owner signatures; the Safe reverts the whole transaction if the inner call fails when safeTxGas and gasPrice are zero, so a partially applied administrative action is not possible.
• Owner rotation. Owners are not fixed at deployment. addOwnerWithThreshold, removeOwner and swapOwner are ordinary Safe transactions and need the current threshold of signatures. A compromised or lost owner key is rotated without touching the protocol contracts.
• Separation from the operational keys. The deployment script rejects a configuration where an owner address is also the service or emergency address, and where service equals emergency (InvalidRoleAddress). Governance, day-to-day operations and the emergency stop are three distinct key sets.
• Threshold sanity. The script also rejects a threshold below a majority of owners or above the owner count (InvalidSafeThreshold), so a Safe that a single owner could control by attrition cannot be deployed by accident.

A standard ERC-20 with permit, plus a transfer hook. The whole of the token's non-standard behaviour is in _update, which classifies every balance change into one of four cases.

The escrow case is the reason the escrow cannot be drained by an operator: tokens held by an address with REDEMPTION_ROLE can only leave by being burned, or by being returned to the exact address that deposited them during a refundEscrowed call. The recipient is pinned in transient storage for the duration of that one call.

A single mapping of address to boolean, read by the token on every transfer, by the mint controller before issuance and by the escrow before a request is created or a payout registered. Every mutation emits WhitelistStatusChanged(account, whitelisted, operator), which records the operator, so the indexer can attribute each listing decision.

Holds one number: the administrator-reported backing, expressed as a maximum total supply. The mint controller reads it on every mint and refuses to cross it. Raising or lowering it is always delayed by UPDATE_DELAY = 48 hours — there is no immediate path, in either direction.

The only path to issuance. mint runs five checks in order, and each has its own error, so a rejected mint is always attributable.

1. Caller is the current mintAgent — otherwise UnauthorizedMintAgent. This is a single address, not a role.
2. Contract is not paused, and any matured limit relaxation is applied first via _syncLimits.
3. Recipient is whitelisted — otherwise AccountNotWhitelisted.
4. Amount is within minAmount and maxAmount — otherwise MintAmountBelowMinimum or MintAmountAboveMaximum.
5. Per-recipient and global UTC-day allowances are consumed — DailyLimitExceeded if either is exhausted — and the resulting total supply is compared against syncSupplyCap(), otherwise SupplyCapExceeded.

Daily usage is tracked by DailyUsageLib, which stores a day id (block.timestamp / 1 days) alongside the amount. A new day resets the counter on first use rather than by a scheduled job, so there is nothing to keep running.

Redemption is a two-sided settlement: the user's tokens are locked on Base while a settler pays the user in an approved stablecoin on the destination network. The escrow is the referee. It never holds or moves the payout asset — it holds USD AW and decides, at the end of the lifecycle, whether that balance is burned or returned.

Redemption converts USD AW on Base into a stablecoin on another network. The two legs cannot be atomic — no contract on Base can move funds on another chain — so the protocol splits them: the escrow locks the tokens and records the outcome, while a settler performs the payout and the issuer reconciles the money afterwards.

The rule throughout: changes that reduce the protocol's freedom take effect at once, changes that increase it wait 48 hours. Delays are enforced by the contracts themselves and cannot be skipped by the Safe.

A scheduled change is public the moment it is proposed: SupplyCapUpdateScheduled, MintLimitsUpdateScheduled and RedemptionLimitsUpdateScheduled all carry the new values and the activation timestamp, and the indexer surfaces the pending cap in the protocol snapshot. The 48 hours are notice, not just friction.

Four contracts are pausable: the token, the whitelist registry, the mint controller and the redemption escrow. _checkPauseAuthority accepts either ADMIN_ROLE or EMERGENCY_ROLE; unpause is ADMIN_ROLE only. The emergency key is therefore a one-way switch — it can be held on a hotter, faster-to-reach device than the Safe owners without giving it the power to restart the system or to change anything.

The pattern is consistent: a pause stops new commitments, never the exits. No combination of pauses can strand tokens in escrow.

All five contracts are UUPS proxies. Upgrade authority is a single line in SystemAccessUpgradeable:

• Implementations call _disableInitializers() in their constructor, so an implementation contract cannot be initialised directly and taken over.
• Each contract reserves a storage gap sized to the fixed slot budget — uint256[47] on the token, [49] on the whitelist, [44] on the supply controller, [39] on the mint controller, [37] on the escrow — so new state can be appended without shifting existing slots.
• There is no delay on an upgrade. This is the single largest trust assumption in the system and the reason the Safe's threshold and key custody matter more than any other parameter.

The indexer is a Node service with a Postgres store. It reads logs from the five contract addresses, decodes them, projects them into an activity feed and a redemption table, and periodically snapshots protocol state read directly from the contracts. It is read-only with respect to the chain: it holds no keys and can sign nothing.

Writes are idempotent — inserts are ON CONFLICT DO NOTHING keyed on the log identity — so replaying a range cannot duplicate history. Amounts are stored as text, never as floats, and rendered at six decimals by the client.

Read-only JSON over HTTP. Every response is cacheable, no endpoint mutates state, and no endpoint accepts a signature — the API is a view onto the chain, not a way into it.

Errors are reported by class, never as raw messages — last_error surfaces as a fixed string — so an RPC provider's URL or key cannot leak through the API.