Oracle API Reference

curl -s 'https://nuntius.kaskad.live/prices/ETH%2FUSD'

{
  "price": {
    "asset_id": "0x0b43555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45",
    "asset_symbol": "ETH/USD",
    "price": "245070790020",
    "price_human": "2450.70790020",
    "timestamp": 1792577431,
    "num_sources": 10,
    "sources_hash": "0x54f96140454ba272dbcd7191a321fc969490b7c59716232a40cc040bbd47f04f",
    "signature": "0x8bebaa400ffbf50964e80a8f8d29f9a4cbfdb17a137db7fe2f06baa25c359cf127538bced6992106e021f2bdaef8a9ef13be4add7d412b5584bc57a77b5f1aaa1c",
    "signer": "0xe4d88be9756eb3fc5bd28b81642605fbf238d2c9"
  },
  "signer": "0xe4d88be9756eb3fc5bd28b81642605fbf238d2c9"
}

{
  "num_assets": 12,
  "prices": [
    { "asset_id": "0xa839…9db4", "asset_symbol": "PONS/USD", "price": "28176289", "price_human": "0.28176289", "timestamp": 1792577423, "num_sources": 3, … },
    …
  ],
  "signer": "0xe4d88be9756eb3fc5bd28b81642605fbf238d2c9"
}

{ "status": "ok", "signer": "0xe4d88be9756eb3fc5bd28b81642605fbf238d2c9", "num_assets": 12, "attestation_healthy": true }

{ "signer": "0xe4d88be9756eb3fc5bd28b81642605fbf238d2c9", "attestation_doc": "8444a101…" }

{"service":"Kaskad TEE Oracle","version":"0.1.0","endpoints":["/prices","/prices/{SYMBOL}","/health","/attestation"],"docs":"Query signed price data from Nitro Enclave"}

bytes32 digest = keccak256(abi.encodePacked(assetId, price, timestamp, numSources, sourcesHash));
address signer = ECDSA.recover(MessageHashUtils.toEthSignedMessageHash(digest), signature);

# The asset id is keccak256 of the symbol.
cast keccak 'ETH/USD'
# 0x0b43555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45

# Pack the five fields (129 bytes) and hash them.
PACKED=$(cast abi-encode --packed 'f(bytes32,uint256,uint256,uint8,bytes32)' \
  0x0b43555ace6b39aae1b894097d0a9fc17f504c62fea598fa206cc6f5088e6e45 \
  245070790020 1792577431 10 \
  0x54f96140454ba272dbcd7191a321fc969490b7c59716232a40cc040bbd47f04f)
DIGEST=$(cast keccak $PACKED)
echo $DIGEST
# 0x8f77938db9d960326358a572b90c460fee37397c8cd5a1535f2594953996d792

# cast adds the EIP-191 prefix, recovers the signer and compares it.
cast wallet verify --address 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 $DIGEST \
  0x8bebaa400ffbf50964e80a8f8d29f9a4cbfdb17a137db7fe2f06baa25c359cf127538bced6992106e021f2bdaef8a9ef13be4add7d412b5584bc57a77b5f1aaa1c
# Validation succeeded. Address 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 signed this message.

function updatePrice(bytes32 assetId, uint256 price, uint256 timestamp, uint8 numSources, bytes32 sourcesHash, bytes calldata signature) external

struct PriceUpdate {
    bytes32 assetId;
    uint256 price;
    uint256 timestamp;
    uint8   numSources;
    bytes32 sourcesHash;
    bytes   signature;
}

mkdir nuntius-scripts && cd nuntius-scripts
npm init -y && npm pkg set type=module
npm install viem@2.57.7 tsx@4.23.15

// Chain definitions shared by the examples.
import { defineChain } from "viem";

export const igra = defineChain({
  id: 38833,
  name: "Igra",
  nativeCurrency: { name: "iKAS", symbol: "iKAS", decimals: 18 },
  rpcUrls: { default: { http: [process.env.IGRA_RPC ?? "https://rpc.igralabs.com:8545"] } },
});

export const robinhood = defineChain({
  id: 4663,
  name: "Robinhood Chain",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: { default: { http: [process.env.RH_RPC ?? "https://rpc.mainnet.chain.robinhood.com"] } },
});

