Repository navigation
Book LLM Aptos material - #13
Conversation
- Complete structs chapters: intro, basics, resources, abilities, example, methods - Complete enums chapters: intro, defining, pattern_matching - Complete modules chapters: intro, basics, imports, scopes, packages, dependencies, publishing - Complete testing chapters: intro, writing_unit_tests, running_unit_tests, coverage, formal_verification - Complete design_patterns chapters: intro, account_authorization_by_signer, event_emission - Expand closures/intro with meaningful content - Complete standard_libraries: move_stdlib, aptos_stdlib, aptos_framework - Complete events/indexing with API and indexer details - Fix TODO: IDE/editor links in installation.md - Fix TODO: Explorer link in hello_blockchain.md - Fix TODO: Test code example in guessing_game/extending.md - Fix TODO: Additional libraries in standard_libraries/intro.md - Fix TODO: LaTeX formula in gas/intro.md - Fix TODO: BlockSTM explanation in parallelization/basics.md Co-authored-by: Greg Nazario <greg@gnazar.io>
…ption New section with four chapters: - Using LLMs to Write Move Code: prompt engineering, patterns, common pitfalls - Using LLMs to Audit Smart Contracts: AI audit workflow, vulnerability detection - Building AI Agents on Aptos: architecture, guardrails, agent frameworks - The llms.txt Standard and Aptos: documentation optimization for LLMs Also: - Update SUMMARY.md with new section - Improve book description in book.toml for LLM discoverability - Update intro.md with book structure overview and LLM optimization note - Update aptos.md landing page with AI-ready features - Expand resources.md with tools, community, and AI resources Co-authored-by: Greg Nazario <greg@gnazar.io>
Remove direct URL links to IDE marketplace pages that may return 404, replace with instructions to search in the respective marketplaces. Book now builds successfully with all backends including linkcheck. Co-authored-by: Greg Nazario <greg@gnazar.io>
|
Cursor Agent can help with this pull request. Just |
There was a problem hiding this comment.
Pull request overview
This pull request significantly expands the Aptos Book with comprehensive documentation covering Move smart contract development, standard libraries, design patterns, and AI-assisted development. The PR adds over 20 new markdown files with extensive code examples, creating a complete reference guide optimized for both human developers and LLM consumption.
Changes:
- Adds complete chapters on testing, structs, enums, modules, design patterns, and building with LLMs
- Expands standard library documentation (MoveStdlib, AptosStdlib, AptosFramework) with practical examples
- Updates book metadata and structure to include llms.txt optimization
- Fills in previously TODO-marked sections across multiple chapters
Reviewed changes
Copilot reviewed 45 out of 45 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| src/testing/writing_unit_tests.md | Complete guide to writing unit tests with annotations, signers, and best practices |
| src/testing/running_unit_tests.md | Documentation for running tests, filtering, debugging, and handling common issues |
| src/testing/intro.md | Introduction to Move testing framework with quick start example |
| src/testing/formal_verification.md | Guide to formal verification with Move Prover and specification language |
| src/testing/coverage.md | Documentation for generating and interpreting test coverage reports |
| src/structs/resources.md | Comprehensive explanation of resources, global storage operations, and abilities |
| src/structs/methods.md | Documentation for struct method syntax with receiver types |
| src/structs/intro.md | Introduction to structs and the abilities system |
| src/structs/example.md | Complete address book example demonstrating struct usage |
| src/structs/basics.md | Guide to defining, instantiating, and working with structs |
| src/structs/abilities.md | Deep dive into the four abilities (copy, drop, store, key) |
| src/standard_libraries/move_stdlib.md | Documentation of Move Standard Library modules with examples |
| src/standard_libraries/intro.md | Updated to include third-party libraries and ecosystem tools |
| src/standard_libraries/aptos_stdlib.md | Documentation of Aptos Standard Library data structures and utilities |
| src/standard_libraries/aptos_framework.md | Comprehensive framework documentation with account, token, and object modules |
| src/resources.md | Expanded learning resources including AI/LLM tools and community links |
| src/parallelization/basics.md | Added explanation of BlockSTM parallel execution mechanism |
| src/modules/scopes.md | Complete guide to function visibility levels and view functions |
| src/modules/publishing.md | Documentation for package publishing, upgrade policies, and deployment workflow |
| src/modules/packages.md | Guide to package structure, Move.toml, and compilation |
| src/modules/intro.md | Introduction to modules and packages organization |
| src/modules/imports.md | Complete import patterns and standard library usage |
| src/modules/dependencies.md | Guide to dependency management and git dependencies |
| src/modules/basics.md | Module definition, naming conventions, and named addresses |
| src/intro.md | Updated with book structure overview and LLM optimization description |
| src/guessing_game/extending.md | Added test helper functions for randomness testing |
| src/getting_started/installation.md | Updated IDE recommendations with specific editor extensions |
| src/getting_started/hello_blockchain.md | Added link to Aptos Explorer for viewing deployed contracts |
| src/gas/intro.md | Updated gas formula from plaintext to LaTeX format |
| src/events/indexing.md | Complete guide to event indexing, querying, and building custom indexers |
| src/enums/pattern_matching.md | Comprehensive match expression documentation with state machine example |
| src/enums/intro.md | Introduction to enums and pattern matching |
| src/enums/defining.md | Guide to defining enums with variants and data |
| src/design_patterns/intro.md | Introduction to design patterns for Move development |
| src/design_patterns/event_emission.md | Pattern for emitting events with best practices |
| src/design_patterns/account_authorization_by_signer.md | Pattern for using signers for authorization and access control |
| src/closures/intro.md | Documentation for closures, lambdas, and function values |
| src/building_with_llms/writing_move_with_llms.md | Guide to using LLMs for Move code generation with prompt patterns |
| src/building_with_llms/llms_txt_and_aptos.md | Documentation of llms.txt standard and its use in Aptos ecosystem |
| src/building_with_llms/intro.md | Introduction to AI-assisted Aptos development |
| src/building_with_llms/auditing_with_llms.md | Guide to using LLMs for smart contract security review |
| src/building_with_llms/ai_agents_on_aptos.md | Complete guide to building AI agents with architecture, frameworks, and examples |
| src/aptos.md | Updated with key features and AI-ready documentation highlights |
| src/SUMMARY.md | Added new chapter on building with LLMs to table of contents |
| book.toml | Updated description to reflect comprehensive content and LLM optimization |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ```typescript | ||
| // Fetch the Aptos Book content for LLM context | ||
| const response = await fetch("https://aptos-book.com/llms-full.txt"); |
There was a problem hiding this comment.
The example URL "https://aptos-book.com/llms-full.txt" appears to be a placeholder. Consider using the actual production URL where this book will be hosted, or clarify in the text that this is an example URL that should be replaced with the actual deployment URL.
| const response = await fetch("https://aptos-book.com/llms-full.txt"); | |
| // Replace the URL below with the actual location where your llms-full.txt is hosted | |
| const response = await fetch("https://your-domain.example.com/llms-full.txt"); |
| TODO: GIF of block STM | ||
| ## How BlockSTM Works | ||
|
|
||
| 1. **Optimistic Execution**: All transactions in a block are executed in parallel, assuming no conflicts. |
There was a problem hiding this comment.
In the "Step 1: Optimistic Execution" section, the explanation describes optimistic execution but doesn't mention what happens when there are no conflicts. Consider adding that when all transactions complete without conflicts, the entire block is committed without re-execution, which is the ideal case that BlockSTM optimizes for.
| 1. **Optimistic Execution**: All transactions in a block are executed in parallel, assuming no conflicts. | |
| 1. **Optimistic Execution**: All transactions in a block are executed in parallel, assuming no conflicts. When all transactions complete without conflicts, the entire block can be committed without any re-execution, which is the ideal case that BlockSTM is optimized for. |
| ``` | ||
| (gas used x gas unit price) + storage refund = total gas | ||
| ``` | ||
| $$\text{total fee} = (\text{gas used} \times \text{gas unit price}) + \text{storage refund}$$ |
There was a problem hiding this comment.
The LaTeX formula uses \text{total fee} but the surrounding context refers to it as "total gas cost" and mentions it can be a "refund". Consider changing the formula to use \text{total gas} or \text{net gas cost} to better align with the terminology used in the text, particularly since storage refunds can exceed gas used, resulting in a net gain rather than a fee.
| $$\text{total fee} = (\text{gas used} \times \text{gas unit price}) + \text{storage refund}$$ | |
| $$\text{total gas cost} = (\text{gas used} \times \text{gas unit price}) + \text{storage refund}$$ |
| let i = 0; | ||
| let len = v.length(); | ||
| while (i < len) { | ||
| result.push_back(f(*v.borrow(i))); |
There was a problem hiding this comment.
The code uses v.borrow(i) for vector element access. Consider adding a note or showing an alternative with the modern bracket indexing syntax v[i] if it's supported in this context, for consistency with the modern Move syntax promoted elsewhere in the book (like Resource[addr] for global storage access).
| result.push_back(f(*v.borrow(i))); | |
| result.push_back(f(*v[i])); |
| struct AgentConfig has key { | ||
| owner: address, | ||
| daily_spent: u64, | ||
| last_reset_timestamp: u64, | ||
| max_transfer: u64, | ||
| max_daily_spend: u64, | ||
| is_active: bool, | ||
| } |
There was a problem hiding this comment.
The AgentConfig struct has a last_reset_timestamp field that is never used in the example code. Consider either showing how this field is used to reset daily spending limits based on time, or removing it from the example to avoid confusion. If it's meant to be part of the implementation left out for brevity, add a comment indicating that.
| assert!(config.is_active, 1); // Agent must be active | ||
| assert!(amount <= config.max_transfer, 2); // Per-transaction limit | ||
| assert!(config.daily_spent + amount <= config.max_daily_spend, 3); // Daily limit |
There was a problem hiding this comment.
The error codes in the agent_transfer function use raw numeric error codes (1, 2, 3) instead of named constants. This violates the error handling convention established elsewhere in the book where error codes should use the E_ prefix naming convention (e.g., E_AGENT_INACTIVE, E_TRANSFER_TOO_LARGE, E_DAILY_LIMIT_EXCEEDED). Consider updating this example to follow the established pattern.
| /// No address book found for this account | ||
| const E_NO_ADDRESS_BOOK: u64 = 1; | ||
| /// Contact not found | ||
| const E_CONTACT_NOT_FOUND: u64 = 2; |
There was a problem hiding this comment.
The E_CONTACT_NOT_FOUND error constant is defined but never used in any of the functions. Consider either adding a function that uses this error (e.g., a remove_contact or get_contact_by_name function) or removing the unused constant to avoid confusion.
1. llms_txt_and_aptos.md: Add clarifying comment that aptos-book.com is the actual production URL, not a placeholder 2. parallelization/basics.md: Add note about the ideal no-conflict case where the entire block commits without re-execution 3. gas/intro.md: Change LaTeX formula from 'total fee' to 'total gas cost' to align with surrounding terminology about refunds 4. closures/intro.md: Use modern bracket indexing syntax v[i] instead of v.borrow(i) for consistency with the rest of the book 5. ai_agents_on_aptos.md: Use named E_ error constants (E_AGENT_INACTIVE, E_TRANSFER_TOO_LARGE, E_DAILY_LIMIT_EXCEEDED) instead of raw numbers; add maybe_reset_daily_spent() to use last_reset_timestamp field 6. structs/example.md: Add remove_contact() function that uses E_CONTACT_NOT_FOUND, plus tests for removal and invalid index Co-authored-by: Greg Nazario <greg@gnazar.io>
Completes and optimizes the Aptos Book for LLM consumption, including a new section on building with LLMs on Aptos.