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,26 @@
+---
+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
+
+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 actually allowed to modify them.
+
+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. See [oracles](./oracles.md) for more information.
+
+## 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 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,5 +1,5 @@
 ---
-title: Oracle Functions
+title: Oracles
 tags: [functions, oracles]
 ---
 
@@ -11,11 +11,6 @@ An oracle is something that allows us to get data from the outside world into ou
 
 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.
-
-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!
 
 `Aztec.nr` has a module dedicated to its oracles. If you are interested, you can view them by following the link below: