EXTENDED DOCUMENTATION

Morpheus Paymaster

Purpose

Morpheus Paymaster is a policy-gated sponsorship service exposed by the Oracle runtime at:

  • text
    POST /paymaster/authorize

It is intended to sponsor pre-approved Neo N3 Abstract Account operations without exposing a global open faucet.

Current production architecture:

  • ingress, auth, rate limit, and recovery stay outside the TEE
  • the Oracle CVM executes the confidential authorization path
  • mainnet and testnet share the same Oracle CVM and differ only by network-scoped policy variables and request metadata

Current runtime scope:

  • active supported chain:
    text
    neo_n3
  • Neo X sponsorship examples are not part of the current production path

Security Model

The service does not blindly pay for arbitrary requests.

Current controls:

  • network-scoped enable/disable flags
  • policy ids
  • per-network max gas limit
  • per-network allowlisted target contracts
  • per-network allowlisted method names
  • optional per-network allowlisted account ids
  • optional per-network blocklisted account ids
  • optional per-network allowlisted dapp ids
  • short-lived signed authorization result
  • TEE attestation bound to the authorization payload

The returned payload includes:

  • text
    approved
  • text
    network
  • text
    target_chain
  • text
    sponsorship_id
  • text
    expires_at
  • text
    output_hash
  • text
    signature
  • text
    public_key
  • text
    tee_attestation

This makes the response portable across:

  • AA relay backends
  • first-party bundlers
  • third-party sponsored execution gateways

Environment Variables

Testnet

  • text
    MORPHEUS_PAYMASTER_TESTNET_ENABLED
  • text
    MORPHEUS_PAYMASTER_TESTNET_POLICY_ID
  • text
    MORPHEUS_PAYMASTER_TESTNET_MAX_GAS_UNITS
  • text
    MORPHEUS_PAYMASTER_TESTNET_ALLOW_TARGETS
  • text
    MORPHEUS_PAYMASTER_TESTNET_ALLOW_METHODS
  • text
    MORPHEUS_PAYMASTER_TESTNET_ALLOW_ACCOUNTS
  • text
    MORPHEUS_PAYMASTER_TESTNET_BLOCK_ACCOUNTS
  • text
    MORPHEUS_PAYMASTER_TESTNET_ALLOW_DAPPS
  • text
    MORPHEUS_PAYMASTER_TESTNET_TTL_MS

Mainnet

  • text
    MORPHEUS_PAYMASTER_MAINNET_ENABLED
  • text
    MORPHEUS_PAYMASTER_MAINNET_POLICY_ID
  • text
    MORPHEUS_PAYMASTER_MAINNET_MAX_GAS_UNITS
  • text
    MORPHEUS_PAYMASTER_MAINNET_ALLOW_TARGETS
  • text
    MORPHEUS_PAYMASTER_MAINNET_ALLOW_METHODS
  • text
    MORPHEUS_PAYMASTER_MAINNET_ALLOW_ACCOUNTS
  • text
    MORPHEUS_PAYMASTER_MAINNET_BLOCK_ACCOUNTS
  • text
    MORPHEUS_PAYMASTER_MAINNET_ALLOW_DAPPS
  • text
    MORPHEUS_PAYMASTER_MAINNET_TTL_MS

Request Shape

json
{
  "network": "testnet",
  "target_chain": "neo_n3",
  "account_id": "0x0c3146e78efc42bfb7d4cc2e06e3efd063c01c56",
  "dapp_id": "demo-dapp",
  "target_contract": "0xe24d2980d17d2580ff4ee8dc5dddaa20e3caec38",
  "method": "executeUserOp",
  "estimated_gas_units": 120000,
  "operation_hash": "0x4444444444444444444444444444444444444444444444444444444444444444"
}

zERC20 Builtins

Available builtins:

  • text
    zkp.groth16.verify
  • text
    zkp.zerc20.single_withdraw.verify

