This repository is a template for building high-integrity oracles on Phala Cloud with Node.js (Typescript). It provides a robust solution to a core problem faced by trust-minimized systems. For blockchains, this is the classic "oracle problem": as deterministic systems, they cannot safely fetch external data. For autonomous AI agents, it is a data integrity problem: they require verifiable, untampered data to make critical decisions. This template provides a secure bridge for both through a two-fold guarantee: verifiable computation from Phala's TEEs and verifiable networking, powered by the hardened-https-agent.
A trustworthy oracle must prove two things: that its internal logic was executed correctly and that the data it processed came from authentic, untampered sources. This template achieves both.
The application is designed to run inside a TEE (Trusted Execution Environment). A TEE is a secure, isolated hardware vault that protects code and data from the host system. Through attestation, a TEE can produce a cryptographic proof (a quote) that it is a genuine TEE running a specific, unmodified version of the oracle code.
Phala enhances this core guarantee by leveraging its decentralized TEEs cloud network, which provides a multi-layered security model. Phala creates a transparent, on-chain "birth certificate" for every oracle instance, making it fully auditable. The decentralized network provides resilience by detecting and removing faulty or compromised TEE nodes. Finally, the DStack SDK, operating within the TEE, enforces strict confidentiality, ensuring critical secrets like API keys are never exposed, even to the node operators themselves.
Verifiable Networking (via hardened-https-agent)
A TEE's guarantee stops at its own boundary; it cannot natively verify that network data is authentic. An attacker could perform a Man-in-the-Middle attack (e.g., via DNS hijacking) to feed the TEE malicious data.
This template solves that problem by using hardened-https-agent, a security-first https.Agent for Node.jst hat applies browser-grade security policies to all outgoing TLS connections.
By combining the TEE's verifiable computation with the agent's verifiable networking, we create a system that cryptographically secures the data's entire journey, from its external source to its final attested form.
This template includes a practical example: a PriceAggregator class that securely fetches the price of the BTC/USD pair from multiple public APIs.
Its logic is simple but robust:
- It fetches data from all configured sources in parallel.
- It uses JSONPath to extract the price from each response.
- It calculates the average price.
- It checks that the variance between sources does not exceed a
deviationThreshold, ensuring data consistency and protecting against faulty or malicious data from a single source.
This class serves as a foundational example. Its core logic can, of course, be significantly improved, but it also serves as a solid base that can be adapted for many other use cases.
The patterns in this template can be extended to build a wide variety of oracles:
- Majority Vote Aggregation: For categorical data, such as reporting the winner of an election or the outcome of a sporting event from multiple news APIs.
- Median Value Aggregation: For financial data, using a median instead of an average to provide stronger resistance to outlier manipulation.
- Exact Match Verification: Fetching a critical, unique piece of data (like a document hash, a software release checksum, or a Git commit ID) from multiple sources and ensuring they are all identical.
- Verifiable Randomness: Using the TEE to securely combine randomness from multiple public sources (e.g., randomness beacons) to generate a single, high-entropy random number.
- Parametric Insurance Triggers: Fetching real-world data (e.g., weather reports from multiple meteorology APIs) to trigger parametric insurance smart contracts, for instance, paying out a claim for flight delays or crop failures based on verified, aggregated data.
This oracle exposes two primary endpoints:
GET /: Returns basic information (TCB Info of the hosted CVM) about the TEE instance.GET /attested-price/btc-usd: Returns the high-integrity, attested price data.
The /attested-price/btc-usd endpoint returns a JSON object containing the complete, verifiable payload:
{
"report": {
"pair": "BTC/USD",
"price": 923456.78,
"timestamp": "2029-05-15T14:30:00.000Z"
},
"sources": [
{ "url": "...", "path": "..." }
],
"deviationThreshold": 0.01, // 1%
"quote": {
// ... TEE attestation quote data ...
}
}The quote is a cryptographic attestation of a hash of the report, sources, and deviationThreshold objects. A client can verify this quote to be certain that the data was generated by this specific oracle code, using those exact inputs and validation rules.
First, follow these steps to set up your development environment.
Install the Phala CLI globally:
npm i -g phala
phala helpClone the repository:
git clone --depth 1 https://github.com/Gldywn/phala-cloud-oracle-template.git
cd phala-cloud-oracle-templateInstall dependencies and create your .env file from the template:
npm i
cp env.example .envBefore running the development server, you need to have an active DStack simulator running.
Start the simulator:
phala simulator start
# You will get something like this
✓ Setting environment for current process...
✓ DSTACK_SIMULATOR_ENDPOINT=/<user>/.phala-cloud/simulator/0.5.3/dstack.sock
✓ TAPPD_SIMULATOR_ENDPOINT=/<user>/.phala-cloud/simulator/0.5.3/tappd.sock
✓ TEE simulator started successfullyDSTACK_SIMULATOR_ENDPOINT variable inside your .env file with the one output by the start command.
Once the simulator is running, you can start your Express development server:
npm run devBy default, the Express development server will listen on port 3000. Open http://localhost:3000/attested-price/btc-usd in your browser to get the BTC/USD pair attested price data.
The provided docker-compose.yml includes a shared logging config to restrict log growth as recommended here.
Build a linux/amd64 image locally via Docker:
phala docker build --image phala-cloud-oracle-template --tag latestLog in to Docker using Phala CLI:
phala docker loginPush your linux/amd64 image to Docker Hub:
phala docker push --image <docker-user>/phala-cloud-oracle-template:latestDeploy a new CVM instance using your Docker Compose file:
phala deploy docker-compose.ymlThis starter requires DStack v0.5 or higher for deployment on Phala Cloud, which is currently running a closed beta for this version. If your deployed CVM is not yet on v0.5, please request beta access on the official Telegram or Discord.