fix(docs): Register FPC docs, contract deployment, events

docs/docs/aztec/concepts/advanced/index.md

@@ -1,6 +1,6 @@
 ---
 title: Advanced Concepts
-sidebar_position: 8
+sidebar_position: 9
 tags: [protocol]
 ---
 
@@ -9,4 +9,3 @@ In this section, you'll learn about the more advanced concepts of the Aztec Netw
 import DocCardList from '@theme/DocCardList';
 
 <DocCardList />
-

docs/docs/aztec/glossary/call_types.md → docs/docs/aztec/concepts/call_types.md

@@ -1,5 +1,7 @@
 ---
 title: Call Types
+sidebar_position: 6
+tags: [calls, contracts, execution]
 ---
 
 ## What is a Call
@@ -136,10 +138,12 @@ This is what the implementation of the check timestamp functionality looks like:
 :::note
 Note that the router contract is not currently part of the [aztec-nr repository](https://github.com/AztecProtocol/aztec-nr).
 To add it as a dependency point to the aztec-packages repository instead:
+
 ```toml
 [dependencies]
 aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "#include_aztec_version", directory = "noir-projects/noir-contracts/contracts/router_contract/src" }
 ```
+
 :::
 
 Even with the router contract achieving good privacy is hard.

docs/docs/aztec/concepts/communication/index.md

@@ -1,6 +1,6 @@
 ---
 title: Communication
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 ## Cross-chain communication

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

@@ -1,6 +1,6 @@
 ---
 title: Private Execution Environment (PXE)
-sidebar_position: 7
+sidebar_position: 8
 tags: [PXE]
 keywords: [pxe, private execution environment]
 importance: 1

docs/docs/aztec/smart_contracts/contract_creation.md

@@ -3,9 +3,82 @@ title: Contract Deployment
 tags: [contracts, protocol]
 ---
 
-import { Spec_Placeholder } from '/components/snippets';
+In the Aztec protocol, contracts are deployed as _instances_ of contract _classes_. The deployment process consists of two main steps: first registering the contract _class_ (if not already registered), and then creating a contract _instance_ that references this class.
 
-<Spec_Placeholder />
+## Contract Classes
+
+A contract class is a collection of state variable declarations, and related unconstrained, private, and public functions. Contract classes don't have state, they just define code (storage structure and function logic). A contract class cannot be called; only a contract instance can be called.
+
+### Key Benefits of Contract Classes
+
+Contract classes simplify code reuse by making implementations a first-class citizen in the protocol. With a single class registration, multiple contract instances can be deployed that reference it, reducing deployment costs. Classes also facilitate upgradability by decoupling state from code, making it easier for an instance to switch to different code while retaining its state.
+
+### Structure of a Contract Class
+
+A contract class includes:
+
+- `artifact_hash`: Hash of the contract artifact
+- `private_functions`: List of individual private functions, including constructors
+- `packed_public_bytecode`: Packed bytecode representation of the AVM bytecode for all public functions
+
+The specification of the artifact hash is not enforced by the protocol. It should include commitments to unconstrained code and compilation metadata. It is intended to be used by clients to verify that an off-chain fetched artifact matches a registered class.
+
+### Contract Class Registration
+
+A contract class is registered by calling a private `register` function in a canonical `ContractClassRegisterer` contract, which emits a Registration Nullifier. This process guarantees that the public bytecode for a contract class is publicly available, which is required for deploying contract instances.
+
+Contract class registration can be skipped if there are no public functions in the contract class, and the contract will still be usable privately. However, the contract class must be registered if it contains public functions, as these functions need to be publicly verifiable.
+
+If you have a contract with public functions, you must either register the contract class to deploy or a contract, or skip the public deployment step, in which case only the private functions will be callable.
+
+## Contract Instances
+
+A deployed contract is effectively an instance of a contract class. It always references a contract class, which determines what code it executes when called. A contract instance has both private and public state, as well as an address that serves as its identifier.
+
+### Structure of a Contract Instance
+
+A contract instance includes:
+
+- `version`: Version identifier, initially one
+- `salt`: User-generated pseudorandom value for uniqueness
+- `deployer`: Optional address of the contract deployer. Zero for universal deployment
+- `contract_class_id`: Identifier of the contract class for this instance
+- `initialization_hash`: Hash of the selector and arguments to the constructor
+- `public_keys_hash`: Optional hash of public keys used for encryption and nullifying
+
+### Instance Address
+
+The address of a contract instance is computed as the hash of the elements in its structure. This computation is deterministic, allowing users to precompute the expected deployment address of their contract, including account contracts.
+
+### Contract Initialization vs. Public Deployment
+
+Aztec makes an important distinction between initialization and public deployment:
+
+1. **Initialization**: A contract instance is considered Initialized once it emits an initialization nullifier, meaning it can only be initialized once. The default state for any address is to be uninitialized. A user who knows the preimage of the address can still issue a private call into a function in the contract, as long as that function doesn't assert that the contract has been initialized.
+2. **Public Deployment**: A Contract Instance is considered to be publicly deployed when it has been broadcast to the network via a canonical `ContractInstanceDeployer` contract, which also emits a deployment nullifier. All public function calls to an undeployed address must fail, since the contract class for it is not known to the network.
+
+### Initialization
+
+Contract constructors are not enshrined in the protocol, but handled at the application circuit level. Constructors are methods used for initializing a contract, either private or public, and contract classes may declare more than a single constructor. They can be declared by the `#[initializer]` macro. You can read more about how to use them on the [Defining Initializer Functions](../../developers/guides/smart_contracts/writing_contracts/initializers.md) page.
+
+A contract must ensure:
+
+- It is initialized at most once
+- It is initialized using the method and arguments defined in its address preimage
+- It is initialized by its deployer (if non-zero)
+- Functions dependent on initialization cannot be invoked until the contract is initialized
+
+Functions in a contract may skip the initialization check.
+
+## Verification of Executed Code
+
+The protocol circuits, both private and public, are responsible for verifying that the code loaded for a given function execution matches the expected one. This includes checking that the `contract_class_id` of the called address is the expected one and that the function selector being executed is part of the `contract_class_id`.
+
+## Genesis Contracts
+
+The `ContractInstanceDeployer` and `ContractClassRegisterer` contracts exist from the genesis of the Aztec Network, as they are necessary for deploying other contracts to the network. Their nullifiers are pre-inserted into the genesis nullifier tree.
+
+This modular approach to contract deployment creates a flexible system that supports diverse use cases, from public applications to private contract interactions, while maintaining the security and integrity of the Aztec protocol.
 
 ## Further reading
 

docs/docs/developers/guides/js_apps/pay_fees.md

@@ -125,6 +125,18 @@ import {
 } from "@aztec/aztec.js";
 ```
 
+The FPC contract must be registered in a users PXE before it can be used.
+
+```ts
+import { FPCContract } from "@aztec/noir-contracts.js/FPC";
+
+// ... (set up the wallet and PXE)
+
+// register the already deployed FPC contract in users PXE
+const fpcContract = FPCContract.at(fpcAddress, userWallet);
+await pxe.registerContract(fpcContract);
+```
+
 The fee payment method is created and used as follows, with similar syntax for private or public fee payments:
 
 #include_code fpc yarn-project/end-to-end/src/e2e_fees/public_payments.test.ts javascript
@@ -140,7 +152,7 @@ See this [section](../../reference/environment_reference/cli_wallet_reference.md
 This method of fee payment will only work for environments where a sponsored fee paying contract is deployed.
 The sandbox comes with a sponsored fee paying contract deployed, so this can be used to pay for transactions without needing to bridge fee juice.
 To use sponsored FPCs in other environments, they will need to be deployed and funded with fee juice.
-Creating the SponsoredFPC is as simple as importing it and passing it the PXE:
+Using a SponsoredFPC payment method is as simple as importing it, registering it and passing it the PXE:
 
 ```ts
 import { SponsoredFeePaymentMethod } from "@aztec/aztec.js/fee/testing";
@@ -150,6 +162,18 @@ import { SponsoredFeePaymentMethod } from "@aztec/aztec.js/fee/testing";
 const paymentMethod = new SponsoredFeePaymentMethod(deployedSponsoredFPC);
 ```
 
+Register the SponsoredFPC in the PXE:
+
+```ts
+import { SponsoredFPCContract } from "@aztec/noir-contracts.js/SponsoredFPC";
+
+// ... (set up the wallet and PXE)
+
+// register the already deployed SponsoredFPC contract in users PXE
+const fpcContract = SponsoredFPCContract.at(sponsoredFpcAddress, userWallet);
+await pxe.registerContract(fpcContract);
+```
+
 Then a transaction can specify this as the `paymentMethod` in the fee object.
 You can see an example of how to get a deployed instance of the sponsored FPC in the sandbox [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/yarn-project/aztec/src/sandbox/sponsored_fpc.ts#L15).
 For example, a contract can be deployed with an fpc as follows:
@@ -159,6 +183,8 @@ const paymentMethod = new SponsoredFeePaymentMethod(deployedSponsoredFPC);
 myAccountManager.deploy({ fee: { paymentMethod } });
 ```
 
+You can find the corresponding CLI command info [here](../../reference/environment_reference/cli_wallet_reference#sponsored-fee-paying-contract)
+
 ## Fee Options
 
 Functions pertaining to sending a transaction, such as `deploy` and `send`, each include a `fee` variable defined with the following (optional) parameters:

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

@@ -57,4 +57,4 @@ Public functions are always executed after private execution. To learn why, read
 
 #### Other call types
 
-There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/glossary/call_types.md).
+There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/concepts/call_types.md).

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

