API

The Warlock Price Feed API.

Warlock provides signed price feeds via gRPC API. This API will be available in Q3 2024, along with related software development kits. The API utilizes protocol buffers, which allow for easy code generation in most languages.

Primitive data types

The API defines some primitive data types mirroring a subset of the Solidity ABI:

H128

message H128 {
  uint64 hi = 1;
  uint64 lo = 2;
}

H160

message H160 {
  H128 hi = 1;
  uint32 lo = 2;
}

H256

message H256 {
  H128 hi = 1;
  H128 lo = 2;
}

Empty

message Empty {}

EthSignature

An Ethereum signature. ECDSA signatures in Ethereum consist of three parameters: v, r and s. The signature is always 65-bytes in length.

• r (bytes): first 32 bytes of signature

• s (bytes): second 32 bytes of signature

• v (bytes): 1 byte of signature

message EthSignature {
  bytes r = 1;
  bytes s = 2;
  bytes v = 3;
}

Price Feeds

The price feeds API allows users to subscribe to a stream of one or more price feeds by price type, token address, and chain ID. These price feeds are signed with an ECDSA signature by the Warlock council to verify the integrity of the feed for on-chain attestation.

import "types.proto";

package warlock.feeds.v1;

enum PriceType {
    SPOT = 0;
    TWAP = 1;
}

// PriceFeed service offers methods related to the tokens
// on various Ethereum-related chains.
service PriceFeed {

  // GetPriceStream is a server-streaming RPC. It provides real-time and oracle prices
  // for a list of tokens across multiple chains.
  //
  // Parameters:
  //   PriceRequest: Contains information about which tokens' prices
  //                     should be fetched on their respective chains.
  // Returns:
  //   stream of PriceResponse: Continuously streams data about the prices
  //                                of the requested tokens on their respective chains
  //                                as updates are available.
  rpc GetPriceStream (PriceRequest) returns (stream PriceInfo);
}

// PriceRequest encapsulates the details of the tokens for which
// prices are desired.
message PriceRequest {

  // price_info contains the details of each token (like its address and the
  // chain it's on) for which the price should be fetched.
  repeated PriceInfo price_info = 1;
}

// PriceInfo represents the details and the spot price (if available) for a single token
// on a particular blockchain.
message PriceInfo {

  // chain_id denotes the specific chain on which the token is located.
  uint64 chain_id = 1;

  // token_address is the Ethereum address of the token, usually in H160 format.
  H160 token_address = 2;

  // The type of the price update
  PriceType price_type = 3

  // price, if available, is the current price in USD of the token.
  // It is represented in a 60x18 (42 integer digits, 18 decimals) H256 format
  // for high precision. This field is optional since the price might not
  // always be available for every token, and because this message is reused
  // in the request and response stream.
  optional H256 price = 4;

  // Signature validating the price feed.
  optional EthSignature signature = 5;
}