> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mrdn.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Contracts

> x402 payment protocol and Meridian facilitator architecture

## Overview

Meridian extends x402 with a **proxy facilitator architecture**. Standard x402 transfers funds directly from payer to recipient; Meridian routes settlement through a facilitator contract instead:

```
Standard x402:  Payer signs authorization → Direct transfer to recipient wallet
Meridian:       Payer signs authorization → Facilitator receives funds → Facilitator settles recipient and fees
```

This one change is what enables fee handling, batch settlement, cross-chain routing, cashback, and organization-scoped payment management on top of the plain x402 flow.

On chains with native EIP-3009 support, Meridian settles standard x402 exact payloads through the facilitator; on chains without an EIP-3009-compatible token (MegaETH, BSC, BOT chain), Meridian settles via Permit2 through `x402ExactPermit2Proxy`. The `upto` scheme (usage-based pricing) settles via Permit2 through `x402UptoPermit2Proxy` on every supported chain. See [Payment Types](/api-reference/payment-types/overview) for how the facilitator routes each payload type.

## X402ProxyFacilitator.sol (V6)

```solidity theme={"system"}
0x8E7769D440b3460b92159Dd9C6D17302b036e2d6
```

The facilitator is a UUPS-upgradeable contract, currently at version 6.

* **Payment Methods**: EIP-3009 `transferWithAuthorization` (USDC), ERC-2612 `transferWithPermit`, and Permit2 `transferWithPermit2` / `transferWithPermit2Upto`
* **Instant Settlement**: Same-chain payments are settled to the recipient during payment execution
* **Batch Settlement**: One signed authorization can settle multiple payments in a single transaction (`batchTransferWithAuthorization` / `batchTransferWithPermit2`), each item with its own recipient, platform, and fee
* **Fee Handling**: Platform and treasury fees accrue inside the facilitator and are withdrawn via `withdrawPlatformFees` / `withdrawTreasuryFees`
* **MRDN Cashback**: On Base, USDC payments earn MRDN cashback priced via Aerodrome TWAP — the rate starts at 2% and decays as total cashback is distributed, capped at \$5 per transaction
* **Cross-Chain Support**: The same entrypoint initiates cross-chain settlement through Across on supported networks, authenticated by a backend-signed EIP-712 message

## x402ExactPermit2Proxy.sol (Non-EIP-3009 Chains)

Integrations on chains without EIP-3009-compatible tokens (MegaETH, BSC, BOT chain) use Permit2 settlement through the Meridian facilitator:

```solidity theme={"system"}
Facilitator:           0x8E7769D440b3460b92159Dd9C6D17302b036e2d6
x402ExactPermit2Proxy: 0x402085c248EeA27D92E8b30b2C58ed07f9E20001
x402UptoPermit2Proxy:  0x402015c795ecb48A360bDC6e35a2EaEb313a0002
Permit2:               0x000000000022D473030F116dDEE9F6B43aC78BA3
```

* **Flow**: Users approve Permit2 once, then sign a Permit2 witness authorization off-chain for each payment
* **Token model**: `paymentRequirements.asset` is the ERC-20 token address being paid
* **Facilitator binding**: `payTo` and `witness.to` stay bound to the Meridian facilitator
* **Settlement**: Meridian settles through `transferWithPermit2`, not through the buyer submitting a transaction

### x402UptoPermit2Proxy (upto scheme)

The `upto` scheme uses the same Permit2 flow with `x402UptoPermit2Proxy` as the signed spender (same address on every chain). The buyer authorizes a maximum amount; Meridian settles the actual usage amount through `transferWithPermit2Upto`. Differences from the exact proxy:

* **Witness shape**: `{ to, facilitator, validAfter }` — the extra `facilitator` field binds which contract may choose the settled amount; both `to` and `facilitator` stay bound to the Meridian facilitator
* **Settled amount**: `0 < settleAmount ≤ permit.permitted.amount`, passed by the seller at settle time (`paymentRequirements.extra.settleAmount`); fees and cashback apply to the settled amount only

