refactor: renaming pxe_db.nr as capsules.nr (#11905)

.gitignore

@@ -31,4 +31,7 @@ tmux-client-*.log
 .supermavenignore
 
 # parallel
-joblog.txt
+joblog.txt
+
+docs/.yarn/install-state.gz
+docs/docs/protocol-specs/public-vm/gen/

docs/docs/aztec/concepts/pxe/index.md

@@ -109,4 +109,4 @@ Oracles are pieces of data that are injected into a smart contract function from
 To learn how to develop on top of the PXE, refer to these guides:
 
 - [Run more than one PXE on your local machine](../../../developers/guides/local_env/run_more_than_one_pxe_sandbox.md)
-- [Use in-built oracles including oracles for arbitrary data](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md)
+- [Use in-built oracles including oracles for arbitrary data](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md)

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

@@ -5,7 +5,7 @@ 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_pop_capsules.md).
+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.
 
@@ -31,4 +31,4 @@ Oracles introduce **non-determinism** into a circuit, and thus are `unconstraine
 
 Find a full list [on GitHub](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/aztec-nr/aztec/src/oracle).
 
-Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [popCapsule](../../../developers/guides/smart_contracts/writing_contracts/how_to_pop_capsules.md).
+Please note that it is **not** possible to write a custom oracle for your dapp. Oracles are implemented in the PXE, so all users of your dapp would have to use a PXE service with your custom oracle included. If you want to inject some arbitrary data that does not have a dedicated oracle, you can use [capsules](../../../developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md).

docs/docs/developers/guides/smart_contracts/writing_contracts/how_to_use_capsules.md

@@ -0,0 +1,54 @@
+---
+title: Using Capsules
+sidebar_position: 5
+tags: [functions, oracles]
+---
+
+Capsules are a per-contract non-volatile database.
+It can be used for storing arbitrary data that can be retrieved later.
+The data is stored locally in PXE and it is scoped per contract address, so external contracts cannot access it.
+The capsule (data stored under a storage slot in the capsules database) persists until explicitly deleted with `delete`.
+
+The capsules module provides these main functions:
+
+- `store<T, N>` - Stores arbitrary data at a slot, overwriting any existing data
+- `load<T, N>` - Retrieves previously stored data from a slot
+- `delete` - Deletes data at a slot
+- `copy` - Efficiently copies contiguous entries between slots
+
+### 1. Import capsules into your smart contract
+
+Import the capsules module:
+
+#include_code import_capsules noir-projects/noir-contracts/contracts/contract_class_registerer_contract/src/main.nr rust
+
+### 2. Store and load data
+
+You can store any type that implements `Serialize` and `Deserialize`:
+
+#include_code load_capsule noir-projects/noir-contracts/contracts/contract_class_registerer_contract/src/main.nr rust
+
+The data is stored per contract address and slot. When loading, you'll get back an `Option<T>` - `None` if no data exists at that slot.
+
+### 3. Copying data
+
+You can use `copy` to move contiguous entries between slots without repeated loads and stores.
+This supports overlapping source and destination regions.
+
+Note that all values are scoped per contract address, so external contracts cannot access them.
+
+### 4. Using CapsuleArray
+
+The `CapsuleArray<T>` type provides a dynamically sized array backed by capsules.
+It handles the storage layout and management automatically.
+The array stores its length at a base slot, with elements stored in consecutive slots after it.
+
+Key functions:
+
+- `at(contract_address, base_slot)` - Creates/connects to an array at the given base slot
+- `len()` - Returns the number of elements in the array
+- `push(value)` - Appends a value to the end of the array
+- `get(index)` - Retrieves the value at the given index
+- `remove(index)` - Removes an element, shifting subsequent elements to maintain contiguous storage
+
+<!-- TODO: Document actual use case of CapsuleArray here once it's actually used. -->