// Fetch signed prices from Nuntius, recover each signer, and dry-run updatePrice on KaskadPriceOracleV2.
import { BaseError, ContractFunctionRevertedError, createPublicClient, encodePacked, http, keccak256, parseAbi, recoverMessageAddress, type Hex } from "viem";
import { robinhood } from "./chains.ts";

const NUNTIUS_URL = "https://nuntius.kaskad.live";
const ORACLE = "0xB4922b744cc395E05Cc962d55FA63FBab0599ec2"; // KaskadPriceOracleV2, Robinhood Chain

interface SignedPrice {
  asset_id: Hex; // keccak256 of asset_symbol
  asset_symbol: string;
  price: string; // integer, 8 decimals
  price_human: string;
  timestamp: number; // unix seconds, set by the enclave
  num_sources: number;
  sources_hash: Hex;
  signature: Hex;
  signer: Hex;
}

const oracleAbi = parseAbi([
  "function isValidSigner(address who) view returns (bool)",
  "function updatePrice(bytes32 assetId, uint256 price, uint256 timestamp, uint8 numSources, bytes32 sourcesHash, bytes signature)",
  // Errors updatePrice can raise, verbatim from KaskadPriceOracleV2.sol.
  "error NoEnclaveRegistered()",
  "error ZeroPrice()",
  "error AssetNotRegistered(bytes32 assetId)",
  "error InsufficientSources()",
  "error FutureTimestamp(uint256 provided, uint256 maxAllowed)",
  "error StalePrice(uint256 provided, uint256 current)",
  "error PriceChangeExceedsLimit(uint256 changeBps, uint256 maxBps)",
  "error InvalidSignature()",
]);

const client = createPublicClient({ chain: robinhood, transport: http() });
const { prices } = (await (await fetch(`${NUNTIUS_URL}/prices`)).json()) as { prices: SignedPrice[] };

for (const p of prices) {
  if (p.asset_id !== keccak256(new TextEncoder().encode(p.asset_symbol))) throw new Error(`asset id mismatch: ${p.asset_symbol}`);

  // The contract verifies EIP-191 over keccak256(abi.encodePacked(assetId, price, timestamp, numSources, sourcesHash)).
  const digest = keccak256(encodePacked(
    ["bytes32", "uint256", "uint256", "uint8", "bytes32"],
    [p.asset_id, BigInt(p.price), BigInt(p.timestamp), p.num_sources, p.sources_hash],
  ));
  const signer = await recoverMessageAddress({ message: { raw: digest }, signature: p.signature });
  const registered = await client.readContract({ address: ORACLE, abi: oracleAbi, functionName: "isValidSigner", args: [signer] });

  // Dry run: would the oracle accept this update right now? Nothing is sent.
  let verdict = "accepted";
  try {
    await client.simulateContract({
      address: ORACLE, abi: oracleAbi, functionName: "updatePrice",
      args: [p.asset_id, BigInt(p.price), BigInt(p.timestamp), p.num_sources, p.sources_hash, p.signature],
    });
  } catch (err) {
    const revert = err instanceof BaseError ? err.walk((e) => e instanceof ContractFunctionRevertedError) : null;
    verdict = revert instanceof ContractFunctionRevertedError ? `rejected: ${revert.data?.errorName ?? revert.shortMessage}` : `rejected: ${String(err)}`;
  }

  console.log(p.asset_symbol.padEnd(11), p.price_human.padStart(16), `sources=${p.num_sources}`, signer, registered ? "registered" : "NOT REGISTERED", verdict);
}

$ npx tsx verify-prices.ts
BTC/USD       83316.69706925 sources=9 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
NVDA/USD        221.16096255 sources=4 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
KAS/USD           0.03874287 sources=5 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
ETH/USD        2460.79649515 sources=10 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
USDG/USD          0.99998000 sources=4 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
USDC/USD          0.99997355 sources=5 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
IGRA/USD          0.00306553 sources=2 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
TIBBIR/USD        0.25938200 sources=2 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
USDT/USD          0.99878500 sources=3 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
TSLA/USD        378.76923555 sources=3 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
PONS/USD          0.28994729 sources=5 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted
TAO/USD         273.17768535 sources=3 0xE4D88bE9756EB3fc5bD28B81642605FBF238d2c9 registered accepted

