Oracles (#316)

* First draft of a very simple topic on oracles

* some links

docs/smart-contracts/entrypoints.md

@@ -34,7 +34,7 @@ An entrypoint may run logic based on:
 <!-- TODO link to Tezos library for address of caller/globals and table of contents -->
 
 Entrypoints cannot access information outside of Tezos, such as calling external APIs.
-If an entrypoint needs information from outside Tezos it must use oracles; see [Using and trusting Oracles](https://opentezos.com/smart-contracts/oracles/) on opentezos.com.
+If an entrypoint needs information from outside Tezos it must use oracles; see [Oracles](./oracles) and [Using and trusting Oracles](https://opentezos.com/smart-contracts/oracles/) on opentezos.com.
 
 The only effects that an entrypoint can have are changes to its storage and new operations that are run after the entrypoint completes.
 An entrypoint can call other entrypoints in its contract or entrypoints in other contracts.

docs/smart-contracts/oracles.md

@@ -0,0 +1,26 @@
+---
+title: Oracles
+authors: 'Tim McMackin'
+last_update:
+  date: 9 February 2024
+---
+
+Oracles provide data to smart contracts that they wouldn't be able to access otherwise.
+Because smart contracts can't access data from outside the blockchain, including calling external APIs, you can use oracles to provide the data.
+
+At a basic level, oracles have two parts:
+
+- The off-chain part provides external data to the on-chain part via ordinary smart contract transactions
+- The on-chain part stores the data on the chain and provides it to consumer smart contracts
+
+How the oracle works is up to the designer.
+Generally speaking, oracles allow smart contracts to call them for information and charge a fee or subscription in exchange.
+
+An example of an oracle is [Harbinger](https://github.com/tacoinfra/harbinger), which provides information about currency exchange rates.
+
+## Trusting oracles
+
+The difficult part of setting up oracles is ensuring that the data they provide is accurate and authoritative so it can be trusted.
+For example, oracles can average multiple sources of data like currency prices to prevent manipulation of the data and ensure that it does not rely on a single source.
+They can use encryption to sign data and prove that it it authoritative.
+For ways to set up oracles to be trustable, see [Using and trusting oracles](https://opentezos.com/smart-contracts/oracles) on opentezos.com.

docs/tutorials/security/part-3.md

@@ -42,7 +42,7 @@ For an example of upgrading smart contracts with lambdas and proxies, see [Creat
 
 Blockchain oracles are third-party services that provide smart contracts with external information. They serve as bridges between blockchains and the outside world, allowing smart contracts to access off-chain data. Oracles verify, query, and authenticate external data sources, and transmit any valuable data.
 
-An Oracle is made of two parts:
+An [Oracle](../../smart-contracts/oracles) is made of two parts:
 
 - Off-chain: The data collector that pushes data to the on-chain contract
 - On-chain: The contract that stores the data and exposes it to other contracts. Generally, a call for information involves monetization and so, some fees apply.

sidebars.js

@@ -168,6 +168,7 @@ const sidebars = {
         'smart-contracts/views',
         'smart-contracts/events',
         'smart-contracts/delegation',
+        'smart-contracts/oracles',
         // 'smart-contracts/multisig-specialized',
         // 'smart-contracts/multisig-usage',
       ],