txproxy

TxProxy Service

TxProxy is the centralized transaction signing and broadcasting gatekeeper for the Neo N3 Mini-App Platform. It holds the platform's TEE signing keys and enforces strict allowlist policies before signing any transaction.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      TxProxy Service                        │
├─────────────────────────────────────────────────────────────┤
│  Security Layer                                             │
│  ├── Contract Allowlist - Only approved contracts           │
│  ├── Method Allowlist - Only approved methods per contract  │
│  ├── Intent Policy - Asset constraints (GAS/NEO)            │
│  └── Replay Protection - Request ID deduplication           │
├─────────────────────────────────────────────────────────────┤
│  Signing Layer                                              │
│  ├── GlobalSigner Client - Preferred (centralized TEE key)  │
│  └── Local TEE Signer - Fallback (enclave-held key)         │
└─────────────────────────────────────────────────────────────┘

File Structure

services/txproxy/marble/
├── service.go      # Main service, initialization, replay cache
├── handlers.go     # HTTP request handler
├── allowlist.go    # Contract/method allowlist logic
└── types.go        # Type definitions

API Endpoint

Allowlist Configuration

The allowlist defines which contracts and methods TxProxy will sign transactions for.

Format

{
  "contracts": {
    "<contract_address>": ["method1", "method2"],
    "<contract_address>": ["*"]
  }
}

Example (allow platform contracts):

{
  "contracts": {
    "<gas_address>": ["transfer"],
    "<paymenthub_address>": ["configureApp", "withdraw"],
    "<governance_address>": ["stake", "unstake", "vote"],
    "<randomnesslog_address>": ["record"],
    "<pricefeed_address>": ["update"],
    "<automationanchor_address>": ["markExecuted"],
    "<servicegateway_address>": ["fulfillRequest"]
  }
}

Rules

• Contract addresses are normalized to lowercase without 0x prefix (40 hex chars)
• Method names are canonicalized by lowercasing the first character (to match Neo C# devpack manifest names like getLatest, setUpdater, transfer)
• "*" allows all methods on a contract (not recommended in production)
• Empty array [] blocks all methods

Loading Priority

1. TXPROXY_ALLOWLIST secret (MarbleRun injected)
2. TXPROXY_ALLOWLIST environment variable
3. Empty allowlist (blocks all)

Intent Policy Gating

Request field intent enables stricter checks for platform user flows:

Requires corresponding contract address environment variables:

• CONTRACT_PAYMENT_HUB_ADDRESS for payments intent
• CONTRACT_GAS_ADDRESS (optional override; defaults to native GAS address)
• CONTRACT_GOVERNANCE_ADDRESS for governance intent

Note: the allowlist must still permit GAS transfer when using the payments intent.

Replay Protection

• Each request includes a unique request_id
• TxProxy maintains an in-memory cache of seen request IDs
• Duplicate requests within the replay window (10 min) are rejected
• Cache cleanup runs periodically to remove expired entries

Configuration

Security

4-Layer Defense

1. SDK Layer: Type signatures prevent invalid asset parameters
2. Edge Layer: Validates JWT, enforces rate limits
3. TxProxy Layer: Allowlist + intent policy + replay protection
4. Contract Layer: Hardcoded asset checks (if asset != GAS throw)

Key Management

• GlobalSigner (Preferred): Signing keys held in dedicated TEE service
• Local Key (Fallback): Key injected via MarbleRun manifest
• Keys never leave the enclave boundary