PYUSDX Specification

This page is the lookup reference for PYUSDX. For explanations of the mechanics, see the PYUSDX overview and its linked pages.

• Solidity: 0.8.34
• EVM target: Cancun
• License: BUSL-1.1

Token parameters

Roles

Consolidated across all contracts.

PYUSDX

The earner manager is a single address, not a role.

IssuerGateway

Portal

BridgeAdapter

YieldToOne

MultiMint

MultiMint inherits YieldToOne roles and adds ASSET_CAP_MANAGER_ROLE, which sets asset caps and manages the replaceAsset caller whitelist.

Initialization parameters

PYUSDX

struct InitializeParams {
  string name;
  string symbol;
  address admin;
  address pauser;
  address freezeManager;
  address forcedTransferManager;
  address earnerManager;
  address rateLimitManager;
  address issuer;
}

IssuerGateway

initialize(admin, operator, executor, mintDelay, mintTTL)

Portal

initialize(admin, pauser, operator, fallbackRecipient)

SwapFacility

initialize(admin, pauser)
// Constructor: (pyusdx, extensionFactory)

ExtensionFactory

initialize(admin, factoryManager)
// Constructor: (pyusdx, swapFacility, yieldToOneBeacon, multiMintBeacon)

ExtensionBeacon

initialize(admin, beaconManager, initialImplementation)
// Constructor: (pyusdx, swapFacility)

Rounding

Rounding is conservative for the protocol. When converting between principal and present amount, PYUSDX never credits more principal than the present amount supports, and never debits less than required. For an earner with current index I:

• Inbound (_addEarningAmount): principal += floor(amount × 1e12 / I), round down.
• Outbound (_subtractEarningAmount): principal -= ceil(amount × 1e12 / I), round up.

Non-earner accounts have no earningPrincipal; their balance updates use the exact amount.

PYUSDX methods

PYUSDX transfers

In all four cases the protocol's net principal accounting is conservative: outgoing principal is over-debited; incoming principal is under-credited. There is no balance or solvency impact; only yield is affected. Moving value through an earning balance can reduce an account's unrealized and future yield by a bounded amount: up to 1 unit (1e-6 PYUSDX) per receive, up to 2 per wrap() + unwrap() round trip.

Forced transfer

A forced transfer runs on a frozen account, which is always non-earning at seizure (freeze materializes pending yield first). The sender side is therefore exact-amount; the recipient side is earner-aware.

Extensions (YieldToOne / MultiMint)

Extension tokens are 1:1 wrappers around PYUSDX. The Extension contract itself is a registered earner on PYUSDX, so wrap/unwrap routes PYUSDX into or out of an earner balance via regular _transfer calls.

Wrap and unwrap always move PYUSDX 1:1 — the amount of extension tokens minted or PYUSDX returned equals the amount supplied. The rounding above applies only to the Extension's earning principal (its future PYUSDX yield), never to the transferred amount or the 1:1 backing.

The extension token's own balanceOf mapping uses exact-amount accounting; extension tokens are not themselves yield-bearing.

Portal (cross-chain)

Portal moves PYUSDX between chains via burn-and-mint.

For an earner sender → earner recipient, source-chain principal is debited rounded up while destination-chain principal is credited rounded down. The sub-unit difference is conservative (no over-issuance).

Invariants

1. totalSupply equals the sum of all account balances. Unclaimed yield is not included in totalSupply; yield enters supply only when materialized by claimYield, setAccountInfo, or _beforeFreeze.
2. An earner's earningPrincipal is always ≤ their balance.
3. An earner's lastIndex is monotonically increasing between the _setAccountInfo that enables earning and the _stopEarningFor that disables it. _stopEarningFor clears lastIndex to 0; a subsequent re-enable re-initializes it to EXP_SCALED_ONE (1e12). currentIndexOf returns EXP_SCALED_ONE (1e12) for non-earners.
4. Freezing an account stops its earning and claims all pending yield first.
5. totalSupply can increase during pause only through setAccountInfo / _beforeFreeze yield materialization.
6. No regular transfers can occur while paused.

Additional guarantees: totalSupply == sum(balanceOf) at all times (balances are stored directly and always honored), and accruedYieldOf(account) ≥ 0 (yield is floored at zero).

Cross-chain message format

The token-transfer payload is 180 bytes, encoded with abi.encodePacked:

┌──────────────┬──────────────┬────────────┬───────────┬──────────────┬──────────┬─────────────┐
│ Dest ChainID │  Dest Peer   │ Message ID │  Amount   │  Dest Token  │  Sender  │  Recipient  │
│  (4 bytes)   │  (32 bytes)  │ (32 bytes) │ (16 bytes)│  (32 bytes)  │(32 bytes)│ (32 bytes)  │
└──────────────┴──────────────┴────────────┴───────────┴──────────────┴──────────┴─────────────┘

On the destination chain, Dest ChainID and Dest Peer are read as targetChainId and targetBridgeAdapter and validated against currentChainId() and msg.sender respectively.

Errors

PYUSDX

IssuerGateway

RateLimiter

Portal

MultiMint

Events

External dependencies

Related

• PYUSDX overview: what PYUSDX is and its contracts
• Token & yield: the yield model and transfer mechanics
• PYUSDX platform deployments: deployed contract addresses