// Borrow through KaskadRouter, pushing fresh Nuntius prices for the lending reserves in the same transaction.
import { createPublicClient, createWalletClient, erc20Abi, http, parseAbi, parseUnits, type Address, type Chain, type Hex } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { igra, robinhood } from "./chains.ts";

enum Network {
  Robinhood = "robinhood",
  Igra = "igra",
}

enum InterestRateMode {
  Variable = 2,
}

interface Deployment {
  chain: Chain;
  nuntiusUrl: string;
  router: Address;
  poolAddressesProvider: Address;
}

const deployments: Record<Network, Deployment> = {
  [Network.Robinhood]: {
    chain: robinhood,
    nuntiusUrl: "https://nuntius.kaskad.live",
    router: "0x75cbB7B191307F869f54479897D87B3a7C20bb0F",
    poolAddressesProvider: "0x3e9a28d988eE889B47bF257F0e103960721475d0",
  },
  [Network.Igra]: {
    chain: igra,
    nuntiusUrl: "https://kaskad.live/enclave",
    router: "0xD22606268c0929AB299918eCf9c6E0eEA0977A0C",
    poolAddressesProvider: "0x4e718714BF19c7BBcf402ecA92f971B8a65c716D",
  },
};

interface SignedPrice {
  asset_id: Hex;
  price: string;
  timestamp: number;
  num_sources: number;
  sources_hash: Hex;
  signature: Hex;
}

// Mirrors KaskadRouter.PriceUpdate.
interface PriceUpdate {
  assetId: Hex;
  price: bigint;
  timestamp: bigint;
  numSources: number;
  sourcesHash: Hex;
  signature: Hex;
}

const routerAbi = parseAbi([
  "struct PriceUpdate { bytes32 assetId; uint256 price; uint256 timestamp; uint8 numSources; bytes32 sourcesHash; bytes signature; }",
  "function borrowWithPrices(PriceUpdate[] prices, address asset, uint256 amount, uint256 interestRateMode)",
  "error PriceUpdateFailed(bytes32 assetId)",
  "error StaleAsset(address asset)",
]);
const providerAbi = parseAbi(["function getPool() view returns (address)", "function getPriceOracle() view returns (address)"]);
const poolAbi = parseAbi([
  "struct ReserveData { uint256 configuration; uint128 liquidityIndex; uint128 currentLiquidityRate; uint128 variableBorrowIndex; uint128 currentVariableBorrowRate; uint128 currentStableBorrowRate; uint40 lastUpdateTimestamp; uint16 id; address aTokenAddress; address stableDebtTokenAddress; address variableDebtTokenAddress; address interestRateStrategyAddress; uint128 accruedToTreasury; uint128 unbacked; uint128 isolationModeTotalDebt; }",
  "function getReservesList() view returns (address[])",
  "function getReserveData(address asset) view returns (ReserveData)",
]);
const aaveOracleAbi = parseAbi(["function getSourceOfAsset(address asset) view returns (address)"]);
const nuntiusFeedAbi = parseAbi(["function assetId() view returns (bytes32)"]);
const debtTokenAbi = parseAbi([
  "function borrowAllowance(address fromUser, address toUser) view returns (uint256)",
  "function approveDelegation(address delegatee, uint256 amount)",
]);

function parseNetwork(value: string | undefined): Network {
  if (value === undefined) return Network.Robinhood;
  const network = Object.values(Network).find((n) => n === value);
  if (!network) throw new Error(`NETWORK must be one of: ${Object.values(Network).join(", ")}`);
  return network;
}

const { chain, nuntiusUrl, router, poolAddressesProvider } = deployments[parseNetwork(process.env.NETWORK)];
const asset = process.env.ASSET as Address | undefined; // reserve to borrow
const amount = process.env.AMOUNT; // in token units, e.g. "10"
if (!process.env.PRIVATE_KEY || !asset || !amount) {
  throw new Error("usage: [NETWORK=igra] PRIVATE_KEY=0x... ASSET=0x... AMOUNT=10 npx tsx borrow-with-prices.ts");
}

const account = privateKeyToAccount(process.env.PRIVATE_KEY as Hex);
const client = createPublicClient({ chain, transport: http() });
const wallet = createWalletClient({ account, chain, transport: http() });

