docs: rewrite gas optimization guide for clarity#1777
docs: rewrite gas optimization guide for clarity#1777Dominion116 wants to merge 1 commit intostacks-network:masterfrom
Conversation
|
|
| Optimize Clarity smart contracts to minimize execution costs and improve performance. | ||
|
|
||
| {% hint style="info" %} | ||
| While Stacks transaction costs are significantly lower than Ethereum, efficient gas management ensures a better user experience and enables higher throughput for complex operations like DeFi or NFT mints. |
There was a problem hiding this comment.
Why comparing tx costs with Ethereum? Remove that.
| 4. **Write Length**: Bytes written to storage. | ||
| 5. **Runtime**: CPU execution cycles. | ||
|
|
||
| Modern Clarity development relies on minimizing storage interactions, as these are the most expensive operations. |
There was a problem hiding this comment.
How are storage interactions most expensive?
|
|
||
| Avoid calling `var-get` or `map-get?` multiple times for the same value in a single execution. Cache the value in a `let` binding instead. | ||
|
|
||
| {% code title="caching.clar" %} |
There was a problem hiding this comment.
Example does not reduce the costs. Best to share the costs for bad and good in this doc
|
|
||
| Consolidate related data into tuples to minimize industrial map writes. | ||
|
|
||
| {% code title="batching.clar" %} |
There was a problem hiding this comment.
Best to share the costs for bad and good in this doc
|
|
||
| ## Efficient Logic | ||
|
|
||
| Writing computationally efficient code reduces the `runtime` cost component and prevents reaching execution limits. |
|
|
||
| ### Right-Size Data Types | ||
|
|
||
| Smaller data types reduce read/write lengths. Use `buff` instead of `string-utf8` for identifiers or fixed-length hex data. |
There was a problem hiding this comment.
All data is fixed-length in Clarity
|
|
||
| ## Loops and Iterations | ||
|
|
||
| Clarity uses functional patterns like `fold`, `map`, and `filter` for iteration. These should be used cautiously. |
There was a problem hiding this comment.
Some example costs for map and fold might be helpful
| Use `define-read-only` for any operation that does not modify state. | ||
|
|
||
| {% hint style="info" %} | ||
| Read-only functions are "free" when called via API/RPC as they don't require an on-chain transaction. |
There was a problem hiding this comment.
api nodes also have limits.
Best to list the default limits for read-only
| Read-only functions are "free" when called via API/RPC as they don't require an on-chain transaction. | ||
| {% endhint %} | ||
|
|
||
| For complex frontend data needs, create a read-only "view" function that batches multiple data points into a single tuple return, reducing the number of network requests. |
There was a problem hiding this comment.
More read-only view functions come at the costs of higher deploy costs and higher read costs on contract-call execution.
|
|
||
| ```bash | ||
| # Run tests with cost analysis | ||
| clarinet test --costs |
3 participants
This PR introduces a new documentation guide: Gas Optimization for Clarity Smart Contracts. This guide provides developers with practical strategies to minimize transaction costs and optimize the performance of their contracts on the Stacks blockchain.
While based on standard optimization principles, the content has been written from scratch to align perfectly with the Stacks repository's styling and technical standards.
Key Features
Actionable Strategies: Detailed sections on minimizing storage hits (caching/batching), logic efficiency (early returns), and right-sizing data types.
GitBook Integration: Follows the repository's native styling using {% hint %} blocks and {% code %} titles for a consistent UI/UX.
Performance Patterns: Provides clear "Good" vs. "Bad" code examples to illustrate the impact of different Clarity implementations.
Tooling Guidance: Includes a dedicated section on measuring gas costs using Clarinet’s --costs analysis tool.
New File
docs/build/more-guides/gas-optimization.md