Oracle Network

Decentralized attestation layer that verifies cross-chain events.

---

Purpose

The oracle network is the trust layer between chains. Oracles independently observe events on the source chain and produce signed attestations that the target chain can verify. No single oracle can forge a claim — the system requires a configurable threshold of independent signatures.

---

Architecture

SOURCE CHAIN                ORACLE NETWORK               TARGET CHAIN
════════════                ══════════════               ════════════

Bridge contract             ┌──────────┐
emits event ───────────────►│ Oracle 1 │──► signs
                            ├──────────┤
                  ────────►│ Oracle 2 │──► signs          claim()
                            ├──────────┤                  requires
                  ────────►│ Oracle 3 │──► signs          min T sigs
                            ├──────────┤                       │
                  ────────►│ Oracle N │──► signs               │
                            └──────────┘                       │
                                  │                            │
                       T of N signatures ─────────────────────►│
                                                               │
                                                    Contract verifies,
                                                    mints/unlocks tokens

---

Oracle Process

Direction: Source → Target (e.g., WAX → Avalanche)

1. Source chain bridge contract locks tokens and emits a logteleport event
2. Each oracle independently detects the event (via state history, Hyperion, or polling)
3. Each oracle serializes the teleport data into a packet
4. Each oracle signs the packet with its private key
5. Signatures are stored on the source chain (WAX teleports table)
6. Player (or relayer) collects signatures and calls claim() on the target chain
7. Target contract verifies each signature against registered oracle addresses
8. If valid_signatures >= threshold, claim is processed

Direction: Target → Source (e.g., Avalanche → WAX)

1. Target chain teleport() function burns tokens and emits Teleport event
2. Oracles detect the event via WebSocket/RPC
3. Oracles call received() on the source chain to confirm the transfer
4. Source chain contract releases locked tokens to the destination account
5. Oracle calls claimed() when the Avalanche-side event is processed

---

Reference Implementation

Component	File	Runtime
WAX → AVAX oracle	bridge-oracle/oracle-eos.js	Node.js
AVAX → WAX oracle	bridge-oracle/oracle-eth.js	Node.js

oracle-eos.js

• Connects to WAX via State History Plugin (SHIP)
• Uses TraceHandler to process action traces
• Detects logteleport actions on the bridge contract
• Serializes teleport data into a signature packet
• Calls sign() on the WAX bridge contract with the oracle's key

oracle-eth.js

• Connects to Avalanche via WebSocket RPC
• Listens for Teleport events on the bridge contract
• Detects Claimed events for bookkeeping
• Calls received() on WAX when detecting outgoing teleports
• Calls claimed() on WAX when detecting claims

---

Configuration

{
  precision: 4,                    // Token decimal places
  symbol: 'THC',                   // Token symbol (configurable per deployment)
  network: 'AVAX',                 // Target network identifier

  eos: {
    chainId: '...',                // Source chain ID  
    wsEndpoint: 'ws://...',        // State History Plugin endpoint
    endpoint: 'https://...',       // API endpoint
    teleportContract: '...',       // Bridge contract account
    oracleAccount: '...',          // This oracle's account
    privateKey: '...'              // This oracle's signing key
  },

  eth: {
    teleportContract: '0x...',     // Target bridge contract address
    wsEndpoint: 'wss://...',       // WebSocket RPC
    endpoint: 'https://...',       // HTTP RPC (fallback)
    oracleAccount: '0x...',        // This oracle's EVM address
    privateKey: '...',             // This oracle's EVM key
    chainId: 2                     // Bridge-internal chain ID (NOT EVM chain ID)
  }
}

---

Security

Threshold Consensus

Configuration	Security Level	Use Case
Threshold = 1	Very low	Testnet only
Threshold = 2	Low	Development
Threshold ≥ 3	Recommended	Production
Threshold = 2/3 N	High	High-value bridges

Rule: No single oracle should be able to forge claims in production.

Key Management

• Oracle signing keys should be stored in a KMS (AWS KMS, GCP KMS, HSM)
• Keys should never be committed to source control
• Each oracle should run on separate infrastructure from separate operators
• Rotation requires updating the registered address on both chain contracts

Monitoring

Metric	Alert Condition
Unsigned teleports	Teleport event older than 5 minutes without oracle signature
Oracle downtime	Oracle process not producing signatures
Bridge volume	Unusually large transfers (possible exploit)
Claim failures	claim() transactions reverting
Balance discrepancy	Source locked balance ≠ target minted supply

---

Running Your Own Oracle

To deploy an oracle for a Monsuta Core bridge:

1. Provision infrastructure — separate VPS or cloud instance, distinct from game server
2. Install dependencies — Node.js, required packages
3. Configure — set contract addresses, endpoints, private keys in config
4. Register — call regOracle() on both chain contracts to whitelist the oracle address
5. Start — run both oracle-eos.js and oracle-eth.js
6. Monitor — set up alerts for the metrics listed above
7. Secure — restrict SSH access, use firewall rules, enable process supervision (pm2, systemd)