@@ -57,4 +57,4 @@ Public functions are always executed after private execution. To learn why, read
 
 #### Other call types
 
-There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/glossary/call_types.md).
+There are other call types, for example to ensure no state changes are made. You can learn more about them in the [call types glossary](../../../../aztec/concepts/call_types.md).

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

@@ -5,32 +5,39 @@ tags: [contracts]
 ---
 
 Events in Aztec work similarly to Ethereum events in the sense that they are a way for contracts to communicate with the outside world.
-They are emitted by contracts and stored inside each instance of an AztecNode.
 
-:::info
-Aztec events are currently represented as raw data and are not ABI encoded.
-ABI encoded events are a feature that will be added in the future.
-:::
+Events are structured pieces of data that can be emitted privately, from private functions, or publicly, from public functions. They include metadata about the event type, so people can query events to look for specific information.
+
+There are also public logs, which are similar to events, but are unstructured data.
+
+## Private Events
+
+To emit encrypted logs you can import the `encode_and_encrypt_event` or `encode_and_encrypt_event_unconstrained` functions and pass them into the `emit` function. An example can be seen in the reference token contract's transfer function:
+
+#include_code encrypted_unconstrained /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
 
-Unlike on Ethereum, there are 2 types of events supported by Aztec: [encrypted](#encrypted-events) and [unencrypted](#unencrypted-events).
+- `encode_and_encrypt_event` Sends an encrypted message to `recipient` with the content of the event, which they will discover when processing private logs.
+- `encode_and_encrypt_event_unconstrained` is the same as `encode_and_encrypt_event`, except encryption is unconstrained. This means that the sender is free to make the log contents be whatever they wish, so the recipient is trusting the sender of the event. This could also potentially result in scenarios in which the recipient is unable to decrypt and process the payload, **leading to the event being lost**. Only use this function in scenarios where the recipient not receiving the event is an acceptable outcome.
 
-## Encrypted Events
+:::note
+Developer can choose whether to emit encrypted events or not. Emitting the events means that they will be posted to Ethereum, in blobs, and will inherit the availability guarantees of Ethereum. Developers may choose not to emit events and to share information with recipients off-chain, or through alternative mechanisms that are to be developed (e.g. alternative, cheaper data availability solutions).
+:::
 
-### Call emit
+You can find the implementation of event logging [here](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/encrypted_logs/log_assembly_strategies/default_aes128/event.nr)
 
-To emit encrypted logs you can import the `encode_and_encrypt` or `encode_and_encrypt_with_keys` functions and pass them into the `emit` function after inserting a note. An example can be seen in the reference token contract's transfer function:
+### Processing encrypted events
 
-#include_code encrypted /noir-projects/noir-contracts/contracts/token_contract/src/main.nr rust
+Contracts created using aztec-nr will try to discover newly created events by searching for logs emitted for any of the accounts registered inside PXE, decrypting their contents and notifying PXE of any events found. This process is automatic and occurs whenever a contract function is invoked.
 
-Furthermore, if not emitting the note, one should explicitly `discard` the value returned from the note creation.
+## Public Events
 
-### Successfully process the encrypted event
+You can emit public events by calling the `emit` function on the event type that you would like to emit. For example:
 
-Contracts created using aztec-nr will try to discover newly created notes by searching for logs emitted for any of the accounts registered inside PXE, decrypting their contents and notifying PXE of any notes found. This process is automatic and occurs whenever a contract function is invoked.
+#include_code emit_public /noir-projects/noir-contracts/contracts/test_log_contract/src/main.nr rust
 
-## Unencrypted Events
+## Public Logs
 
-Unencrypted events are events which can be read by anyone. They can be emitted **only** by public functions.
+Public logs are unstructured data which can be read by anyone. They can be emitted **only** by public functions.
 
 ### Call emit_public_log
 
@@ -46,13 +53,4 @@ Once emitted, unencrypted events are stored in AztecNode and can be queried by a
 
 ## Costs
 
-All event data is pushed to Ethereum as calldata by the sequencer and for this reason the cost of emitting an event is non-trivial.
-
-In the Sandbox, an encrypted note has a fixed overhead of 4 field elements (to broadcast an ephemeral public key, a contract address, and a storage slot); plus a variable number of field elements depending on the type of note being emitted.
-
-A `ValueNote`, for example, currently uses 3 fields elements (plus the fixed overhead of 4). That's roughly `7 * 32 = 224` bytes of information.
-
-#include_code value-note-def /noir-projects/aztec-nr/value-note/src/value_note.nr
-
-- There are plans to compress encrypted note data further.
-- There are plans to adopt EIP-4844 blobs to reduce the cost of data submission further.
+Event data is pushed to Ethereum, in blobs, by the sequencer and for this reason the cost of emitting an event can be non-trivial. As mentioned above, emitting encrypted events is optional and there will likely be alternative options for developers to choose from in the future.

docs/docs/developers/reference/environment_reference/cli_wallet_reference.md

@@ -53,22 +53,35 @@ Below are all the payment methods available to pay transaction fees on Aztec, st
 
 Fee paying contracts specify their own criteria of payment in exchange for paying the fee juice of a transaction, e.g. an FPC
 be written to accept some banana tokens to pay for another's transaction fee.
-With an alias corresponding to the FPC's address this would be:
+
+Before using a fee paying contract, you need to register it in the PXE, passing the address of the contract and specifying the `from` account (in this case `main`). For example:
+
+```bash
+aztec-wallet register-contract $FPC_ADDRESS FPCContract -f main
+```
+
+With an alias corresponding to the FPC's address (`bananaFPC`) this would be:
 
 ```bash
 aztec-wallet <your transaction> --payment method=fpc,fpc-contract=contracts:bananaFPC
 ```
 
 ### Sponsored Fee Paying Contract
 
+Before using a Sponsored Fee Paying Contract (FPC), you need to register it in the PXE, passing the address of the contract and specifying the `from` account (in this case `main`). For example:
+
+```bash
+aztec-wallet register-contract $FPC_ADDRESS SponsoredFPC -f main
+```
+
 This is a special type of FPC that can be used to pay for account deployment and regular txs.
 Eg: to create an account paid for by the sponsoredFPC:
 
 ```bash
-aztec-wallet create-account -a main --payment method=fpc-sponsored,fpc=<fpc-address>
+aztec-wallet create-account -a main --payment method=fpc-sponsored,fpc=$FPC_ADDRESS
 ```
 
-:::Note
+:::note
 In the sandbox, the sponsored FPC address is printed at the end of its initial logs.
 :::
 

docs/docs/aztec/glossary/index.md → docs/docs/glossary.md

@@ -1,5 +1,6 @@
 ---
 title: Glossary
+tags: [protocol, glossary]
 ---
 
 ### `aztec-nargo`
@@ -38,7 +39,7 @@ How this works will be discussed via a future RFP process on Discourse, similarl
 
 The Private eXecution Environment (PXE) is a client-side library for the execution of private operations. The PXE generates proofs of private function execution, and sends these proofs along with public function requests to the sequencer. Private inputs never leave the client-side PXE.
 
-Read more [here](../concepts/pxe/index.md).
+Read more [here](./aztec/concepts/pxe/index.md).
 
 ### Sequencer