// 1. Asset ids of the reserves that Nuntius prices. Other reserves use feeds without assetId().
const [pool, aaveOracle] = await Promise.all([
  client.readContract({ address: poolAddressesProvider, abi: providerAbi, functionName: "getPool" }),
  client.readContract({ address: poolAddressesProvider, abi: providerAbi, functionName: "getPriceOracle" }),
]);
const reserves = await client.readContract({ address: pool, abi: poolAbi, functionName: "getReservesList" });
const reserveIds = new Set<string>();
for (const reserve of reserves) {
  const source = await client.readContract({ address: aaveOracle, abi: aaveOracleAbi, functionName: "getSourceOfAsset", args: [reserve] });
  const id = await client.readContract({ address: source, abi: nuntiusFeedAbi, functionName: "assetId" }).catch(() => null);
  if (id) reserveIds.add(id.toLowerCase());
}

// 2. Signed prices for those reserves.
const response = await fetch(`${nuntiusUrl}/prices`);
if (!response.ok) throw new Error(`GET /prices failed: HTTP ${response.status}`);
const { prices } = (await response.json()) as { prices: SignedPrice[] };
const updates: PriceUpdate[] = prices
  .filter((p) => reserveIds.has(p.asset_id.toLowerCase()))
  .map((p) => ({
    assetId: p.asset_id,
    price: BigInt(p.price),
    timestamp: BigInt(p.timestamp),
    numSources: p.num_sources,
    sourcesHash: p.sources_hash,
    signature: p.signature,
  }));

// 3. The router borrows on your behalf, so it needs credit delegation on the variable debt token.
const decimals = await client.readContract({ address: asset, abi: erc20Abi, functionName: "decimals" });
const value = parseUnits(amount, decimals);
const { variableDebtTokenAddress } = await client.readContract({ address: pool, abi: poolAbi, functionName: "getReserveData", args: [asset] });
const allowance = await client.readContract({
  address: variableDebtTokenAddress, abi: debtTokenAbi, functionName: "borrowAllowance", args: [account.address, router],
});
if (allowance < value) {
  const hash = await wallet.writeContract({ address: variableDebtTokenAddress, abi: debtTokenAbi, functionName: "approveDelegation", args: [router, value] });
  await client.waitForTransactionReceipt({ hash });
}

// 4. Push the prices and borrow in one transaction. The simulation surfaces PriceUpdateFailed or StaleAsset before anything is sent.
const { request } = await client.simulateContract({
  account, address: router, abi: routerAbi, functionName: "borrowWithPrices",
  args: [updates, asset, value, BigInt(InterestRateMode.Variable)],
});
const receipt = await client.waitForTransactionReceipt({ hash: await wallet.writeContract(request) });
console.log(`borrow ${receipt.status} in block ${receipt.blockNumber}: ${amount} sent to ${account.address}, ${updates.length} price(s) pushed`);

# Robinhood Chain: borrow 10 USDG
PRIVATE_KEY=0x… ASSET=0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168 AMOUNT=10 npx tsx borrow-with-prices.ts
# Igra: borrow 1 USDT
NETWORK=igra PRIVATE_KEY=0x… ASSET=0x46346F49b4fe8c640c5FCdbed2d6741056FEB959 AMOUNT=1 npx tsx borrow-with-prices.ts

borrow success in block 94249184: 10 sent to 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, 1 price(s) pushed
borrow success in block 19791508: 1 sent to 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266, 5 price(s) pushed

ORACLE=0xB4922b744cc395E05Cc962d55FA63FBab0599ec2
RPC=https://rpc.mainnet.chain.robinhood.com
cast call $ORACLE "latestPrices(bytes32)(uint256,uint256,uint256,uint8,bytes32,uint80)" $(cast keccak 'PONS/USD') --rpc-url $RPC

28813937 [2.881e7]
1792581045 [1.792e9]
1792581020 [1.792e9]
5
0x6821d62bd588ada46b1d08131466d57543090d3296da4de45e450cd560951a15
44

cast logs --address $ORACLE \
  "PriceUpdated(bytes32 indexed assetId, uint256 price, uint256 timestamp, uint8 numSources, uint80 roundId)" \
  $(cast keccak 'PONS/USD') --from-block 94000000 --rpc-url $RPC