> For the complete documentation index, see [llms.txt](https://docs.aeternity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aeternity.com/developer-documentation/protocol/oracles/oracle_transactions.md). # Oracle transactions Oracle transactions are of four types: * Register * Extend * Query * Response ## Oracle register transaction An oracle operator can register an existing account as an oracle. The transaction contains: * The address that should be registered as an oracle (oracle\_owner) + nonce * Query format definition * Response format definition * Query fee (that should be paid for posting a query to the oracle). * A TTL (relative in number of blocks, or absolute block height) * Vm version (see [VM description](/developer-documentation/protocol/contracts/contract_vms.md)). * Transaction fee. See the [serialization specification](https://github.com/aeternity/docs/blob/master/serializations.md#oracle-register-transaction). ### TODO * In the future we could imagine an oracle register transaction that\ creates a new account by double signing the request with the source\ account and the new account. ## Oracle extend transaction An oracle operator can extend the TTL of an existing oracle. The transaction contains: * The address/oracle that should be extended (and a nonce) * An extension to the TTL (relative to current expiry in number of blocks) * Transaction fee. See the [serialization specification](https://github.com/aeternity/docs/blob/master/serializations.md#oracle-extend-transaction). ## Oracle query transaction * Contains: * The sender (address) + nonce * The oracle (address) * The query in binary format * The query fee - locked up until either: * The oracle answers and receive the fee * The TTL expire and the sender gets a refund * Query TTL * Response TTL * The transaction fee. The transaction creates an oracle interaction object in the oracle\ state tree. The id of this object is constructed from the query\ transaction as the hash of {sender\_address, nonce, oracle\_address} The query TTL decides how long the query is open for response from the\ oracle. The query TTL can be either absolute (in block height) or relative\ (also in block height) to the block the query was included in. The response TTL decides how long the response is available when given\ from the oracle. The response TTL is always relative. This is to not\ give incentive to the oracle to post the answer late, since the oracle\ is paying the fee for the response. See the [serialization specification](https://github.com/aeternity/docs/blob/master/serializations.md#oracle-query-transaction). ### Questions/Later * We could include an earliest time that the oracle can answer to\ protect against malicious oracles answering early and collect the fee. ## Oracle response The oracle operator responds to a query by posting an oracle response\ transaction, signing it with the oracle account's private key. The response transaction is invalid if the TTL from the query has\ expired. The oracle pays the fee of the response transaction. The minimum fee\ is determined by the response TTL from the query and the size of the\ response. Note that there is an incentive to keep the response precise (and\ small) since the oracle pays for the response transaction. The transaction contains: * The oracle (address) + nonce * The oracle interaction ID (derived from the query) * The response in binary format * Response TTL (redundant, but makes the transaction self contained) * The transaction fee. See the [serialization specification](https://github.com/aeternity/docs/blob/master/serializations.md#oracle-response-transaction). ### Questions/Later * Should we have an automatic callback defined in the query? * Any callback is paid by the oracle. * Should we be able to return parts of the fee if the oracle for some\ reason could not provide an answer. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.aeternity.com/developer-documentation/protocol/oracles/oracle_transactions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.