Skip to content

Conversation

@critesjosh
Copy link
Contributor

@critesjosh critesjosh commented Dec 19, 2025

Summary

Comprehensive documentation review and improvements for the aztec-nr developer documentation. This PR focuses on improving clarity, structure, accuracy, and consistency across the Aztec smart contract development guides.

Changes Include:

Framework & Core Concepts

  • Improved storage declaration guide with clearer examples and structure
  • Enhanced macros documentation for better clarity
  • Updated contract artifacts, structure, upgrades, and dependencies documentation
  • Refined global variables documentation

Function Documentation

  • Updated attributes documentation for clarity and accuracy
  • Streamlined function transforms and visibility documentation

How-To Guides

  • Enhanced event emission guide with clearer structure and examples
  • Refined custom notes implementation guide
  • Streamlined how-to guide for calling contracts
  • Updated authwit (authentication witness) guide for clarity
  • Improved cross-chain communication guide

Advanced Topics

  • Enhanced documentation for proving historical state
  • Improved retrieving and filtering notes guide
  • Updated partial notes and capsules documentation
  • Refactored profiling transactions guide

L1-L2 Messaging

  • Updated L1-L2 messaging data structures documentation
  • Improved inbox, outbox, and registry documentation

Setup & Installation

  • Updated installation instructions for Noir LSP to specify VSCode Extension
  • Improved local network installation instructions

General Improvements

  • Fixed grammatical errors and typos throughout
  • Improved consistency in tone and terminology
  • Updated links and cross-references
  • Removed redundant information and improved conciseness
  • Better organization of content following simple → complex flow

critesjosh and others added 18 commits December 19, 2025 15:23
…, structure, upgrades, dependencies, and global variables

- Updated "how to profile transactions" guide to clarify profiling steps and output analysis.
- Revised "contract artifact" documentation to improve clarity on artifact structure and usage.
- Enhanced "contract structure" section with clearer explanations and next steps for developers.
- Streamlined "contract upgrades" documentation to emphasize upgrade processes and security considerations.
- Expanded "aztec.nr dependencies" section to include detailed library paths and descriptions.
- Improved "global variables" documentation to clarify differences between private and public contexts.
@critesjosh critesjosh marked this pull request as ready for review December 24, 2025 19:01
@critesjosh critesjosh requested a review from a team December 24, 2025 19:01
@AztecBot
Copy link
Collaborator

Flakey Tests

🤖 says: This CI run detected 1 tests that failed, but were tolerated due to a .test_patterns.yml entry.

\033FLAKED\033 (\0338;;http://ci.aztec-labs.com/dec5119fd6c6de0f�dec5119fd6c6de0f8;;�\033):  yarn-project/end-to-end/scripts/run_test.sh simple src/e2e_p2p/multiple_validators_sentinel.parallel.test.ts "collects attestations for validators in proposer node when block is not published" (106s) (code: 1) group:e2e-p2p-epoch-flakes (\033Josh Crites\033: fix links)

Copy link
Contributor

@sklppy88 sklppy88 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

beautiful !


:::tip get_notes vs pop_notes

- `get_notes`: Retrieves notes without nullifying. Use when you need to read note data.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note data is not guaranteed to be current, or non-nullified

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As an aside, I think we should move everything to include codes. Right now it's a mix of code blocks and include codes.

Comment on lines +114 to +117
The message structures are:
- `L1Actor` and `L2Actor` - Represent entities on L1 and L2 respectively
- `L1ToL2Msg` - Message sent from L1 to L2
- `L2ToL1Msg` - Message sent from L2 to L1
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section a bit verbose

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants