RedStone oracles

How RedStone oracles work with TON

RedStone oracles use an alternative design of providing oracle data to smart contracts. Instead of constantly persisting data on the contract's storage (by data providers), the information is brought on-chain only when needed (by end users). Until that moment, data remains in the decentralized cache layer, powered by RedStone light cache gateways and a stream-based data broadcasting protocol. Data is transferred to the contract by end users, who should attach signed data packages to their function invocations. The information integrity is verified on-chain through signature checking.

To learn more about the RedStone oracle design, see the RedStone docs.

Documentation links

RedStone TON Connector

Smart contracts

price_manager

Sample oracle contract that consumes RedStone oracles data price_manager.fc written in FunC. It requires TVM Upgrade 2023.07.

Initial data

As mentioned above, the data packages transferred to the contract are being verified by signature checking. To be counted to achieve the signer_count_threshold, the signer signing the passed data should be one of the signers passed in the initial data. There is also needed signer_count_threshold to be passed.

Due to the architecture of TON contracts, the initial data must conform to the contract's storage structure, which is constructed as below:

  begin_cell()
    .store_uint(signer_count_threshold, 8)  /// number as passed below
    .store_uint(timestamp, TIMESTAMP_BITS)  /// initially 0 representing the epoch 0
    .store_ref(signers)                     /// serialized tuple of values passed below
  .end_cell();

The value of signers should be passed as a serialized tuple of ints. See tuple.

In the function parameters below, each feed_id is a string encoded to int which means, that's a value consisting of hex-values of the particular letters in the string. For example: 'ETH' as an int is 0x455448 in hex or 4543560 in decimal, as

