fix(docs): fable review (#24005)

Fixes the critical issues found in a full audit of the docs site,
applied to both the source docs and the published v4.3.1 versioned docs
(versioned facts verified against the `v4.3.1` tag, source facts against
`next`).

## Tutorials
- **Counter tutorial** (source + v4.3.1): adds the missing "clear the
scaffold's placeholder test" note. As written, renaming the contract
`Main` -> `Counter` leaves the generated `counter_test` crate
referencing `Main`, so `aztec compile` fails with 6 errors (reproduced
on a live local network). The token and recursive-verification tutorials
already carry this note.
- **Token bridge tutorial** (source + v4.3.1): the deploy script was
inlined from the monorepo's CI example, and its artifact imports don't
resolve in the Hardhat project the tutorial sets up. Adds a correction
note (Hardhat artifact paths and `bytecode` vs Forge's
`bytecode.object`), fixes the run command (`npx tsx scripts/index.ts`
instead of `npx hardhat run ... --network localhost`, which targets a
network the starter repo doesn't define), adds a note to update the
starter repo's `@aztec/l1-contracts` tag (pinned to v4.2.0-aztecnr-rc.2;
a `v4.3.1` tag exists upstream), and fixes a broken relative link.

## CLI references
- **aztec CLI reference** (source + v4.3.1): the `aztec start` section
was completely empty. Adds usage, examples, common options, and module
flags (verified against `aztec_start_options.ts`), linking to the
operator CLI reference for the full per-module list.
- **aztec-wallet CLI reference** (source + v4.3.1): removes
generator-machine leakage: `--data-dir` default
`/home/josh/.aztec/wallet` -> `~/.aztec/wallet`, `--node-url` default
`host.docker.internal` -> `localhost`.

## Operator docs
- **useful-commands / governance-participation** (source + v4.3.1): the
documented cast calls target functions that no longer exist on the
governance contracts. `M()` -> `ROUND_SIZE()`, `N()` -> `QUORUM_SIZE()`,
`yeaCount(...)` -> `signalCount(...)` (EmpireBase.sol), and
`proposals(uint256)` (internal mapping) -> `getProposal(uint256)`
(Governance.sol).
- **slashing-configuration** (source + v4.3.1): the ejection description
("98% of activation, max 3 slashes") didn't match the implementation.
Slashing ejection is driven by the rollup's `localEjectionThreshold`
(190,000 on mainnet, 95% of the 200,000 activation threshold; StakingLib
withdraws the entire remaining stake when a slash would cross it). Also
fixes stale 36s-per-slot math (slots are 72s) and the "28 rounds on
testnet" execution-delay label (28 rounds is mainnet). Source and v4.3.1
copies use their respective slash amounts (v4.3.1: all 2,000; next:
2,000/5,000 per AZIP-16).

## Aztec.nr / foundational topics
- **events_and_logs** (source + v4.3.1):
`self.context.emit_public_log(...)` doesn't exist; corrected to
`emit_public_log_unsafe(tag, log)` with a pointer to prefer
`self.emit(event)`.
- **state_variables / how_to_retrieve_filter_notes** (source + v4.3.1):
`get_notes`/`remove` documented around nonexistent
`RetrievedNote`/`HintedNote` types; the actual return type is
`ConfirmedNote`.
- **contract_structure** (source + v4.3.1): claimed the storage struct
"can have any name"; the `#[storage]` macro requires it to be named
`Storage`.
- **contract_creation** (source + v4.3.1): the "Proving Contract States"
block used a nonexistent `aztec::history::contract_inclusion` module;
replaced with the real `aztec::history::deployment` assert functions.
- **outbox.md** (source only): parameter tables and `getRootData`
signature updated to the checkpoint-based `IOutbox` (`Epoch` +
`_numCheckpointsInEpoch`). The v4.3.1 copy matches its own interface and
is untouched.

Spellcheck (`yarn cspell`) passes on all 514 files.

Author: critesjosh

docs/developer_versioned_docs/version-v4.3.1/docs/aztec-nr/framework-description/advanced/how_to_retrieve_filter_notes.md

@@ -33,8 +33,8 @@ This returns up to `MAX_NOTE_HASH_READ_REQUESTS_PER_CALL` notes without filterin
 ### Step 2: Retrieve notes from storage
 
 ```rust
-// Returns BoundedVec<HintedNote<MyNote>, ...>
-let hinted_notes = storage.my_notes.at(owner).get_notes(options);
+// Returns BoundedVec<ConfirmedNote<MyNote>, ...>
+let confirmed_notes = storage.my_notes.at(owner).get_notes(options);
 ```
 
 :::tip get_notes vs pop_notes

docs/developer_versioned_docs/version-v4.3.1/docs/aztec-nr/framework-description/contract_structure.md

@@ -98,7 +98,7 @@ pub contract MyContract {
     };
     use uint_note::UintNote;
 
-    // The storage struct can have any name, but is typically called `Storage`. It must have the `#[storage]` macro applied to it.
+    // The storage struct must be named `Storage` and must have the `#[storage]` macro applied to it.
     // This struct must also have a generic type called C or Context.
     #[storage]
     struct Storage<Context> {

docs/developer_versioned_docs/version-v4.3.1/docs/aztec-nr/framework-description/events_and_logs.md

@@ -86,13 +86,15 @@ Public events are emitted as plaintext logs, similar to Solidity events.
 
 ## Emit unstructured public logs
 
-For unstructured data, use `emit_public_log` directly on the context:
+For unstructured data, use `emit_public_log_unsafe` directly on the context. It takes a tag (placed at the first field of the emitted log, which nodes use to index logs) followed by the data:
 
 ```rust
-self.context.emit_public_log("My message");
-self.context.emit_public_log([1, 2, 3]);
+self.context.emit_public_log_unsafe(0, "My message");
+self.context.emit_public_log_unsafe(0, [1, 2, 3]);
 ```
 
+The tag should be domain-separated to prevent collisions with unrelated log types. Prefer `self.emit(event)` where possible, which handles tagging automatically.
+
 ## Query public logs
 
 Query public logs from offchain applications using the Aztec node:

docs/developer_versioned_docs/version-v4.3.1/docs/aztec-nr/framework-description/state_variables.md

@@ -579,7 +579,7 @@ Note: The `Owned` wrapper requires calling `.at(owner)` to access the underlying
 
 #### `get_notes`
 
-Retrieves notes the account has access to. You can optionally provide filtering options. Returns `RetrievedNote` instances:
+Retrieves notes the account has access to. You can optionally provide filtering options. Returns `ConfirmedNote` instances:
 
 ```rust title="private_set_get_notes" showLineNumbers 
 let options = NoteGetterOptions::with_filter(filter_notes_min_sum, amount);
@@ -591,7 +591,7 @@ let notes = owner_balance.get_notes(options);
 
 #### `pop_notes`
 
-This function pops (gets, removes and returns) the notes the account has access to. Unlike `get_notes`, this immediately nullifies the notes and returns them directly (not wrapped in `RetrievedNote`):
+This function pops (gets, removes and returns) the notes the account has access to. Unlike `get_notes`, this immediately nullifies the notes and returns them directly (not wrapped in `ConfirmedNote`):
 
 ```rust title="private_set_pop_notes" showLineNumbers 
 let options = NoteGetterOptions::new().set_limit(1);
@@ -602,13 +602,13 @@ let note = owner_balance.pop_notes(options).get(0);
 
 #### `remove`
 
-Will remove a note from the `PrivateSet` if it previously has been read from storage. Takes a `RetrievedNote` as returned by `get_notes`:
+Will remove a note from the `PrivateSet` if it previously has been read from storage. Takes a `ConfirmedNote` as returned by `get_notes`:
 
 ```rust
 let options = NoteGetterOptions::new();
-let retrieved_notes = self.storage.balances.at(owner).get_notes(options);
+let confirmed_notes = self.storage.balances.at(owner).get_notes(options);
 // ... select a note to remove ...
-self.storage.balances.at(owner).remove(retrieved_notes.get(0));
+self.storage.balances.at(owner).remove(confirmed_notes.get(0));
 ```
 
 Note that if you obtained the note via `get_notes`, it's much better to use `pop_notes`, as `pop_notes` results in significantly fewer constraints due to avoiding an extra hash and read request check.

docs/developer_versioned_docs/version-v4.3.1/docs/cli/aztec_cli_reference.md

@@ -67,9 +67,9 @@ wallet [options] [command]
 **Options:**
 
 - `-V --version` - output the version number
-- `-d --data-dir <string>` - Storage directory for wallet data (default: "/home/josh/.aztec/wallet")
+- `-d --data-dir <string>` - Storage directory for wallet data (default: "~/.aztec/wallet")
 - `-p --prover <string>` - The type of prover the wallet uses (choices: "wasm", "native", "none", default: "native", env: PXE_PROVER)
-- `-n --node-url <string>` - URL of the Aztec node to connect to (default: "http://host.docker.internal:8080", env: AZTEC_NODE_URL)
+- `-n --node-url <string>` - URL of the Aztec node to connect to (default: "http://localhost:8080", env: AZTEC_NODE_URL)
 - `-h --help` - display help for command
 
 ### Subcommands

docs/developer_versioned_docs/version-v4.3.1/docs/cli/aztec_wallet_cli_reference.md

@@ -102,24 +102,25 @@ Your contract can verify the deployment or initialization state of other contrac
 - Conditional logic based on initialization
 
 ```rust
-use aztec::history::contract_inclusion::{
-    ProveContractDeployment,
-    ProveContractNonDeployment,
-    ProveContractInitialization,
-    ProveContractNonInitialization,
+use aztec::history::deployment::{
+    assert_contract_bytecode_was_not_published_by,
+    assert_contract_bytecode_was_published_by,
+    assert_contract_was_initialized_by,
+    assert_contract_was_not_initialized_by,
 };
 
-// Prove a contract is deployed
-header.prove_contract_deployment(contract_address);
+// Prove a contract's bytecode was published by a given block
+assert_contract_bytecode_was_published_by(block_header, contract_address);
 
-// Prove a contract is NOT deployed
-header.prove_contract_non_deployment(contract_address);
+// Prove a contract's bytecode was NOT published by a given block
+assert_contract_bytecode_was_not_published_by(block_header, contract_address);
 
-// Prove a contract is initialized
-header.prove_contract_initialization(contract_address);
+// Prove a contract was initialized by a given block
+// (init_hash is the contract's initialization hash, obtainable via get_contract_instance)
+assert_contract_was_initialized_by(block_header, contract_address, init_hash);
 
-// Prove a contract is NOT initialized
-header.prove_contract_non_initialization(contract_address);
+// Prove a contract was NOT initialized by a given block
+assert_contract_was_not_initialized_by(block_header, contract_address, init_hash);
 ```
 
 These functions prove inclusion or non-inclusion of the corresponding nullifiers in the nullifier tree at a given block.

docs/developer_versioned_docs/version-v4.3.1/docs/foundational-topics/contract_creation.md

@@ -65,6 +65,15 @@ pub contract Counter {
 
 This defines a contract called `Counter`.
 
+:::note Clear the scaffold's placeholder test
+The scaffolded `counter_test/src/lib.nr` imports the default contract name (`Main`) we just replaced above, so it now fails to compile. Tests aren't used in this tutorial - replace its contents with a single-line stub so `aztec compile` stays clean:
+
+```rust
+// Tests are out of scope for this tutorial. See https://docs.aztec.network/developers/docs/aztec-nr/testing_contracts for examples.
+```
+
+:::
+
 ## Imports
 
 We need to define some imports.

docs/developer_versioned_docs/version-v4.3.1/docs/tutorials/contract_tutorials/counter_contract.md

@@ -39,6 +39,16 @@ cd hardhat-aztec-example
 yarn add @aztec/aztec.js@4.3.1 @aztec/accounts@4.3.1 @aztec/stdlib@4.3.1 @aztec/wallets@4.3.1 tsx
 ```
 
+:::note Match the `@aztec/l1-contracts` version
+The starter repo pins its `@aztec/l1-contracts` dependency to an older release. In `package.json`, update the tag to match the network version used in this tutorial, then run `yarn install` again:
+
+```json
+"@aztec/l1-contracts": "git+https://github.com/AztecProtocol/l1-contracts.git#v4.3.1"
+```
+
+The L1 interfaces the portal imports later in this tutorial must match the contracts deployed by your running network.
+:::
+
 Now start the local network in another terminal:
 
 ```bash
@@ -274,7 +284,7 @@ aztec compile
 
 We have built the L2 NFT contract. This is the L2 representation of an NFT that is locked on the L1 bridge.
 
-The L2 bridge is the contract that talks to the L1 bridge through cross-chain messaging. You can read more about this protocol [here](../../../docs/foundational-topics/ethereum-aztec-messaging/index.md).
+The L2 bridge is the contract that talks to the L1 bridge through cross-chain messaging. You can read more about this protocol [here](../../foundational-topics/ethereum-aztec-messaging/index.md).
 
 ```mermaid
 graph LR
@@ -667,6 +677,19 @@ const inboxAddress = nodeInfo.l1ContractAddresses.inboxAddress.toString();
 > <sup><sub><a href="https://github.com/AztecProtocol/aztec-packages/blob/v4.3.1/docs/examples/ts/token_bridge/index.ts#L1-L42" target="_blank" rel="noopener noreferrer">Source code: docs/examples/ts/token_bridge/index.ts#L1-L42</a></sub></sup>
 
 
+:::warning Adjust the artifact imports for this project's layout
+The snippet above comes from the monorepo's runnable example, and its artifact imports point at that repo's layout. In the Hardhat project used in this tutorial, replace the four artifact imports with:
+
+```typescript
+import NFTPortal from "../artifacts/contracts/NFTPortal.sol/NFTPortal.json" with { type: "json" };
+import SimpleNFT from "../artifacts/contracts/SimpleNFT.sol/SimpleNFT.json" with { type: "json" };
+import { NFTBridgeContract } from "../contracts/aztec/artifacts/NFTBridge.js";
+import { NFTPunkContract } from "../contracts/aztec/artifacts/NFTPunk.js";
+```
+
+`npx hardhat compile` writes the Solidity artifacts to `artifacts/contracts/`, and the `aztec codegen` commands from earlier wrote the TypeScript bindings to `contracts/aztec/artifacts/`. Hardhat artifacts also store the bytecode as a plain string, so in the deployment snippet below use `SimpleNFT.bytecode` and `NFTPortal.bytecode` instead of `.bytecode.object`.
+:::
+
 You now have wallets for both chains, correctly connected to their respective chains. Next, deploy the L1 contracts:
 
 ```typescript title="deploy_l1_contracts" showLineNumbers 
@@ -1021,8 +1044,8 @@ console.log("NFT withdrawn to L1\n");
 
 You can now try the whole flow with:
 
-```typescript
-npx hardhat run scripts/index.ts --network localhost
+```bash
+npx tsx scripts/index.ts
 ```
 
 ## What You Built

docs/developer_versioned_docs/version-v4.3.1/docs/tutorials/js_tutorials/token_bridge.md

@@ -33,8 +33,8 @@ This returns up to `MAX_NOTE_HASH_READ_REQUESTS_PER_CALL` notes without filterin
 ### Step 2: Retrieve notes from storage
 
 ```rust
-// Returns BoundedVec<HintedNote<MyNote>, ...>
-let hinted_notes = storage.my_notes.at(owner).get_notes(options);
+// Returns BoundedVec<ConfirmedNote<MyNote>, ...>
+let confirmed_notes = storage.my_notes.at(owner).get_notes(options);
 ```
 
 :::tip get_notes vs pop_notes