text
zkp.zerc20.single_withdraw.verify
is a separate compute helper. It is not part of paymaster policy by default. Applications that need zERC20-specific sponsorship can build that rule on top of the generic paymaster flow.

Integration Patterns

1. AA Relay / Bundler

Call

text
paymaster/authorize
just before relay submission.

Recommended order:

  1. simulate the AA invocation
  2. estimate gas units
  3. call Morpheus Paymaster with normalized operation metadata
  4. submit only if
    text
    approved === true

2. Third-Party Bundler

The bundler can use the signed authorization as a sponsorship ticket and verify:

  • signature
  • text
    policy_id
  • text
    expires_at
  • text
    account_id
  • optional
    text
    dapp_id
  • text
    operation_hash
  • target contract
  • method
  • gas limit
  • attestation metadata

3. Application Server

An app backend can pre-screen business policy, then delegate final sponsorship approval to Morpheus Paymaster so that:

  • app policy remains app-specific
  • TEE-signed sponsorship remains portable

Current AA Integration

The AA frontend relay request builder now forwards optional

text
paymaster
metadata, and the AA relay API can request Morpheus paymaster authorization before broadcasting a relay-ready meta invocation.

This is currently a server-side integration path. It does not require changing the AA on-chain contract.

The latest integrated Oracle + NeoDID + AA verifier regression entrypoint is:

  • text
    npm run examples:test:n3:attack-regression
  • reference docs:
    text
    docs/RELAYER.md
    ,
    text
    docs/SECURITY_AUDIT.md

Validated Neo N3 Testnet Flow

The AA relay + Morpheus paymaster path has been validated live on Neo N3 testnet.

Validated service-side facts:

  • network:
    text
    testnet
  • policy id:
    text
    testnet-aa
  • target chain:
    text
    neo_n3
  • allowed AA target contract:
    text
    0xe24d2980d17d2580ff4ee8dc5dddaa20e3caec38
  • allowed method:
    text
    executeUserOp
  • Oracle CVM app id:
    text
    ddff154546fe22d15b65667156dd4b7c611e6093

Validated end-to-end flow:

  1. register a V3 AA account
  2. update the verifier key
  3. update the paymaster allowlist on the CVM
  4. simulate the AA invocation
  5. request Morpheus paymaster authorization
  6. relay the sponsored
    text
    executeUserOp
  7. confirm on-chain
    text
    HALT

Successful live full-path validation example:

  • account id:
    text
    0x531a5f4d3a916dffbba3ea372317623fdbbb853c
  • register txid:
    text
    0xf79d6a1d3012e9edc64c1a7e40abc932253c7f737873698055ad8f3df8a1869e
  • update verifier txid:
    text
    0xed9c97801a757fb0e3d72d641d75a6659c1242c084134234b5e7cd1a81e903d8
  • relay txid:
    text
    0x057d4a581efbe815fad0148a3766284da2a33335e72fb50e54d476078d8f40d4
  • paymaster approval digest:
    text
    04111a96d6356231c45fdb033ddc91818856c1dc0ac0ce09677ecdb033cae92f
  • paymaster attestation hash:
    text
    73849ae405db210d51c28ff63033bc4bb5f2f0886e1a7478c2557e1ac9c39886

A successful replay path using an already allowlisted account was also validated:

  • account id:
    text
    0x0c3146e78efc42bfb7d4cc2e06e3efd063c01c56
  • relay txid:
    text
    0x0481a3ca7b2af77f762ec50f19f0c81c973885d93d1d24b6f0fbb42cfe56cf04

Operational note:

  • The worker service itself remains protected and is not intended to be left as a public open endpoint.
  • For the live validation harness, the most stable CVM access pattern was
    text
    phala cp
    to upload a helper script, followed by
    text
    phala ssh
    to execute it on the CVM.
  • This replaced an earlier stdin-piped
    text
    phala ssh
    bridge that was intermittently failing with transport error
    text
    255
    .
CURRENT DESIGNUPDATED FOR DUAL-CVM ARCHITECTURE
Morpheus Oracle