feed_id(ETH) = 256*256*ord('E')+256*ord('T')+ord('H')` = 4543560

You can use: feed_id=hexlify(toUtf8Bytes(feed_string)) to convert particular values or the online converter.

The value of feed_ids should be passed as a serialized tuple of ints.

The value payload is packed from an array of bytes representing the serialized RedStone payload. See TON RedStone payload packing section below, as well as the file constants.fc, containing all needed int-length constants.

get_prices_v2

(cell) get_prices_v2(cell data_feed_ids, cell payload) method_id;

The function process on-chain the payload passed as an argument and returns a cell of aggregated values of each feed passed as an identifier inside feed_ids.

к сведению

The Function is written for TON Center　API v2.

That are just a method_id get methods—they don't modify the contract's storage and don't consume TONs.

OP_REDSTONE_WRITE_PRICES

Regardless of the on-the-fly processing, there also exists a method for processing the payload on-chain, but saving/writing the aggregated values to the contract's storage. The values persist in the contract's storage and then can be read by using read_prices function. The timestamp of data last saved/written to the contract is able to read by using the read_timestamp function.

The method must be invoked as a TON internal message. The arguments of the message are:

an int representing RedStone_Write_Prices name hashed by keccak256 as defined in constants.ts
a cell ref representing the data_feed_ids as a serialized tuple of ints.\
a cell ref representing the packed RedStone payload

    int op = in_msg_body~load_uint(OP_NUMBER_BITS);

    if (op == OP_REDSTONE_WRITE_PRICES) {
        cell data_feeds_cell = in_msg_body~load_ref();
        cell payload_cell = in_msg_body~load_ref();

    // ...
    }

That's an internal message - it consumes GAS and modifies the contract's storage, so must be paid by TONs.

See how it works at: https://ton-showroom.redstone.finance/

read_prices

(tuple) read_prices(tuple data_feed_ids) method_id;

The function reads the values persisting in the contract's storage and returns a tuple corresponding to the passed feed_ids. The function doesn't modify the storage and can read only aggregated values of the feed_ids saved by using write_prices function.

read_timestamp

(int) read_timestamp() method_id;

Returns the timestamp of data last saved/written to the contract's storage by using OP_REDSTONE_WRITE_PRICES message.

That's just a method_id function - it doesn't modify the contract's storage and don't consume TONs.

price_feed

Due to the architecture of TON contracts, the initial data must convene with the contract's storage structure, which is constructed as below:

beginCell()
  .storeUint(BigInt(hexlify(toUtf8Bytes(this.feedId))), consts.DATA_FEED_ID_BS * 8)
  .storeAddress(Address.parse(this.managerAddress))
  .storeUint(0, consts.DEFAULT_NUM_VALUE_BS * 8)  /// initially 0 representing the epoch 0
  .storeUint(0, consts.TIMESTAMP_BS * 8)
  .endCell();

To define the initial (storage) data for the Price feed contract, use the predefined class PriceFeedInitData.ts.

OP_REDSTONE_FETCH_DATA

Regardless of reading the values persisting in the contract's from outside the network, there is a possibility for fetching the value stored in the contract for a feed_id on-chain directly. There must be invoked an internal message OP_REDSTONE_FETCH_DATA. The arguments of the message are:

an int representing RedStone_Fetch_Data name hashed by keccak256 as defined in constants.ts
an int representing the feed_id value.
a slice representing the initial_sender of the message, to allow they carried the remaining transaction balance when the returning transaction goes.

    int op = in_msg_body~load_uint(OP_NUMBER_BITS);

    if (op == OP_REDSTONE_FETCH_DATA) {
        int feed_id = in_msg_body~load_uint(DATA_FEED_ID_BITS);
        cell initial_payload = in_msg_body~load_ref();

        // ...
    }

The returning message OP_REDSTONE_DATA_FETCHED message is sent to the sender, containing the value and the timestamp of the value has saved. The message can be then fetched in the sender and processed or saved in the sender's storage. The initial payload's ref (initial_payload) is added as a ref containing, for example, the first message's sender, to allow they carry the remaining transaction balance.

begin_cell()
  .store_uint(value, MAX_VALUE_SIZE_BITS)
  .store_uint(timestamp, TIMESTAMP_BITS)
  .store_ref(initial_payload)
  .end_cell()

That's an internal message - it consumes gas and modifies the contract's storage, so must be paid by Toncoins.

get_price_and_timestamp

(int, int) get_price_and_timestamp() method_id;

Returns the last value and timestamp from the adapter's storage.

That's just a method_id function - it doesn't modify the contract's storage and don't consume Toncoins.

single_feed_man

initial data

Similar to the prices and price_feed initial data. Due to the architecture of TON contracts, the initial data must convene with the contract's storage structure, which is constructed as below:

beginCell()
  .storeUint(BigInt(hexlify(toUtf8Bytes(this.feedId))), consts.DATA_FEED_ID_BS * 8)
  .storeUint(this.signerCountThreshold, SIGNER_COUNT_THRESHOLD_BITS)
  .storeUint(0, consts.DEFAULT_NUM_VALUE_BS * 8)
  .storeUint(0, consts.TIMESTAMP_BS * 8)
  .storeRef(serializeTuple(createTupleItems(this.signers)))
  .endCell();

To define the initial (storage) data for the SingleFeedMan contract, use the predefined class SingleFeedManInitData.ts.

A contract like price_manager, but supporting the single feed only, to omit the communication needs between feed and manager contracts.

get_price

(int, int) get_price(cell payload) method_id;

Similar to get_prices, but omitting the first (data_feed_ids) argument as have it configured during the initialization. Returns also the min timestamp of the passed data packages.

read_price_and_timestamp

(int, int) read_price_and_timestamp() method_id;

Works as the get_price_and_timestamp function.

OP_REDSTONE_WRITE_PRICE

Similar to OP_REDSTONE_WRITE_PRICES, but omitting the first (data_feed_ids) cell ref as have it configured during the initialization.

    int op = in_msg_body~load_uint(OP_NUMBER_BITS);

    if (op == OP_REDSTONE_WRITE_PRICE) {
        cell payload_cell = in_msg_body~load_ref();

        // ...
    }

sample_consumer

A sample consumer for data stored in the price_feed. Works also with single_feed_man. The price_feed to be called needs to be passed.

sample_consumer.fc

initial data

Similar to the price_feed initial data. Due to the architecture of TON contracts, the initial data must convene with the contract's storage structure, which is constructed as below:

beginCell()
  .storeAddress(Address.parse(this.feedAddress))
  .endCell();

To define the initial (storage) data for the Price manager contract, use the predefined class SampleConsumerInitData.ts.

The contract calls the single feed.

OP_REDSTONE_READ_DATA

There is a possibility for fetching the value stored in the contract for a feed_id on-chain directly. There must be invoked an internal message OP_REDSTONE_READ_DATA. The arguments of the message are:

a slice representing the initial_sender of the message, to allow they carried the remaining transaction balance when the returning transaction goes. — a cell ref representing the initial_payload.

    int op = in_msg_body~load_uint(OP_NUMBER_BITS);

    if (op == OP_REDSTONE_READ_DATA) {
        cell initial_payload = in_msg_body~load_ref();

        // ...
    }

The returning message OP_REDSTONE_DATA_READ message is sent to the sender, containing the feed_id, value and the timestamp of the value has saved. The message can be then fetched in the sender and processed or saved in the sender's storage. The initial payload's ref (initial_payload) is added as a ref containing, for example, the first message's sender, to allow they carry the remaining transaction balance.

begin_cell()
  .store_uint(value, MAX_VALUE_SIZE_BITS)
  .store_uint(timestamp, TIMESTAMP_BITS)
  .store_ref(initial_payload)
  .end_cell()

That's an internal message - it consumes gas and modifies the contract's storage, so must be paid by Toncoins.

TON RedStone payload packing

Due to Bag of Cells (BoC) size limitations, the RedStone payload data — represented as a hex string — needs to be passed to a contract in a more complex way.

Having the RedStone payload as defined here, the data should be passed as a Cell built as follows.

The main payload cell consists of:
1. the metadata in the data-level bits consisting of the parts as on the image:
1. a ref containing a udict indexed by consecutive natural numbers (beginning from 0) containing the list of data_package cells.
Each data-package cell consists of:
1. the data package's signature in the data-level bits:
1. one ref to a cell containing the data of the rest of the data package on its data-level:

Current implementation limitations

The RedStone payload must be fetched by explicitly defining data feeds, which leads to one data point belonging to one data package.
The unsigned metadata size must not be exceeding 127 - (2 + 3 + 9) = 113 bytes.

Helper

The createPayloadCell method in the create-payload-cell.ts file checks the limitations and prepares the data to be sent to the contract as described above.

Sample serialization

The image below contains data for 2 feeds times 2 unique signers: Sample payload serialization (2 feeds × 2 signers)

Possible transaction failures

The number of signers recovered from the signatures matched with addresses passed in the initializer must be greater than or equal to the signer_count_threshold in the constructor, for each feed.
- Otherwise, it panics then with the 300 error, increased by the first index of the passed feed which has broken the validation.
The timestamp of data-packages must not be older than 15 minutes in relation to the block_timestamp.
- Otherwise, it panics then with the 200 error, increased by the first index of the payload's data package which has broken the validation, increased additionally by 50 if the package's timestamp is in the future.
The internal messages consume gas and must be paid by Toncoins. The data are available on the contract immediately after the transaction succeeds.
The other error codes are defined here

How RedStone oracles work with TON​

Documentation links​

Smart contracts​

price_manager​

Initial data​

get_prices_v2​

OP_REDSTONE_WRITE_PRICES​

read_prices​

read_timestamp​

price_feed​

OP_REDSTONE_FETCH_DATA​

get_price_and_timestamp​

single_feed_man​

initial data​

get_price​

read_price_and_timestamp​

OP_REDSTONE_WRITE_PRICE​

sample_consumer​

initial data​

OP_REDSTONE_READ_DATA​

TON RedStone payload packing​

Current implementation limitations​

Helper​

Sample serialization​

Possible transaction failures​

See also​

How RedStone oracles work with TON

Documentation links

Smart contracts

price_manager

Initial data

get_prices_v2

OP_REDSTONE_WRITE_PRICES

read_prices

read_timestamp

price_feed

OP_REDSTONE_FETCH_DATA

get_price_and_timestamp

single_feed_man

initial data

get_price

read_price_and_timestamp

OP_REDSTONE_WRITE_PRICE

sample_consumer

initial data

OP_REDSTONE_READ_DATA

TON RedStone payload packing

Current implementation limitations

Helper

Sample serialization

Possible transaction failures

See also