Skip to content

docs: surface sub-parser trust model on the using-words-from pragma (#496) #508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thedavidmeister merged 1 commit into from
May 14, 2026
Merged

docs: surface sub-parser trust model on the using-words-from pragma (#496) #508

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions src/lib/parse/LibParsePragma.sol
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,32 @@ bytes32 constant PRAGMA_KEYWORD_MASK = bytes32(~((1 << (32 - PRAGMA_KEYWORD_BYTE
/// @title LibParsePragma
/// @notice Parses the `using-words-from` pragma from Rainlang source text
/// and registers sub-parser contract addresses on the parse state.
///
/// @dev Sub-parsers are external contracts called during parse to resolve
/// words this parser doesn't recognise. They are invoked at parse time,
/// receive parser state context, and return bytecode that is spliced
/// into the result. `integrityCheck2` then validates the assembled
/// bytecode's structural and stack-tracking correctness.
///
/// Trust model: sub-parsers run under the same trust assumption as the
/// expression author. A buggy or malicious sub-parser can:
/// - emit syntactically valid bytecode that nevertheless encodes
/// behaviour the user did not write (e.g. wrong opcode index, swapped
/// inputs);
/// - emit constants of its choosing, including ones that look like
/// addresses the user did not specify;
/// - decline to parse legitimate input and revert the entire expression.
///
/// The integrity check on the assembled bytecode catches stack-shape and
/// pointer-bounds violations. It does NOT verify semantic equivalence
/// between the source text and the bytecode the sub-parser produced —
/// that's a function of the sub-parser's correctness, not the
/// interpreter's.
///
/// Integrators MUST vet every sub-parser address they accept (or that
/// users include via the `using-words-from` pragma) under the same trust
/// model they apply to the expression itself. An expression with a
/// hostile sub-parser is equivalent to a hostile expression.
Comment on lines +35 to +53
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 14, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add explicit NatSpec tags to each paragraph in this doc block.

Line 35-Line 53 uses untagged /// lines after an explicit-tag block; per repo rule, those lines are not treated as continuations. Please tag each paragraph explicitly (e.g., @dev or @custom:security).

Proposed compliant rewrite 
-/// Trust model: sub-parsers run under the same trust assumption as the
-/// expression author. A buggy or malicious sub-parser can:
+/// `@dev` Trust model: sub-parsers run under the same trust assumption as the
+/// expression author. A buggy or malicious sub-parser can:
 /// - emit syntactically valid bytecode that nevertheless encodes
 ///   behaviour the user did not write (e.g. wrong opcode index, swapped
 ///   inputs);
 /// - emit constants of its choosing, including ones that look like
 ///   addresses the user did not specify;
 /// - decline to parse legitimate input and revert the entire expression.
 ///
-/// The integrity check on the assembled bytecode catches stack-shape and
+/// `@dev` The integrity check on the assembled bytecode catches stack-shape and
 /// pointer-bounds violations. It does NOT verify semantic equivalence
 /// between the source text and the bytecode the sub-parser produced —
 /// that's a function of the sub-parser's correctness, not the
 /// interpreter's.
 ///
-/// Integrators MUST vet every sub-parser address they accept (or that
+/// `@dev` Integrators MUST vet every sub-parser address they accept (or that
 /// users include via the `using-words-from` pragma) under the same trust
 /// model they apply to the expression itself. An expression with a
 /// hostile sub-parser is equivalent to a hostile expression.

As per coding guidelines, “In NatSpec doc blocks containing explicit tags (e.g., @title), all entries must be explicitly tagged; untagged lines do not continue the previous tag”.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
/// Trust model: sub-parsers run under the same trust assumption as the
/// expression author. A buggy or malicious sub-parser can:
/// - emit syntactically valid bytecode that nevertheless encodes
/// behaviour the user did not write (e.g. wrong opcode index, swapped
/// inputs);
/// - emit constants of its choosing, including ones that look like
/// addresses the user did not specify;
/// - decline to parse legitimate input and revert the entire expression.
///
/// The integrity check on the assembled bytecode catches stack-shape and
/// pointer-bounds violations. It does NOT verify semantic equivalence
/// between the source text and the bytecode the sub-parser produced —
/// that's a function of the sub-parser's correctness, not the
/// interpreter's.
///
/// Integrators MUST vet every sub-parser address they accept (or that
/// users include via the `using-words-from` pragma) under the same trust
/// model they apply to the expression itself. An expression with a
/// hostile sub-parser is equivalent to a hostile expression.
/// `@dev` Trust model: sub-parsers run under the same trust assumption as the
/// expression author. A buggy or malicious sub-parser can:
/// - emit syntactically valid bytecode that nevertheless encodes
/// behaviour the user did not write (e.g. wrong opcode index, swapped
/// inputs);
/// - emit constants of its choosing, including ones that look like
/// addresses the user did not specify;
/// - decline to parse legitimate input and revert the entire expression.
///
/// `@dev` The integrity check on the assembled bytecode catches stack-shape and
/// pointer-bounds violations. It does NOT verify semantic equivalence
/// between the source text and the bytecode the sub-parser produced —
/// that's a function of the sub-parser's correctness, not the
/// interpreter's.
///
/// `@dev` Integrators MUST vet every sub-parser address they accept (or that
/// users include via the `using-words-from` pragma) under the same trust
/// model they apply to the expression itself. An expression with a
/// hostile sub-parser is equivalent to a hostile expression.
🤖 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 `@src/lib/parse/LibParsePragma.sol` around lines 35 - 53, The NatSpec doc block
in LibParsePragma.sol (the multi-paragraph comment at the top of the file
describing the trust model) mixes explicit tags with untagged /// lines, which
are not treated as continuations; revise that comment so each paragraph is
explicitly tagged (for example, prepend `@dev` to implementation/behavior
paragraphs and `@custom`:security to threat-model/security paragraphs) so every
line is a valid NatSpec entry and no untagged /// lines remain.

library LibParsePragma {
using LibParseError for ParseState;
using LibParseInterstitial for ParseState;
Expand Down
Loading