Updating oracle

docs/examples/Infra/oracle/dia-randomness-oracle.md

@@ -11,75 +11,86 @@ 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,
     pub prev_signature: String,
 }
 ```
 
-```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<u128, Random>,
+    pub values: HashMap<u128, Random>,
     pub last_round: u128,
     pub manager: ActorId,
 }
 ```
 
 ## 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.
 
-## Init Configuration
+```rust title="oracle/randomness/app/src/lib.rs"
 
-```rust
-#[derive(Debug, Encode, Decode, TypeInfo)]
-pub struct InitConfig {
-    pub manager: ActorId,
-}
+    pub enum Event {
+        NewManager(ActorId),
+        NewRandomValue { round: u128, value: Random },
+        LastRoundWithRandomValue { round: u128, random_value: u128 },
+    }
+```
+
+## Initialisation 
+
+The `init` method initializes the oracle with the given manager and sets up its default state, defining ownership and control.
+
+```rust title="oracle/randomness/app/src/lib.rs"
+    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: [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/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`: [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).
+For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing).

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<u128, state::Random>,
-    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: [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` 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`: [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).
+For more details about testing programs written on Vara, refer to this article: [Program Testing](/docs/build/testing).