Developers
Consumers
Walkthrough: Using a Topic Inference on-chain

Walkthrough: Using a Topic Inference on-chain

Overview

This guide shows how to use Allora Network inferences in smart contracts:

  1. Query inference data from the Consumer API
  2. Verify the data on-chain with cryptographic signatures
  3. Use verified predictions in your contract logic

Complete Example

Here's the smart contract function you'll implement:

    /**
     * @notice Example for calling a protocol function with topic inference data
     * 
     * @param protocolFunctionArgument An argument for the protocol function
     * @param alloraNetworkInferenceData The signed data from the Allora Consumer
     */
    function callProtocolFunctionWithAlloraTopicInference(
        uint256 protocolFunctionArgument,
        AlloraConsumerNetworkInferenceData calldata alloraNetworkInferenceData
    ) external payable {
        (
            uint256 value,
            uint256[] memory confidenceIntervalPercentiles,
            uint256[] memory confidenceIntervalValues,
        ) = IAlloraConsumer(<Consumer Contract Address>).verifyNetworkInference(alloraNetworkInferenceData);
 
        _protocolFunctionRequiringPredictionValue(
            protocolFunctionArgument, 
            value,
            confidenceIntervalPercentiles,
            confidenceIntervalValues
        );
    }

Step-by-Step Guide

Step 1: Query the API

Call the Consumer Inference API using the asset and timeframe you want to query.

Parameters:

  • asset: The asset you want to query, e.g. BTC, ETH
  • timeframe: The timeframe you want to query, e.g. 5m, 8h

API Request:

 
curl -X 'GET' --url 'https://api.allora.network/v2/allora/consumer/price/ethereum-111551111/ETH/5m' -H 'x-api-key: <apiKey>'

Step 2: Parse the API Response

Example API Response:

{
	"request_id": "b52b7c20-57ae-4852-bdbb-8f39cf317974",
	"status": true,
	"data": {
		"signature": "0x99b8b75f875a9ecc09fc499073656407458d464edeceb384686dba990ed785d841e6510b578d253a6e19a20503d1ec1e3c38b4c60980ff3b4df9ce3335ebd3851b",
		"inference_data": {
			"network_inference": "3365485208027959000000",
			"confidence_interval_percentiles": ["2280000000000000000", "15870000000000000000", "50000000000000000000", "84130000000000000000", "97720000000000000000"],
			"confidence_interval_values": ["2280000000000000000", "15870000000000000000", "50000000000000000000", "84130000000000000000", "97720000000000000000"],
			"topic_id": "9",
			"timestamp": "1719866777",
			"extra_data": "0x"
		}
	}
}

Key fields:

  • signature: Cryptographic signature for on-chain verification
  • network_inference: The main prediction value
  • confidence_interval_percentiles: Statistical confidence levels
  • confidence_interval_values: Prediction bounds for risk assessment
  • topic_id: Identifier for the prediction topic
  • timestamp: When the inference was generated

Step 3: Create the Smart Contract Transaction

Construct a call to the Allora Consumer contract on the chain of your choice (options listed under deployments) using the returned signature and network-inference as follows:

Creating the Transaction

Note you be doing something more like callProtocolFunctionWithAlloraTopicInference in the example above, so you would want to construct your call to that contract in a similar way to the following. You can find the complete example here (opens in a new tab).

TypeScript Implementation:

const alloraConsumer = 
  (new AlloraConsumer__factory())
    .attach(ALLORA_CONSUMER_ADDRESS)
    .connect(senderWallet) as AlloraConsumer
 
const tx = await alloraConsumer.verifyNetworkInference({
  signature: '0x99b8b75f875a9ecc09fc499073656407458d464edeceb384686dba990ed785d841e6510b578d253a6e19a20503d1ec1e3c38b4c60980ff3b4df9ce3335ebd3851b',
    networkInference: {
    topicId: 9,
    timestamp: 1719866777,
    extraData: ethers.toUtf8Bytes(''),
    networkInference: '3365485208027959000000',
    confidenceIntervalPercentiles:['2280000000000000000', '15870000000000000000', '50000000000000000000', '84130000000000000000', '97720000000000000000' ],
    confidenceIntervalValues:[ '3016256807053656000000', '3029849059956295000000', '3049738780726754000000', '3148682039955208400000', '3278333171848616500000' ],
  }, 
  extraData: ethers.toUtf8Bytes(''),
})
 
console.info('tx hash:', tx.hash) 
console.info('Awaiting tx confirmation...')
 
const result = await tx.wait()
 
console.info('tx receipt:', result)

Transaction Flow:

  1. Create consumer contract instance with factory
  2. Connect your wallet for transaction signing
  3. Call verifyNetworkInference with the API response data
  4. Wait for transaction confirmation

Important Notes

Data Format:

  • API uses snake_case, contracts use camelCase for field names
  • Ethers.js requires '0x' for empty extraData, not ''

Field mapping:

  • network_inference → networkInference
  • confidence_interval_percentiles → confidenceIntervalPercentiles
  • confidence_interval_values → confidenceIntervalValues

Source Code

Next Steps

Consumer contract development | Deploy consumer contracts | Alternative data access

Existing ConsumersOverview