Quickstart

Integrate the Morpheus Privacy Oracle into your Neo smart contracts in under 5 minutes. This guide covers the end-to-end flow from encrypting secrets to reading the TEE-verified result on-chain.

Step 1: Understand the Data Flow

The Morpheus network requires an asynchronous request-callback pattern. You must implement a callback function in your contract to receive the response.

Step 2: Seal Your Parameters (Off-Chain)

Before calling the Oracle contract, encrypt any sensitive API keys or parameters locally. The worker's active X25519 public key is exposed through the frontend proxy and also published on-chain in the Oracle registry metadata.

// 1. Fetch TEE Public Key
const res = await fetch("/api/oracle/public-key");
const { public_key } = await res.json();

// 2. Your confidential injection payload
const secrets = {
  "headers": { "Authorization": "Bearer YOUR_PRIVATE_API_KEY" }
};

// 3. Encrypt locally using X25519 + HKDF-SHA256 + AES-256-GCM
const encryptedBlob = await encryptWithOracleX25519(JSON.stringify(secrets), public_key);

Step 3: Submit On-Chain Request

Build a JSON payload, then pass that payload bytestring to the Oracle contract. On Neo N3 the request currently costs 0.01 GAS of prepaid credit; on Neo X the reference interface uses requestFee().

// Mainnet Oracle: 0x017520f068fd602082fe5572596185e62a4ad991
// NeoNS alias: oracle.morpheus.neo

public static BigInteger FetchPrivateData(ByteString encryptedBlob)
{
    string payloadJson = "{\"url\":\"https://api.secret.io\","
        + "\"encrypted_params\":\"" + (string)encryptedBlob + "\","
        + "\"json_path\":\"data.price\","
        + "\"target_chain\":\"neo_n3\"}";

    return (BigInteger)Contract.Call(
        OracleHash,
        "request",
        CallFlags.All,
        "oracle",
        (ByteString)payloadJson,
        Runtime.ExecutingScriptHash,
        "onOracleResult"
    );
}

public static void OnOracleResult(BigInteger requestId, string requestType, bool success, ByteString result, string error)
{
    Storage.Put(Storage.CurrentContext, "last_result", result);
}

Step 4: Await the Relayer Callback

Once the transaction is mined, the Morpheus Relayer detects the event, forwards the encrypted payload to the Phala TEE, and then submits a callback transaction back to your contract containing the signed result envelope. If the upstream fetch or compute fails, the request should still finalize with a failure callback instead of being silently dropped.