From 60f89bd2c12c755235d3c8e7807b3b46bed652b0 Mon Sep 17 00:00:00 2001 From: MedovTimur Date: Mon, 13 Jan 2025 14:33:38 +0300 Subject: [PATCH 1/3] Updating oracle --- .../Infra/oracle/dia-randomness-oracle.md | 87 +++++++++++-------- docs/examples/Infra/oracle/oracle.md | 59 ++++++++----- 2 files changed, 88 insertions(+), 58 deletions(-) diff --git a/docs/examples/Infra/oracle/dia-randomness-oracle.md b/docs/examples/Infra/oracle/dia-randomness-oracle.md index 4bdb253..2bfb1dd 100644 --- a/docs/examples/Infra/oracle/dia-randomness-oracle.md +++ b/docs/examples/Infra/oracle/dia-randomness-oracle.md @@ -11,17 +11,14 @@ Randomness in blockchains is crucial for a fair and unpredictable distribution o However, there are distributed systems that try to solve the problem of "predictability" of randomness, one of which is [drand](https://drand.love/). -The given dia-oracle implementation is an example of safe randomization. +The given dia-oracle implementation is an example of safe randomization. The source code, developed using the [Sails](../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle/randomness). + ## State -```rust -/// Used to represent high and low parts of an unsigned 256-bit integer. -pub type RandomSeed = (u128, u128); -``` +The `Random` structure stores a random value, its cryptographic signature, and the signature of the previous value, ensuring integrity and traceability. -```rust -#[derive(Debug, Clone, Encode, Decode, TypeInfo)] +```rust title="oracle/randomness/app/src/lib.rs" pub struct Random { pub randomness: RandomSeed, pub signature: String, @@ -29,11 +26,12 @@ pub struct Random { } ``` -```rust -#[derive(Debug, Default, Clone, Encode, Decode, TypeInfo)] +The `RandomnessOracle` structure maintains the overall oracle state, tracking ownership, stored random values, the last updated round, and the manager responsible for updates. + +```rust title="oracle/randomness/app/src/lib.rs" pub struct RandomnessOracle { pub owner: ActorId, - pub values: BTreeMap, + pub values: HashMap, pub last_round: u128, pub manager: ActorId, } @@ -41,45 +39,58 @@ pub struct RandomnessOracle { ## Actions -```rust -#[derive(Debug, Encode, Decode, TypeInfo)] -pub enum Action { - SetRandomValue { round: u128, value: state::Random }, - GetLastRoundWithRandomValue, - UpdateManager(ActorId), -} +```rust title="oracle/randomness/app/src/lib.rs" + pub fn set_random_value(&mut self, round: u128, value: Random); + pub fn get_last_round_with_random_value(&mut self) -> (u128, u128); + pub fn update_manager(&mut self, new_manager: ActorId); +``` +- The `set_random_value` method securely assigns a new random value to a specific round, ensuring sequential updates. +- The `get_last_round_with_random_value` method retrieves the most recent round and its associated random value. +- The `update_manager` method changes the manager, allowing controlled delegation of responsibility. + +```rust title="oracle/randomness/app/src/lib.rs" + pub fn get_owner(&self) -> ActorId; + pub fn get_last_round(&self) -> u128; + pub fn get_manager(&self) -> ActorId; + pub fn get_values(&self) -> Vec<(u128, Random)>; ``` +Methods like `get_owner`, `get_last_round`, `get_manager`, and `get_values` provide convenient access to the oracle's current state. + ## Events -```rust -#[derive(Debug, Encode, Decode, TypeInfo)] -pub enum Event { - NewManager(ActorId), - NewRandomValue { - round: u128, - value: state::Random, - }, - LastRoundWithRandomValue { - round: u128, - random_value: state::RandomSeed, - }, -} +The `Event` enum defines key events: updating the manager, adding a new random value, and retrieving the last round's random value, ensuring clear system behavior tracking. + +```rust title="oracle/randomness/app/src/lib.rs" + + pub enum Event { + NewManager(ActorId), + NewRandomValue { round: u128, value: Random }, + LastRoundWithRandomValue { round: u128, random_value: u128 }, + } ``` -## Init Configuration +## Initialisation + +The `init` method initializes the oracle with the given manager and sets up its default state, defining ownership and control. ```rust -#[derive(Debug, Encode, Decode, TypeInfo)] -pub struct InitConfig { - pub manager: ActorId, -} + pub async fn init(manager: ActorId) -> Self { + unsafe { + RANDOMNESS_ORACLE = Some(RandomnessOracle { + owner: msg::source(), + manager, + ..Default::default() + }); + } + Self(()) + } ``` ## Conclusion -The source code of this example of a Dia Randomness Oracle program is available on GitHub: [oracle/randomness/src/lib.rs](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness/src/lib.rs). +The source code of this example of a Dia Randomness Oracle program is available on GitHub: [oracle/randomness/](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness). -See also an example of the program testing implementation based on `gtest`: [oracle/tests/oracle_randomness.rs](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/tests/oracle_randomness.rs). +See also an example of the program testing implementation based on `gtest`: [oracle/randomness/tests/gtest.rs](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness/tests/gtest.rs). -For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing). \ No newline at end of file +For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing). diff --git a/docs/examples/Infra/oracle/oracle.md b/docs/examples/Infra/oracle/oracle.md index 4f9a347..af7fa9e 100644 --- a/docs/examples/Infra/oracle/oracle.md +++ b/docs/examples/Infra/oracle/oracle.md @@ -16,44 +16,63 @@ These programs can obtain external data which can't exist in blockchain space. I Moreover, oracles allow the creation of lending/DEX protocols, which form an important part of DeFi. -This article provides an example of the native implementation of a randomness oracle, which provides the ability to use random numbers in programs. It can be used as is or modified to suit specific scenarios. Anyone can easily create their own oracle and run it on the Vara Network. The source code is available on [GitHub](https://github.com/gear-foundation/dapps-oracle). +This article provides an example of the native implementation of a randomness oracle, which provides the ability to use random numbers in programs. It can be used as is or modified to suit specific scenarios. Anyone can easily create their own oracle and run it on the Vara Network. + +The source code, developed using the [Sails](../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). ## Storage Structure -```rust -#[derive(Debug, Default)] -pub struct RandomnessOracle { - pub owner: ActorId, - pub values: BTreeMap, - pub last_round: u128, - pub manager: ActorId, +The `Oracle` structure defines the storage for the program, including the owner, the manager responsible for operations, and optional [dDNS](../dein.md) information. + +```rust title="oracle/app/src/lib.rs" +pub struct Oracle { + owner: ActorId, + manager: ActorId, + dns_info: Option<(ActorId, String)>, } ``` -### `Action` and `Event` +### `Action` -`Event` is generated when `Action` is triggered. The `Action` enum wraps various `Input` structs, and `Event` wraps `Reply`. +The oracle exposes methods to interact with its state and fetch randomness values from the designated manager. -```rust -#[derive(Debug, Encode, Decode, TypeInfo)] -pub enum Action { - RequestValue, - ChangeManager(ActorId), -} +```rust title="oracle/app/src/lib.rs" +pub async fn request_value(&mut self) -> u128; +pub fn change_manager(&mut self, new_manager: ActorId); +``` +- `request_value`: Asynchronously retrieves the latest random value from the manager and emits a `NewValue` event. +- `change_manager`: Updates the manager responsible for providing randomness values, ensuring operational flexibility. + +The oracle also provides accessors to retrieve its internal state: + +```rust title="oracle/app/src/lib.rs" + pub fn get_owner(&self) -> ActorId; + pub fn get_manager(&self) -> ActorId; + pub fn get_dns_info(&self) -> Option<(ActorId, String)>; ``` +- `get_owner`: Returns the oracle owner's ActorId. +- `get_manager`: Returns the current manager's ActorId. +- `get_dns_info`: Retrieves the DNS integration details. + + +### `Event` + +The `Event` enum captures significant actions within the oracle, enabling better system monitoring and interaction. -```rust +```rust title="oracle/app/src/lib.rs" #[derive(Debug, Encode, Decode, TypeInfo)] pub enum Event { NewValue { value: u128 }, NewManager(ActorId), } ``` +- `NewValue`: Emitted when a new random value is fetched and stored. +- `NewManager`: Triggered when the manager is changed, indicating a shift in operational responsibility. ## Conclusion -The source code of this example of a Vara Oracle program is available on GitHub: [oracle/oracle/src/contract.rs](https://github.com/gear-foundation/dapps-oracle/blob/wip/oracle/src/contract.rs). +The source code of this example of a Vara Oracle program is available on GitHub: (https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). -See also an example of the program testing implementation based on `gtest` and `gclient`: [oracle/oracle/tests](https://github.com/gear-foundation/dapps-oracle/tree/wip/oracle/tests). +See also an example of the program testing implementation based on `gtest`: [oracle/tests](https://github.com/gear-foundation/dapps-oracle/tree/wip/oracle/tests). -For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing). \ No newline at end of file +For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing). From 8360b8b88ae79c14ae28e4edf05c1ca6409c6f57 Mon Sep 17 00:00:00 2001 From: MedovTimur Date: Mon, 13 Jan 2025 15:48:27 +0300 Subject: [PATCH 2/3] fix link --- docs/examples/Infra/oracle/dia-randomness-oracle.md | 2 +- docs/examples/Infra/oracle/oracle.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/examples/Infra/oracle/dia-randomness-oracle.md b/docs/examples/Infra/oracle/dia-randomness-oracle.md index 2bfb1dd..1237abc 100644 --- a/docs/examples/Infra/oracle/dia-randomness-oracle.md +++ b/docs/examples/Infra/oracle/dia-randomness-oracle.md @@ -11,7 +11,7 @@ Randomness in blockchains is crucial for a fair and unpredictable distribution o However, there are distributed systems that try to solve the problem of "predictability" of randomness, one of which is [drand](https://drand.love/). -The given dia-oracle implementation is an example of safe randomization. The source code, developed using the [Sails](../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle/randomness). +The given dia-oracle implementation is an example of safe randomization. The source code, developed using the [Sails](../../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle/randomness). ## State diff --git a/docs/examples/Infra/oracle/oracle.md b/docs/examples/Infra/oracle/oracle.md index af7fa9e..48f8a50 100644 --- a/docs/examples/Infra/oracle/oracle.md +++ b/docs/examples/Infra/oracle/oracle.md @@ -18,7 +18,7 @@ Moreover, oracles allow the creation of lending/DEX protocols, which form an imp This article provides an example of the native implementation of a randomness oracle, which provides the ability to use random numbers in programs. It can be used as is or modified to suit specific scenarios. Anyone can easily create their own oracle and run it on the Vara Network. -The source code, developed using the [Sails](../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). +The source code, developed using the [Sails](../../../build/sails/sails.mdx) framework, is available on [GitHub](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). ## Storage Structure From b0e2fb33d33907baf12f712e2d58619a63aadf8f Mon Sep 17 00:00:00 2001 From: MedovTimur Date: Thu, 16 Jan 2025 12:13:19 +0300 Subject: [PATCH 3/3] typo correction --- docs/examples/Infra/oracle/dia-randomness-oracle.md | 6 +++--- docs/examples/Infra/oracle/oracle.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/examples/Infra/oracle/dia-randomness-oracle.md b/docs/examples/Infra/oracle/dia-randomness-oracle.md index 1237abc..229f67a 100644 --- a/docs/examples/Infra/oracle/dia-randomness-oracle.md +++ b/docs/examples/Infra/oracle/dia-randomness-oracle.md @@ -74,7 +74,7 @@ The `Event` enum defines key events: updating the manager, adding a new random v The `init` method initializes the oracle with the given manager and sets up its default state, defining ownership and control. -```rust +```rust title="oracle/randomness/app/src/lib.rs" pub async fn init(manager: ActorId) -> Self { unsafe { RANDOMNESS_ORACLE = Some(RandomnessOracle { @@ -89,8 +89,8 @@ The `init` method initializes the oracle with the given manager and sets up its ## Conclusion -The source code of this example of a Dia Randomness Oracle program is available on GitHub: [oracle/randomness/](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness). +The source code of this example of a Dia Randomness Oracle program is available on GitHub: [gear-foundation/dapps/contracts/oracle/randomness](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness). -See also an example of the program testing implementation based on `gtest`: [oracle/randomness/tests/gtest.rs](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness/tests/gtest.rs). +See also an example of the program testing implementation based on `gtest`: [gear-foundation/dapps/contracts/oracle/randomness/tests/gtest.rs](https://github.com/gear-foundation/dapps/blob/master/contracts/oracle/randomness/tests/gtest.rs). For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing). diff --git a/docs/examples/Infra/oracle/oracle.md b/docs/examples/Infra/oracle/oracle.md index 48f8a50..46e1043 100644 --- a/docs/examples/Infra/oracle/oracle.md +++ b/docs/examples/Infra/oracle/oracle.md @@ -71,8 +71,8 @@ pub enum Event { ## Conclusion -The source code of this example of a Vara Oracle program is available on GitHub: (https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). +The source code of this example of a Vara Oracle program is available on GitHub: [gear-foundation/dapps/contracts/oracle](https://github.com/gear-foundation/dapps/tree/master/contracts/oracle). -See also an example of the program testing implementation based on `gtest`: [oracle/tests](https://github.com/gear-foundation/dapps-oracle/tree/wip/oracle/tests). +See also an example of the program testing implementation based on `gtest`: [gear-foundation/dapps/contracts/oracle](https://github.com/gear-foundation/dapps-oracle/tree/wip/oracle/tests). For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing).