Skip to content

Oracles

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.

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.

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.

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.

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.

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 oracle
near 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 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 fees
near 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 anymore
near account delete-keys bob.near public-keys "$ORACLE_PUBLIC_KEY" \
network-config mainnet sign-with-keychain send

The 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_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 send

oracle_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 now

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 send

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: the nonce of 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 base58
REQUEST_HASH=zd8Fk7yMefYFa5FgU4cQ7HBwXgwFPiH4gcxRx5h7n75
# The prices of NEAR and USDC on 3 exchanges, in the format Qoq reads
RESPONSE=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

A nonce that no operations wait with, like the one here, is skipped.

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.near
near 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

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.

#!/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:4g4goejHzzdqFXRXj6MW1ZrEj3XiLcfAxoqNcnt4HSx5
ORACLE_PRIVATE_KEY=ed25519:4UcCHYsnYgtLDoPb1rRsupwhSwRJtTgcjiFZetywd22uyA95drABko7sCaP3iKaEKAURrkJXDM2DAYFfiWHpDEz1
# bob.near gets the oracle's fees, in NEAR, and its storage balance pays for the
# records of the oracle
near 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 fees
near 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 anymore
near 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 base58
REQUEST_HASH=zd8Fk7yMefYFa5FgU4cQ7HBwXgwFPiH4gcxRx5h7n75
# The prices of NEAR and USDC on 3 exchanges, in the format Qoq reads
RESPONSE=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.near
near 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