feat: expand error taxonomy with related errors, documentation links, protocol versioning, and contract examples - #383
Conversation
…oning, and examples
📝 WalkthroughWalkthroughThe taxonomy documentation now describes Schema v2.0. The TOML database adds enriched entries for ChangesEnhanced error taxonomy
Estimated code review effort: 2 (Simple) | ~10 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@taxonomy/enhanced_error_taxonomy.toml`:
- Around line 62-64: Update the UNDERFUNDED.protocol and HOST_FN_FAILED.protocol
blocks to explicitly define deprecated_in and removed_in as null, matching
ZERO_BALANCE.protocol and preserving consistent consumer-visible semantics.
- Around line 100-109: The taxonomy is incomplete: enhanced_error_taxonomy.toml
contains only three entries and examples instead of the promised 50+
contract-specific examples. Expand the existing error taxonomy sections with at
least 50 realistic, diverse examples tied to specific contracts and scenarios,
or explicitly mark the taxonomy as incomplete and track the remaining population
as a follow-up.
- Around line 48-56: Separate the taxonomy entries for insufficient source
funding and destination-account low reserve. Update error.UNDERFUNDED and the
related example so UNDERFUNDED represents CREATE_ACCOUNT_UNDERFUNDED, while the
minimum-reserve condition is mapped to a distinct LOW_RESERVE error entry. Apply
the same correction to the additional occurrence noted at lines 65–74,
preserving accurate descriptions and relationships.
- Around line 23-25: Replace the stale Stellar and Soroban documentation URLs in
the ZERO_BALANCE, and corresponding error documentation entries at the other
referenced sections, with verified live canonical pages for each specific error.
Ensure every URL resolves directly to the relevant error documentation rather
than a 404 or documentation homepage.
- Around line 37-44: Make the Soroban examples identified by ZERO_BALANCE,
UNDERFUNDED, and HOST_FN_FAILED either compilable self-contained contract
snippets or explicitly label them as pseudocode. For compilable examples,
replace undefined symbols and invalid patterns such as read_balance,
MIN_RESERVE, Error::..., and map_err on Option with valid storage access, error
definitions, and Soroban APIs, using valid panic_with_error! environment
references; apply the same treatment consistently across all three examples.
In `@taxonomy/README.md`:
- Around line 15-17: Clarify in taxonomy/README.md lines 15-17 which
protocol-version representation is canonical, and define the semantics of
deprecated_in and removed_in. In taxonomy/enhanced_error_taxonomy.toml line 8,
remove the duplicate representation or add schema validation enforcing equality
with the documented canonical value.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 106afe27-10e4-4a6f-803e-530e40d7bf5b
📒 Files selected for processing (2)
taxonomy/README.mdtaxonomy/enhanced_error_taxonomy.toml
| [error.ZERO_BALANCE.documentation] | ||
| stellar_docs_url = "https://developers.stellar.org/docs/encyclopedia/errors#zero-balance" | ||
| soroban_docs_url = "https://soroban.stellar.org/docs/reference/errors#zero-balance" |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Replace the documentation URLs with live canonical pages.
The three Stellar error URLs currently return 404, while the three Soroban error URLs redirect to the documentation homepage rather than an error reference. Consequently, the direct-documentation objective is not met. ()
Also applies to: 58-60, 93-95
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/enhanced_error_taxonomy.toml` around lines 23 - 25, Replace the
stale Stellar and Soroban documentation URLs in the ZERO_BALANCE, and
corresponding error documentation entries at the other referenced sections, with
verified live canonical pages for each specific error. Ensure every URL resolves
directly to the relevant error documentation rather than a 404 or documentation
homepage.
Source: MCP tools
| code_snippet = ''' | ||
| fn transfer(e: Env, from: Address, to: Address, amount: i128) { | ||
| let balance = read_balance(&e, from.clone()); | ||
| if balance < amount { | ||
| panic_with_error!(e, Error::ZeroBalance); | ||
| } | ||
| } | ||
| ''' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '1,160p' taxonomy/enhanced_error_taxonomy.tomlRepository: Toolbox-Lab/Grat
Length of output: 3809
🏁 Script executed:
sed -n '60,130p' taxonomy/enhanced_error_taxonomy.tomlRepository: Toolbox-Lab/Grat
Length of output: 1950
🏁 Script executed:
rg -n "code_snippet|panic_with_error!|contractimpl|HOST_FN_FAILED|ZERO_BALANCE|UNDERFUNDED" taxonomy README.md .Repository: Toolbox-Lab/Grat
Length of output: 4242
🏁 Script executed:
sed -n '1,120p' taxonomy/README.mdRepository: Toolbox-Lab/Grat
Length of output: 973
🌐 Web query:
Soroban panic_with_error! official example host function failure invalid arguments docs
💡 Result:
In Soroban, the panic_with_error! macro is used to halt contract execution and return a specific, defined error value to the caller, rather than crashing with an unhandled exception [1][2][3]. This approach is preferred over a standard panic! because it allows for structured error propagation [4][2]. Key characteristics and usage: 1. Purpose and Usage: The macro takes a reference to the environment (Env) and a contract-defined error value as arguments [1]. When called, it stops the contract execution immediately and propagates the provided error [2][3]. Example: panic_with_error!(&env, Error::Unauthorized); [2] 2. Handling Failures: If a contract calls a host function with invalid arguments or triggers an internal runtime error (e.g., bounds violation, arithmetic overflow), the host may trap the execution [4][5]. While these traps are often surfaced as generic HostError(WasmVm, InvalidAction) or similar errors, using panic_with_error! provides a clear, actionable way to signal intended failures [4]. 3. Interaction with Other Contracts: When a contract invokes another, errors returned via panic_with_error! are captured as part of the InvokeError enum, specifically within the Contract(u32) variant [6][2]. This contrasts with a standard panic! or a host trap, which may result in an Abort error variant [6][2]. 4. Debugging: Because standard panic! messages are not typically included in WASM builds, they can be difficult to debug [4]. Using panic_with_error! allows developers to define granular, semantic error codes that are preserved, making it easier to diagnose why a contract failed [4][2][3]. Diagnostic events are also recommended to provide additional context during simulation or testing [4]. If you encounter a HostError during development, it is generally recommended to fix the underlying contract logic or invocation arguments, increase unit testing coverage, and verify your implementation with simulateTransaction runs [4].
Citations:
- 1: https://docs.rs/soroban-sdk/latest/soroban%5Fsdk/macro.panic_with_error.html
- 2: https://mintlify.wiki/stellar/rs-soroban-sdk/guides/error-handling
- 3: https://developers.stellar.org/docs/build/smart-contracts/example-contracts/errors
- 4: https://developers.stellar.org/docs/learn/fundamentals/contract-development/errors-and-debugging/debugging-errors
- 5: https://docs.rs/soroban-env-host-zephyr/latest/soroban_env_host_zephyr/struct.Host.html
- 6: https://docs.rs/soroban-sdk/latest/soroban_sdk/enum.InvokeError.html
Make these Soroban examples compilable or label them as pseudocode.
ZERO_BALANCE, UNDERFUNDED, and HOST_FN_FAILED use undefined symbols and invalid patterns (read_balance, MIN_RESERVE, Error::..., map_err on Option), so they aren’t self-contained contract snippets. If they’re meant to be real examples, wrap them in minimal #[contractimpl] code with valid panic_with_error!(&env, ...) and storage usage; otherwise mark them as pseudocode.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/enhanced_error_taxonomy.toml` around lines 37 - 44, Make the Soroban
examples identified by ZERO_BALANCE, UNDERFUNDED, and HOST_FN_FAILED either
compilable self-contained contract snippets or explicitly label them as
pseudocode. For compilable examples, replace undefined symbols and invalid
patterns such as read_balance, MIN_RESERVE, Error::..., and map_err on Option
with valid storage access, error definitions, and Soroban APIs, using valid
panic_with_error! environment references; apply the same treatment consistently
across all three examples.
Source: MCP tools
| description = "The account balance is below the minimum reserve requirement." | ||
| code = "ERR_UNDERFUNDED" | ||
| since_protocol = 19 | ||
| category = "account" | ||
|
|
||
| [[error.UNDERFUNDED.related_errors]] | ||
| code = "ERR_ZERO_BALANCE" | ||
| relationship = "similar" | ||
| description = "Both indicate insufficient funds; underfunded is reserve-specific" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Separate UNDERFUNDED from low-reserve errors.
This entry and its example conflate insufficient funding with a destination account falling below the minimum reserve. Stellar distinguishes CREATE_ACCOUNT_UNDERFUNDED from CREATE_ACCOUNT_LOW_RESERVE; the example checks the latter condition while labeling it UNDERFUNDED. Remap the taxonomy or split these into distinct errors. (developers.stellar.org)
Also applies to: 65-74
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/enhanced_error_taxonomy.toml` around lines 48 - 56, Separate the
taxonomy entries for insufficient source funding and destination-account low
reserve. Update error.UNDERFUNDED and the related example so UNDERFUNDED
represents CREATE_ACCOUNT_UNDERFUNDED, while the minimum-reserve condition is
mapped to a distinct LOW_RESERVE error entry. Apply the same correction to the
additional occurrence noted at lines 65–74, preserving accurate descriptions and
relationships.
Source: MCP tools
| [error.UNDERFUNDED.protocol] | ||
| since_version = 19 | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Make protocol fields consistent across entries.
ZERO_BALANCE.protocol explicitly sets deprecated_in and removed_in to null, but the UNDERFUNDED and HOST_FN_FAILED protocol blocks omit both fields. Require explicit null values or document the meaning of an omitted field so consumers can distinguish “not deprecated” from “unknown.”
Also applies to: 97-99
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/enhanced_error_taxonomy.toml` around lines 62 - 64, Update the
UNDERFUNDED.protocol and HOST_FN_FAILED.protocol blocks to explicitly define
deprecated_in and removed_in as null, matching ZERO_BALANCE.protocol and
preserving consistent consumer-visible semantics.
| [[error.HOST_FN_FAILED.examples]] | ||
| contract = "defi" | ||
| scenario = "Calling a host function with invalid arguments" | ||
| code_snippet = ''' | ||
| fn deposit(e: Env, amount: i128) -> Result<(), Error> { | ||
| e.storage().instance().get::<Balance>(&DataKey::Balance) | ||
| .map_err(|_| Error::HostFnFailed)?; | ||
| Ok(()) | ||
| } | ||
| ''' |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Complete the promised taxonomy population.
This file contains only three error entries and three examples, while the PR objective calls for 50+ real-world contract-specific examples. Add the remaining coverage before claiming a fully populated taxonomy, or clearly track this as an incomplete follow-up.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/enhanced_error_taxonomy.toml` around lines 100 - 109, The taxonomy
is incomplete: enhanced_error_taxonomy.toml contains only three entries and
examples instead of the promised 50+ contract-specific examples. Expand the
existing error taxonomy sections with at least 50 realistic, diverse examples
tied to specific contracts and scenarios, or explicitly mark the taxonomy as
incomplete and track the remaining population as a follow-up.
| ### Since Protocol Version | ||
| - `[error.ERROR_CODE.protocol]` - Protocol version tracking | ||
| - Fields: `since_version`, `deprecated_in`, `removed_in` |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Make protocol version metadata unambiguous.
Both files define two representations of the same protocol version, creating a split-brain schema.
taxonomy/README.md#L15-L17: document whethersince_protocolorprotocol.since_versionis canonical, and definedeprecated_in/removed_insemantics.taxonomy/enhanced_error_taxonomy.toml#L8-L8: remove the duplicate field or enforce equality through schema validation.
📍 Affects 2 files
taxonomy/README.md#L15-L17(this comment)taxonomy/enhanced_error_taxonomy.toml#L8-L8
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@taxonomy/README.md` around lines 15 - 17, Clarify in taxonomy/README.md lines
15-17 which protocol-version representation is canonical, and define the
semantics of deprecated_in and removed_in. In
taxonomy/enhanced_error_taxonomy.toml line 8, remove the duplicate
representation or add schema validation enforcing equality with the documented
canonical value.
2 participants
Summary
Expand the Error Taxonomy Database with extensive metadata per Issue #381.
Changes
similar,precondition,cascaderelationships)enhanced_error_taxonomy.tomlwith three complete error entries:ZERO_BALANCE- with related errors, docs, protocol version, token contract exampleUNDERFUNDED- with reserve-specific related error, account creation exampleHOST_FN_FAILED- with cascade relationship, DeFi contract exampleFiles
taxonomy/enhanced_error_taxonomy.toml- Schema v2.0 with all new fieldstaxonomy/README.md- Schema documentationCloses #381
Summary by CodeRabbit
New Features
Documentation