Oracles
This page is also Markdown, for agents: /intear-dex/guides/oracles.md, and /llms.txt lists every page.
Some DEXs need data from outside NEAR for a swap, like the current prices of their assets. They get it from an oracle: a service that watches for requests and responds to them with a transaction. Qoq’s NEAR/USDC pool, for example, prices its assets with what an oracle reads from several exchanges.
Anyone can run an oracle, and each DEX decides which oracles it trusts. The engine carries the requests and the responses, holds the assets until the oracle responds, and pays the oracle its fee.
Asking an oracle
Section titled “Asking an oracle”A swap on a DEX that needs an oracle starts with an OracleRequest operation, in execute_operations or in a deposit message. It must be the first operation, and there can only be one. This asks Qoq’s oracle for the prices of NEAR and USDC, then swaps 1 NEAR for USDC on Qoq:
[ { "OracleRequest": { "oracle_key": "ed25519:7EK1MhudQrXZBZjvnvvcNXiQ2ByYBkXg8rUhbKL69CGo", "dex_id": "slimedragon.near/amp", "request": "AgAAAAABQAAAADE3MjA4NjI4Zjg0ZjVkNmFkMzNmMGRhM2JiYmViMjdmZmNiMzk4ZWFjNTAxYTMxYmQ2YWQyMDExZTM2MTMzYTE=", "fee": ["near", "400000000000000000000"], "swap": null } }, { "SwapSimple": { "dex_id": "slimedragon.near/amp", "message": "AQAAAEBCDwABAAAAAAAAAA==", "asset_in": "near", "asset_out": "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1", "amount": { "Amount": { "ExactIn": "1000000000000000000000000" } }, "constraint": "2800000" } }]| Field | Description |
|---|---|
oracle_key |
The oracle to ask, one that the DEX trusts. Qoq’s pools name theirs |
dex_id |
The DEX that reads the response. Only it can |
request |
What to ask, in the DEX’s format, at most 1024 bytes. Here it’s Qoq’s request for the prices of NEAR and USDC |
fee |
An asset the oracle takes fees in, and its fee in it, exactly as oracle_fees returns it. Any other amount fails with The fee of oracle <oracle key> is <fee> <asset>, not <amount> |
swap |
Optional. A swap that buys the fee first, see below |
With execute_operations, the fee comes from your inner balance. In a deposit, it comes from the deposit, which must then be of the fee’s asset. To pay it with another asset, swap buys exactly the fee with asset_in, before the request. It pays no referral fees, and constraint is the most it can take of asset_in. This one pays an oracle that takes NEAR with USDC, through Plach’s NEAR/USDC pool:
"swap": { "dex_id": "slimedragon.near/xyk", "message": "AQAAAEBCDwABAAAAVQAAAA==", "asset_in": "nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1", "constraint": "10000"}Referral fees go to the first swap after the request, not to this one.
Waiting for the response
Section titled “Waiting for the response”The engine takes the fee, logs an oracle_request event with a random nonce, and the operations after the request wait. When the oracle responds, they run in a later receipt, where the DEX reads the response. The transaction ends after that, so wallets and the near CLI wait for it. If the oracle doesn’t respond within 200 blocks, about 2 minutes, the request times out.
The engine keeps 30 Tgas of the call’s gas for what it does after the operations, 50 Tgas when a swap buys the fee in a deposit, and the operations get the rest, so attach enough gas for them, like 300 Tgas, the most a transaction can have.
If the operations don’t run
Section titled “If the operations don’t run”Operations after a request fail on their own, in their receipt, and what happens then depends on whether the oracle responded:
| The oracle responded, and the operations failed | The oracle didn’t respond in time | |
|---|---|---|
| The oracle’s fee | Paid to the oracle | Back to your inner balance, or to the sender of a deposit |
execute_operations |
The transaction fails with Operations after the oracle request failed |
The transaction fails with Oracle didn't respond in time |
| A deposit | Withdrawn back to the sender | Withdrawn back to the sender, and the fee too, in its asset |
The operations also fail if the engine is paused when the oracle responds.
A token contract sees a deposit with an oracle request as used up: ft_on_transfer returns "0", even when the engine sends the deposit back later. So don’t read the result of ft_transfer_call to learn whether the swap went through: look for the swap event, or the withdraw of the refund. If that withdrawal fails, the assets go to the sender’s inner balance, if the asset is registered for them, and are lost otherwise. So register the assets you deposit with an oracle request.
Quoting
Section titled “Quoting”simulate_swap_simple can’t wait for an oracle, so it takes the response as an argument: oracle_response, with the oracle_key, the request and the response. The DEX reads it as if the oracle had responded with it, so the quote is only as good as the response you pass. To quote swaps on Qoq, use the DEX Aggregator, which has its oracle’s latest prices, or see Quoting to pass prices yourself.
Running an oracle
Section titled “Running an oracle”An oracle’s key is a gas key on the engine’s account, dex.intear.near: a key with its own balance, which pays for the gas of its transactions, and which can only call oracle_respond and remove_oracle_key. The oracle signs its responses with it, as dex.intear.near. The key has 4 nonces, so the oracle can send 4 responses at once, one per nonce index.
The near CLI examples below run an oracle as bob.near, from the start to the end. Together they’re one script. First, bob.near needs a storage balance, which pays for the records of the oracle, and NEAR registered, to get fees in it:
# bob.near gets the oracle's fees, in NEAR, and its storage balance pays for the# records of the oraclenear contract call-function as-transaction dex.intear.near storage_deposit \ json-args '{}' \ prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \ sign-as bob.near network-config mainnet sign-with-keychain send
near contract call-function as-transaction dex.intear.near register_assets \ json-args '{"asset_ids": ["near"]}' \ prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \ sign-as bob.near network-config mainnet sign-with-keychain sendAdd the key
Section titled “Add the key”create_oracle_key must be signed with the oracle’s key, as a full access key of the account that calls it, which becomes the oracle’s fee receiver. That way, only whoever has the key can name its fee receiver. Add the key to the account, call create_oracle_key with it, and delete it from the account again:
# create_oracle_key is signed with the oracle's key, as a full access key of the# account that gets the oracle's feesnear account add-key bob.near grant-full-access \ use-manually-provided-public-key "$ORACLE_PUBLIC_KEY" \ network-config mainnet sign-with-keychain send
near contract call-function as-transaction dex.intear.near create_oracle_key \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ prepaid-gas '50.0 Tgas' attached-deposit '0.5 NEAR' \ sign-as bob.near network-config mainnet \ sign-with-plaintext-private-key "$ORACLE_PRIVATE_KEY" send
# bob.near doesn't need the key anymorenear account delete-keys bob.near public-keys "$ORACLE_PUBLIC_KEY" \ network-config mainnet sign-with-keychain sendThe deposit pays for the storage of the key, about 0.005 NEAR for an Ed25519 key, and the rest is the key’s gas balance. With less than the storage attached, it fails with Attach at least <amount> for the storage of the key.
Set the fees
Section titled “Set the fees”set_oracle_fees sets what the oracle takes for a request in each asset, and replaces all of its fees. Only the fee receiver can call it, with 1 yoctoNEAR, and it must have each asset registered. A request must pay one of these fees exactly, and it’s paid to the fee receiver’s inner balance when the oracle responds.
near contract call-function as-transaction dex.intear.near set_oracle_fees \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{ "oracle_key": $oracle_key, "fees": {"near": "400000000000000000000"} }')" \ prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \ sign-as bob.near network-config mainnet sign-with-keychain sendoracle_fee_receiver and oracle_fees read them back:
near contract call-function as-read-only dex.intear.near oracle_fee_receiver \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ network-config mainnet now
near contract call-function as-read-only dex.intear.near oracle_fees \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ network-config mainnet nowTop up the gas balance
Section titled “Top up the gas balance”Each response spends gas from the key’s balance. Anyone can add to it:
near contract call-function as-transaction dex.intear.near top_up_oracle_key \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ prepaid-gas '30.0 Tgas' attached-deposit '0.1 NEAR' \ sign-as bob.near network-config mainnet sign-with-keychain sendRespond
Section titled “Respond”An oracle watches for oracle_request events with its key, and responds with oracle_respond:
request_hash: the SHA-256 of the request’s bytes, in base58,response: the response, in the DEX’s format, at most 1024 bytes,nonces: thenonceof each event it responds to. One response can answer every request that asked the same.
It’s signed with the oracle’s key, as dex.intear.near, with a nonce index from 0 to 3. The engine doesn’t check the response: the DEX does, when it reads it.
# The request and the nonce of an oracle_request event: Qoq asking for the# prices of NEAR and USDC. Nothing waits with this nonce here, so the response# is skipped.REQUEST=AgAAAAABQAAAADE3MjA4NjI4Zjg0ZjVkNmFkMzNmMGRhM2JiYmViMjdmZmNiMzk4ZWFjNTAxYTMxYmQ2YWQyMDExZTM2MTMzYTE=NONCE=B84yAz7+ggEbxNz71+p6+pKtGeY92vCI77oM2B8/+8o=# The SHA-256 of the request, in base58REQUEST_HASH=zd8Fk7yMefYFa5FgU4cQ7HBwXgwFPiH4gcxRx5h7n75# The prices of NEAR and USDC on 3 exchanges, in the format Qoq readsRESPONSE=AwAAAAcAAABiaW5hbmNlAgAAAAAAopii3j4oAAAAAAAAAAAAAGSns7bgDQAAAAAAAAAAAwAAAG9reAIAAAAAgGg9IWxCKAAAAAAAAAAAAABkp7O24A0AAAAAAAAAAAUAAABieWJpdAIAAAAAgNvzI1E7KAAAAAAAAAAAAABkp7O24A0AAAAAAAAAAA==
near contract call-function as-transaction dex.intear.near oracle_respond \ json-args "$(jq -n --arg request_hash "$REQUEST_HASH" --arg response "$RESPONSE" --arg nonce "$NONCE" '{ "request_hash": $request_hash, "response": $response, "nonces": [$nonce] }')" \ prepaid-gas '30.0 Tgas' attached-deposit '0 NEAR' \ sign-as dex.intear.near network-config mainnet \ sign-with-plaintext-private-key --nonce-index 0 "$ORACLE_PRIVATE_KEY" sendA nonce that no operations wait with, like the one here, is skipped.
Remove the key
Section titled “Remove the key”remove_oracle_key, signed with the oracle’s key, deletes it with its fee receiver and fees, and sends the NEAR that paid for its storage to receiver_id. What’s left of the gas balance is burned, and removing a key with more than 1 NEAR left fails, so let it run low first.
# Burns what's left of the key's gas balance, and sends the NEAR that paid for# the key's storage to bob.nearnear contract call-function as-transaction dex.intear.near remove_oracle_key \ json-args '{"receiver_id": "bob.near"}' \ prepaid-gas '30.0 Tgas' attached-deposit '0 NEAR' \ sign-as dex.intear.near network-config mainnet \ sign-with-plaintext-private-key --nonce-index 0 "$ORACLE_PRIVATE_KEY" sendFor DEXs
Section titled “For DEXs”A DEX reads the response with the oracle_request(oracle_key, request) host function. It returns the response only after an OracleRequest of this DEX with the same key and request bytes, or in a simulation with them in oracle_response, and nothing otherwise. The DEX decides which keys it trusts, and what to do without a response, such as failing the swap. See What a DEX sees, and test-dex for a DEX that swaps at a rate an oracle responds with.
The whole script
Section titled “The whole script”#!/usr/bin/env bash# Runs an oracle as bob.near: adds its key to the engine, sets its fees, tops up# the key's gas balance, responds to a request and removes the key. bob.near has# never used Intear DEX.set -euo pipefail
# A key pair made for the oracle only. The oracle signs its responses with it.ORACLE_PUBLIC_KEY=ed25519:4g4goejHzzdqFXRXj6MW1ZrEj3XiLcfAxoqNcnt4HSx5ORACLE_PRIVATE_KEY=ed25519:4UcCHYsnYgtLDoPb1rRsupwhSwRJtTgcjiFZetywd22uyA95drABko7sCaP3iKaEKAURrkJXDM2DAYFfiWHpDEz1
# bob.near gets the oracle's fees, in NEAR, and its storage balance pays for the# records of the oraclenear contract call-function as-transaction dex.intear.near storage_deposit \ json-args '{}' \ prepaid-gas '30.0 Tgas' attached-deposit '0.01 NEAR' \ sign-as bob.near network-config mainnet sign-with-keychain send
near contract call-function as-transaction dex.intear.near register_assets \ json-args '{"asset_ids": ["near"]}' \ prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \ sign-as bob.near network-config mainnet sign-with-keychain send
# create_oracle_key is signed with the oracle's key, as a full access key of the# account that gets the oracle's feesnear account add-key bob.near grant-full-access \ use-manually-provided-public-key "$ORACLE_PUBLIC_KEY" \ network-config mainnet sign-with-keychain send
near contract call-function as-transaction dex.intear.near create_oracle_key \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ prepaid-gas '50.0 Tgas' attached-deposit '0.5 NEAR' \ sign-as bob.near network-config mainnet \ sign-with-plaintext-private-key "$ORACLE_PRIVATE_KEY" send
# bob.near doesn't need the key anymorenear account delete-keys bob.near public-keys "$ORACLE_PUBLIC_KEY" \ network-config mainnet sign-with-keychain send
near contract call-function as-transaction dex.intear.near set_oracle_fees \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{ "oracle_key": $oracle_key, "fees": {"near": "400000000000000000000"} }')" \ prepaid-gas '30.0 Tgas' attached-deposit '1 yoctoNEAR' \ sign-as bob.near network-config mainnet sign-with-keychain send
near contract call-function as-read-only dex.intear.near oracle_fee_receiver \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ network-config mainnet now
near contract call-function as-read-only dex.intear.near oracle_fees \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ network-config mainnet now
near contract call-function as-transaction dex.intear.near top_up_oracle_key \ json-args "$(jq -n --arg oracle_key "$ORACLE_PUBLIC_KEY" '{"oracle_key": $oracle_key}')" \ prepaid-gas '30.0 Tgas' attached-deposit '0.1 NEAR' \ sign-as bob.near network-config mainnet sign-with-keychain send
# The request and the nonce of an oracle_request event: Qoq asking for the# prices of NEAR and USDC. Nothing waits with this nonce here, so the response# is skipped.REQUEST=AgAAAAABQAAAADE3MjA4NjI4Zjg0ZjVkNmFkMzNmMGRhM2JiYmViMjdmZmNiMzk4ZWFjNTAxYTMxYmQ2YWQyMDExZTM2MTMzYTE=NONCE=B84yAz7+ggEbxNz71+p6+pKtGeY92vCI77oM2B8/+8o=# The SHA-256 of the request, in base58REQUEST_HASH=zd8Fk7yMefYFa5FgU4cQ7HBwXgwFPiH4gcxRx5h7n75# The prices of NEAR and USDC on 3 exchanges, in the format Qoq readsRESPONSE=AwAAAAcAAABiaW5hbmNlAgAAAAAAopii3j4oAAAAAAAAAAAAAGSns7bgDQAAAAAAAAAAAwAAAG9reAIAAAAAgGg9IWxCKAAAAAAAAAAAAABkp7O24A0AAAAAAAAAAAUAAABieWJpdAIAAAAAgNvzI1E7KAAAAAAAAAAAAABkp7O24A0AAAAAAAAAAA==
near contract call-function as-transaction dex.intear.near oracle_respond \ json-args "$(jq -n --arg request_hash "$REQUEST_HASH" --arg response "$RESPONSE" --arg nonce "$NONCE" '{ "request_hash": $request_hash, "response": $response, "nonces": [$nonce] }')" \ prepaid-gas '30.0 Tgas' attached-deposit '0 NEAR' \ sign-as dex.intear.near network-config mainnet \ sign-with-plaintext-private-key --nonce-index 0 "$ORACLE_PRIVATE_KEY" send
# Burns what's left of the key's gas balance, and sends the NEAR that paid for# the key's storage to bob.nearnear contract call-function as-transaction dex.intear.near remove_oracle_key \ json-args '{"receiver_id": "bob.near"}' \ prepaid-gas '30.0 Tgas' attached-deposit '0 NEAR' \ sign-as dex.intear.near network-config mainnet \ sign-with-plaintext-private-key --nonce-index 0 "$ORACLE_PRIVATE_KEY" send