feat(docs): Docs on shared mutable, contract classes, and injecting data

docs/docs/aztec/concepts/accounts/keys.md

@@ -152,3 +152,17 @@ App-siloed incoming viewing key also allows per-application auditability. A user
 Key rotation is the process of creating new signing keys to replace existing keys. By rotating encryption keys on a regular schedule or after specific events, you can reduce the potential consequences of the key being compromised.
 
 On Aztec, key rotation is impossible for nullifier keys, incoming viewing keys and address keys as all of them are embedded into the address and address is unchangeable. In the meanwhile, signing keys can be rotated.
+
+## Shared secrets
+
+Aztec uses the Elliptic Curve Diffie-Hellman (ECDH) method to allow two parties to securely create a shared secret without directly exchanging it.
+
+ECDH works by each party generating a public-private key pair and exchanging public keys, then using their own private key and the other party’s public key to derive the same shared secret. Mathematically, if Alice has a private key `a` and public key `A = aG`, and Bob has a private key `b` and public key `B = bG` (where `G` is a generator point on the elliptic curve), they can both compute the shared secret as:
+
+```
+S = aB = a(bG) = b(aG) = bA
+```
+
+This shared secret encrypts private data to be shared with another party over the network, which enables private transactions without communicating with the other party outside of the network.
+
+

docs/docs/aztec/smart_contracts/contract_classes.md

@@ -0,0 +1,15 @@
+---
+title: Contract Classes
+tags: [contracts, protocol]
+sidebar_position: 0
+---
+
+Aztec defines a difference between contract *classes* and contract *instances*. This is different from Ethereum, where every contract's bytecode is deployed to the network and has a unique address.
+
+## Contract classes
+
+A contract class defines the contract's bytecode and is uniquely identified by a hash. A contract class doesn't have its own storage or state, but is more of a template that outlines the contract's code.
+
+## Contract instances
+
+A contract instance is a deployed version of a contract class with its own storage and state. Each instance operates independently. This separation allows for multiple deployments of the same contract logic without interference between instances.

docs/docs/aztec/smart_contracts/injecting_data/index.md

@@ -0,0 +1,24 @@
+---
+title: Injecting Data
+tags: [functions, oracles, capsules]
+---
+
+There are multiple ways to inject data into smart contracts.
+
+1. **Oracles** - fetching data from the outside world
+2. **Authwits (Authentication Witnesses)** - authorizing an arbitrary action (or piece of data)
+3. **Capsules** - local data storage in the PXE
+
+## Oracles
+
+An oracle is something that allows us to get data from the outside world into our contracts. Aztec has some inbuilt oracles that allow developers to access cross-chain messages, private logs, data about notes, and others. You can learn more about them [here](./oracles.md).
+
+## Authentication Witnesses (authwit)
+
+The same mechanism used in oracles is also used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation. See [AuthWit](../../concepts/advanced/authwit.md) for more information on this.
+
+## Capsules
+
+Capsules are used to store contract-scoped data in the PXE and inject this data into smart contracts. They can be useful for arbitrary data that does not have a dedicated oracle.
+
+You can learn more about using capsules in contracts in the [reference docs](../../../developers/reference/smart_contract_reference/aztec-nr/aztec/oracle/capsules.md)

docs/docs/aztec/smart_contracts/oracles/index.md → docs/docs/aztec/smart_contracts/injecting_data/oracles.md

@@ -1,22 +1,19 @@
 ---
-title: Oracle Functions
+title: Oracles
 tags: [functions, oracles]
 ---
 
 This page goes over what oracles are in Aztec and how they work.
 
 Looking for a hands-on guide? You can learn how to use oracles in a smart contract [here](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md).
 
-An oracle is something that allows us to get data from the outside world into our contracts. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account.
+Oracles are used to fetch data from the outside world. The most widely-known types of oracles in blockchain systems are probably Chainlink price feeds, which allow us to get the price of an asset in USD taking non-blockchain data into account.
 
 While this is one type of oracle, the more general oracle, allows us to get any data into the contract. In the context of oracle functions or oracle calls in Aztec, it can essentially be seen as user-provided arguments, that can be fetched at any point in the circuit, and don't need to be an input parameter.
 
-**Why is this useful? Why don't just pass them as input parameters?**
-In the world of EVM, you would just read the values directly from storage and call it a day. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you actually allowed to modify them.
+In the world of EVM, you can read data directly from storage. However, when we are working with circuits for private execution, this becomes more tricky as you cannot just read the storage directly from your state tree, because there are only commitments (e.g. hashes) there. The pre-images (content) of your commitments need to be provided to the function to prove that you know value that the commitments represent and that you are actually allowed to modify them. We can instead fetch the notes with an oracle all.
 
-If we fetch the notes using an oracle call, we can keep the function signature independent of the underlying data and make it easier to use. A similar idea, applied to the authentication mechanism is used for the Authentication Witnesses that allow us to have a single function signature for any wallet implementation, see [AuthWit](../../concepts/advanced/authwit.md) for more information on this.
-
-Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure!
+Oracles introduce **non-determinism** into a circuit, and thus are `unconstrained`. It is important that any information that is injected into a circuit through an oracle is later constrained for correctness. Otherwise, the circuit will be **under-constrained** and potentially insecure.
 
 `Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below:
 #include_code oracles-module /noir-projects/aztec-nr/aztec/src/oracle/mod.nr rust
@@ -27,7 +24,7 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine
 - [`auth_witness`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/authwit/src/auth_witness.nr) - Provides a way to fetch the authentication witness for a given address. This is useful when building account contracts to support approve-like functionality.
 - [`get_l1_to_l2_message`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/get_l1_to_l2_message.nr) - Useful for application that receive messages from L1 to be consumed on L2, such as token bridges or other cross-chain applications.
 - [`notes`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/notes.nr) - Provides a lot of functions related to notes, such as fetches notes from storage etc, used behind the scenes for value notes and other pre-build note implementations.
-- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the to log encrypted and unencrypted data.
+- [`logs`](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/oracle/logs.nr) - Provides the ability to log encrypted and unencrypted data.
 
 Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle).