refactor(security-practices): port security article code samples to Tolk, adjust dangling Tact stdlib references

[aigerimu]

closes #1186

Summary by CodeRabbit

• Documentation
  • Modernized security best-practice examples to a unified style and updated message/handler patterns.
  • Added explicit error handling (ErrCode/assert) across examples for arithmetic, replay protection, authorization, and signature checks.
  • Expanded guidance on signed-request front-running prevention (with a secure and insecure variant), persistent storage helpers, and seqno handling.
  • Clarified examples for gas handling, address/workchain validation, name collisions, type consistency, and return-value checks.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mintlify-ton-docs	🟢 Ready	View Preview	Apr 27, 2026, 6:54 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[coderabbitai]

Warning

Review limit reached

@novusnota, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 58 minutes and 26 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5ef03b2c-044b-4ffb-91f5-028b6a7ba1ab

📥 Commits

Reviewing files that changed from the base of the PR and between 9a5f1a9 and 03e5e23.

📒 Files selected for processing (2)

• content/contract-dev/techniques/security.mdx
• content/contract-dev/techniques/signing.mdx

📝 Walkthrough

Walkthrough

Converts security best-practice code samples in documentation from func/tact to tolk, updating handler names, storage API calls, message acceptance, and explicit error/assert patterns across numerous inline examples; no API or exported/public declarations were changed. (47 words)

Changes

Cohort / File(s)

Summary

Security Documentation & Code Examples contract-dev/techniques/security.mdx

All inline code examples converted from func/tact to tolk style. Updates include handler renames (recv_internal/recv_external → onInternalMessage/onExternalMessage), storage API swaps (get_data/set_data → contract.getData/contract.setData), message acceptance renames, introduction of ErrCode/assert-based explicit error handling, guarded arithmetic for transfers, replay-protection seqno logic, signed-context checks and persistent Storage helpers, and multiple illustrative examples (destruction race, replay, external validation, gas/excess handling, cross-contract exchange, address/workchain checks, name-collision, type consistency, and update authorization).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Hopping through snippets, tidy and brisk,

I swapped old tricks for a safer risk.
Tolks lined up, assertions in place,
Storage snug in its new little space.
A joyful twitch — docs polished with grace.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR successfully addresses issue #1186 by porting all code examples in the Security Best Practices article to Tolk format, as required.
Out of Scope Changes check	✅ Passed	All changes are directly related to the primary objective of converting security documentation code samples to Tolk; no out-of-scope modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately reflects the main change: porting security article code samples from Tact to Tolk while addressing outdated stdlib references.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch security-edits

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Thanks for the detailed security documentation updates in contract-dev/techniques/security.mdx: I have several suggestions to align language tags, phrasing, and terminology with the style guide; please apply the inline suggestions.

---

Per-comment submission: 9 posted, 2 failed.

Unposted inline comments (raw text):

• contract-dev/techniques/security.mdx:L88-L90

  [HIGH] Wikipedia link used as primary replay-attack explanation

  Lines 88–90 describe replay protection and link “reusing a previous message” to Wikipedia’s Replay_attack article as the only explanation of the concept. The extended style guide prefers internal documentation or official specs for normative explanations in security-sensitive sections, and allows Wikipedia only as non‑normative background. As written, the sentence relies on Wikipedia as the primary definition for a security concept, which conflicts with that guidance.

  Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

• contract-dev/techniques/security.mdx:L387-L395

  [HIGH] Non-standard tolk fences in address-format example

  The “Address formats” example around lines 387–395 uses a tolk fenced block to show raw, bounceable, and non-bounceable addresses and a forceChain call. This continues the file-wide pattern of using an undocumented language tag. To align with the extended style guide, examples showing code-like configuration or API usage should employ a recognized highlighter, not a bespoke tag.

  Please leave a reaction 👍/👎 to this suggestion to improve future reviews for everyone!

[github-actions]

Thanks for the updates in contract-dev/techniques/security.mdx: please apply the inline suggestion to keep the example wording neutral and consistent with the docs style.

[coderabbitai]

Actionable comments posted: 4

♻️ Duplicate comments (1)

contract-dev/techniques/security.mdx (1)

544-552: ⚠️ Potential issue | 🟠 Major

This section is not fully ported to Tolk yet.

The vulnerable snippet still uses a func fence (Line 546) while the paired secure snippet is tolk. For this PR’s objective (“port code samples to Tolk”), this section should be fully converted for consistency.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/security.mdx` around lines 544 - 552, The vulnerable
snippet uses a `func` code fence while the paired secure snippet is `tolk`, so
update the vulnerable example to use a `tolk` fence and ensure both examples are
fully ported to Tolk; locate the snippet containing `infoDict.delete(index);`
and replace the surrounding fence language from `func` to `tolk`, then verify
the secure implementation block is also a complete Tolk block (matching fence
type and content) so the section is fully converted and consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@contract-dev/techniques/security.mdx`:
- Around line 340-342: The Vote struct's votes field is declared as a signed int
(Vote.votes : int32) but Storage.votes is unsigned (Storage.votes : uint32),
causing a signed/unsigned mismatch at the addition site (storage.votes +=
msg.votes); change Vote.votes to uint32 to match Storage.votes and ensure the
addition uses the same unsigned type throughout (update the Vote struct
declaration and any references to Vote.votes accordingly).
- Around line 95-103: The Tolk external-message handlers (function
onExternalMessage and similar examples) call the wrong API: replace the call to
acceptMessage() with the documented acceptExternalMessage() to correctly accept
incoming external messages; update each usage in the Tolk code blocks that
currently call acceptMessage() so they call acceptExternalMessage() instead
(e.g., inside onExternalMessage and the two other external-message examples).
- Around line 270-277: The example uses msg.send(128) which is
SendRemainingBalance and will drain the contract; update the example to use a
non-draining send mode (e.g., msg.send(0) for a regular send or msg.send(3) to
forward fees) or explicitly document why draining is intended; locate the
createMessage call and the msg.send(128) invocation (and note the presence of
seqno replay protection) and replace the 128 mode or add a clear comment
explaining the deliberate use of SendRemainingBalance.
- Around line 64-71: The secure-example snippets use the outdated Tolk signature
onInternalMessage(msgValue: int, inMsgFull: cell, inMsgBody: slice) and the bare
sender variable; update both occurrences (the snippets handling empty message
and the later similar block) to the modern entrypoint signature fun
onInternalMessage(in: InMessage) and replace any use of sender with
in.senderAddress; adjust any references to message parts to use fields on the
InMessage (e.g., in.body or in.raw) so sendRawMessage is called with the correct
in-derived values and types (keep the same destruction logic but sourced from
in).

---

Duplicate comments:
In `@contract-dev/techniques/security.mdx`:
- Around line 544-552: The vulnerable snippet uses a `func` code fence while the
paired secure snippet is `tolk`, so update the vulnerable example to use a
`tolk` fence and ensure both examples are fully ported to Tolk; locate the
snippet containing `infoDict.delete(index);` and replace the surrounding fence
language from `func` to `tolk`, then verify the secure implementation block is
also a complete Tolk block (matching fence type and content) so the section is
fully converted and consistent.

🪄 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

Run ID: ca165394-0a02-4b9f-90ad-50f083258940

📥 Commits

Reviewing files that changed from the base of the PR and between 8d4f473 and 47416ab.

📒 Files selected for processing (1)

• contract-dev/techniques/security.mdx

[github-actions]

Thanks for the updates in contract-dev/techniques/security.mdx: please apply the couple of inline suggestions to tighten the security wording and clean up the example snippet.

---

Per-comment submission: 1 posted, 1 failed.

Unposted inline comments (raw text):

• contract-dev/techniques/security.mdx:L181-L183

  [HIGH] Vague phrase “not entirely foolproof” in security guidance

  The guidance on using built-in random functions ends with the phrase “it is still not entirely foolproof,” which is vague and emotionally toned rather than technically precise. This conflicts with the style guidance against dramatic or marketing-style intensifiers and does not clearly describe what risks remain. Replacing this phrase with a concrete statement about residual risk and limitations of on-chain randomness improves clarity and keeps the focus on actionable security considerations. The surrounding context about secure random numbers supports rephrasing without changing the underlying recommendation.

  ```  …(truncated)
  

[novusnota]

note to self: also check for Tact-specific functions/structs on pages in foundations, tvm, contract-dev, and standard sections — replace each occurance with idiomatic Tolk equivalents

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 21, 2026 10:38pm

Resolved