```mermaid theme={"system"}
sequenceDiagram
    participant User
    participant Token as ERC20 Token
    participant Permit2
    participant Facilitator
    participant ExactProxy as x402ExactPermit2Proxy
    participant Recipient

    Note over User: One-time setup on Permit2 chains
    User->>Token: approve(Permit2, amount or max)
    Token-->>User: Approval recorded

    Note over User,Facilitator: Every payment
    User->>User: Signs Permit2 witness authorization
    User->>Facilitator: Sends signed payment payload

    Facilitator->>ExactProxy: transferWithPermit2(...)
    ExactProxy->>Permit2: settle signed transfer
    Permit2->>Token: transferFrom(user, facilitator, amount)
    Token-->>Facilitator: Tokens moved

    Facilitator->>Recipient: Settle recipient amount and fees
    Facilitator-->>User: Payment complete
```

## MRDN Token

MRDN (`Meridian`, 18 decimals) has a fixed canonical supply of 1 billion tokens
on Base and uses LayerZero's Omnichain Fungible Token (OFT) standard to move
between Base and Robinhood Chain. The Base adapter locks canonical MRDN when
bridging out; the Robinhood OFT mints the corresponding representation and
burns it when MRDN returns to Base.

### Deployed contracts

| Network                  | Contract              | Address                                      |
| ------------------------ | --------------------- | -------------------------------------------- |
| Base (`8453`)            | Canonical MRDN        | `0xE57E601c06689D3e2BF7DB7bebb14B4ff28400C6` |
| Base (`8453`)            | LayerZero OFT Adapter | `0x6Dd74a4B532659CE2F82e85cCCd2e5989ceA3589` |
| Robinhood Chain (`4663`) | MRDN OFT              | `0xBaabCB1800C539a58a46035d3982403a37FD6d5D` |

### LayerZero route

| Network         | Endpoint ID | LayerZero Endpoint V2                        | Remote peer                |
| --------------- | ----------- | -------------------------------------------- | -------------------------- |
| Base            | `30184`     | `0x1a44076050125825900e736c501f859c50fE728c` | Robinhood OFT (`30416`)    |
| Robinhood Chain | `30416`     | `0x6F475642a6e85809B1c36Fa62763669b1b48DD5B` | Base OFT Adapter (`30184`) |

The route uses six shared decimals and is open in both directions. OFT send
messages use `msgType 1` with an enforced destination receive-gas limit of
`100,000`. LayerZero Labs and Nethermind are the two required DVNs on each
direction. Ownership and LayerZero Endpoint delegation are held by the Meridian
Safe at `0x37E9CA7154F539113626903edf1f5a14714A0faa`.

## Solana (SVM)

On Solana, Meridian settles through the `meridian_x402` program instead of a
Solidity facilitator. Solana needs no EIP-3009: a transaction can carry multiple
signers, so the payer signs the settlement transaction as their USDC token
authority and the facilitator co-signs as fee payer and submits it. Settlement
is atomic — the program splits fees and the recipient's net directly from the
payer's token account in one transaction, with no escrow hop.

The program is live on both `solana` (mainnet) and `solana-devnet`. See
[Solana Program](/payments/solana-program) for the architecture, accounts, and
fee math, and [Solana payments](/ai-skills/solana) for an end-to-end integration
guide.

## How a Payment Flows

1. **Authorization Signing**: Payer signs a payment authorization with amount, recipient context, and network details.
2. **Verification**: Server verifies signature and authorization parameters.
3. **Transfer Execution**: Meridian executes settlement through the facilitator — `transferWithAuthorization` for native EIP-3009 tokens, `transferWithPermit2` via the proxy elsewhere.
4. **Fee Application**: Recipient and fee amounts are handled during settlement processing.

Payments are linked to your organization: API keys authenticate verification and settlement, the recipient wallet is configured in organization settings, and every payment lands in your organization's transaction history in [Command Centre](/command-centre/transactions).