Skip to content

feat(contract-dev): edit upgrade contracts to fit styleguide#2110

Open
kay-is wants to merge 13 commits intomainfrom
upgrade-contracts-style
Open

feat(contract-dev): edit upgrade contracts to fit styleguide#2110
kay-is wants to merge 13 commits intomainfrom
upgrade-contracts-style

Conversation

@kay-is
Copy link
Copy Markdown
Collaborator

@kay-is kay-is commented Apr 22, 2026

closes #2109

Summary by CodeRabbit

  • Documentation
    • Clarified upgradeability narrative and when address preservation is required
    • Rewrote "How upgrades work" to distinguish code activation after transactions vs data replacement during execution
    • Added explicit guidance on insufficient-funds behavior and a caution that certain send options can leave a contract unusable
    • Converted delayed/hot sections into action-oriented "pattern" sections, revised flows, migration risk warnings, and updated examples and links

Copilot AI review requested due to automatic review settings April 22, 2026 10:27
@kay-is kay-is requested a review from a team as a code owner April 22, 2026 10:27
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented Apr 22, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Rewrote the upgrades guide to clarify when address‑preserving upgrades are required, distinguish timing semantics of setCodePostponed() vs setData(), restructure basic/delayed/hot upgrade patterns, and strengthen migration-risk wording. Documentation-only changes.

Changes

Cohort / File(s) Summary
Upgrades guide (documentation)
contract-dev/techniques/upgrades.mdx
Comprehensive rewrite: reframed motivation and examples to tie address‑preserving upgrades to referenced contracts; clarified setCodePostponed() (code becomes available after transaction completion) vs setData() (storage replaced during compute, before transaction end); merged and simplified upgrade flow into single transaction steps; restructured basic/delayed/hot patterns and example narratives; strengthened migration-risk guidance (insufficient funds aborts, SendIgnoreErrors caveat, abort-on-throw risk); renamed oldStorageOldStorage in examples and adjusted example link text.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 I hopped through paragraphs, nibbling vague and terse,

I straightened timing, smoothed the steps, and trimmed a bit of verse,
Now upgrades march in clearer time, no tangled seam or snare,
A tiny hop, a tidy guide — proceed with gentle care.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title directly describes the main change: editing documentation to conform to the project's style guide, which aligns with the file modifications and PR objectives.
Linked Issues check ✅ Passed The pull request fulfills issue #2109 by comprehensively revising the upgrades documentation's content, wording, structure, and formatting to conform to style guide standards.
Out of Scope Changes check ✅ Passed All changes are scoped to documentation style improvements in the upgrades guide; no unrelated code modifications or out-of-scope changes are present.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ 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 upgrade-contracts-style

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

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

@github-actions

This comment has been minimized.

@kay-is kay-is marked this pull request as draft April 22, 2026 10:28
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 6

🤖 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/upgrades.mdx`:
- Line 43: Remove the unnecessary comma in the sentence "An admin sends an
upgrade message to the contract, that contains new code, data, or both." by
deleting the comma after "contract" so the restrictive clause reads "that
contains new code, data, or both" directly following "contract"; update the
sentence in the upgrades.mdx content where that exact line appears.
- Line 413: Fix the missing verb in the sentence that currently reads "The
migration logic these steps:" by changing it to a complete phrase such as "The
migration logic follows these steps:" or "The migration logic includes these
steps:" so the sentence is grammatically correct (locate the phrase "The
migration logic these steps:" and replace with the chosen corrected version).
- Line 12: The sentence currently reads "(DEX), that are referenced by many
other contracts" with an incorrect comma; edit the line containing "The upgrade
pattern is also required for [vanity](/contract-dev/vanity) contracts and
protocols such as distributed exchanges (DEX), that are referenced by many other
contracts." to remove the comma after "(DEX)" so it reads "(DEX) that are
referenced by many other contracts."
- Line 32: Update the sentence "Use delayed upgrades to allow users to react to
compromised admin keys or unwanted update." by changing the singular noun
"update" to the plural "updates" so it reads "...or unwanted updates" to match
the plural "admin keys" and maintain parallel structure; locate the sentence in
the content of the techniques/upgrades section (the line starting with "Use
delayed upgrades to allow users...") and replace "update" with "updates".
- Line 415: Update the example abbreviation in the list item text that currently
reads "e.g, `oldStorage` with `adminAddress` and `counter`" to use the correct
punctuation "e.g.," so the phrase becomes "e.g., `oldStorage` with
`adminAddress` and `counter`" in the sentence starting "1. Loading the storage
using the old structure...".
- Line 106: Replace the article "an" with "a" before the symbol RequestUpgrade
in the sentence "An admin sends an `RequestUpgrade` message..." so it reads "A
admin sends a `RequestUpgrade` message..." — update the text around the
identifier RequestUpgrade accordingly to use the correct indefinite article.
🪄 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: 625f5522-98ab-4aba-a90e-430388e1f3fe

📥 Commits

Reviewing files that changed from the base of the PR and between a4a7393 and 3be783f.

📒 Files selected for processing (1)
  • contract-dev/techniques/upgrades.mdx

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Edits the “Upgrading contracts” technique guide to better match the repository’s documentation style guide, improving structure, clarity, and callout usage.

Changes:

  • Rewrites the introduction and examples to improve readability and align phrasing with the style guide.
  • Restructures the “basic”, “delayed”, and “hot” upgrade pattern sections with clearer step-by-step descriptions and headings.
  • Standardizes/clarifies <Aside> callouts (titles/types) and refines surrounding explanatory text.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx
Comment thread contract-dev/techniques/upgrades.mdx
@github-actions
Copy link
Copy Markdown
Contributor

Thanks for the thoughtful improvements to contract-dev/techniques/upgrades.mdx: I’ve left several targeted suggestions to tighten grammar, align with the docs style, and clarify upgrade guidance—please apply the inline suggestions where they match your intent.


Per-comment submission: 10 posted, 1 failed.

Unposted inline comments (raw text):

  • contract-dev/techniques/upgrades.mdx:L28-L34

    [HIGH] Personal and reader-facing pronouns in ethics aside

    Lines 32–34 in the ethics aside use “allow users to react” and “You can find more information… in the Trail of Bits blog”, which address the reader as “you” and frame users as belonging to the reader. The extended style guide for this docs set discourages authorial “we/our” and direct second-person pronouns for guidance, preferring neutral descriptions of actions and actors. This section is a safety-related ethics callout, so overly conversational framing can dilute clarity about who is responsible for reacting to risks.

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

@github-actions

This comment has been minimized.

@kay-is
Copy link
Copy Markdown
Collaborator Author

kay-is commented Apr 22, 2026

/review

Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

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

Thanks for the updates to contract-dev/techniques/upgrades.mdx: I have a couple of suggestions to align the wording with the documentation style guide, so please apply the inline suggestions.

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
@mintlify
Copy link
Copy Markdown

mintlify Bot commented Apr 22, 2026

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

Project Status Preview Updated (UTC)
mintlify-ton-docs 🟢 Ready View Preview Apr 22, 2026, 11:46 AM

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

@kay-is
Copy link
Copy Markdown
Collaborator Author

kay-is commented Apr 22, 2026

/review

Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

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

Thanks for the polish on contract-dev/techniques/upgrades.mdx: I have a couple of suggestions there to tighten list style and step wording, so please apply the inline suggestions.

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx
@kay-is
Copy link
Copy Markdown
Collaborator Author

kay-is commented Apr 22, 2026

/review

Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

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

Thanks for the thoughtful updates in contract-dev/techniques/upgrades.mdx: please apply the couple of inline suggestions to tighten the upgrade behavior description and align punctuation with the documented style.

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
@kay-is kay-is marked this pull request as ready for review April 22, 2026 12:42
Copy link
Copy Markdown
Contributor

@github-actions github-actions Bot left a comment

Choose a reason for hiding this comment

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

Thanks for the updates in contract-dev/techniques/upgrades.mdx: please apply the one inline suggestion to align the procedural steps with the documented style.

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 3

♻️ Duplicate comments (2)
contract-dev/techniques/upgrades.mdx (2)

411-418: ⚠️ Potential issue | 🟡 Minor

Clean up remaining style-guide polish items.

Line 411 is still wordy, Line 417 has an unnecessary comma, and Line 426 places the period inside a non-quoted parenthetical.

Proposed wording
-The new version of `hotUpgradeData()` function is what is called after the code was switched with `setTvmRegisterC3()` and performs the migration.
+The new version of the `hotUpgradeData()` function runs after the code is switched with `setTvmRegisterC3()` and performs the migration.
-1. Reorder fields, to move `counter` before `adminAddress`.
+1. Reorder fields to move `counter` before `adminAddress`.
-- The contract receives frequent state updates (DEX pools, oracles, lending protocols.)
+- The contract receives frequent state updates (DEX pools, oracles, lending protocols).

Also applies to: 426-426

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` around lines 411 - 418, Shorten and
simplify the sentence describing hotUpgradeData() to be more concise (refer to
the sentence mentioning hotUpgradeData() and setTvmRegisterC3()), remove the
unnecessary trailing comma in the sentence that currently ends with a comma (the
line referencing the migration steps), and move the period outside the
parentheses where a sentence currently ends with the period inside a non-quoted
parenthetical (the sentence around contract.setData()); keep the meaning
identical but apply the proposed wording style polish to those three spots.

102-102: ⚠️ Potential issue | 🟡 Minor

Replace remaining contractions in technical prose.

Use “do not” and “That is” to keep the style formal and consistent.

Proposed wording
-The delay allows users to withdraw funds or exit positions if they don't trust the upgrade or if an admin account is compromised.
+The delay allows users to withdraw funds or exit positions if they do not trust the upgrade or if an admin account is compromised.
-The contract never executes the original `hotUpgradeData()` function because it is immediately replaced by the new code during the upgrade. The new code defines the actual migration logic. That's why the migration function must have a `method_id` that's stable across versions, so the runtime can call it after the upgrade.
+The contract never executes the original `hotUpgradeData()` function because it is immediately replaced by the new code during the upgrade. The new code defines the actual migration logic. That is why the migration function must have a `method_id` that is stable across versions, so the runtime can call it after the upgrade.

Also applies to: 315-315

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` at line 102, The paragraph describing
the delayed upgrade pattern contains informal contractions; replace "don't" with
"do not" and "that's" with "That is" (and scan the rest of upgrades.mdx for any
remaining contractions to convert to their expanded forms) so the technical
prose remains formal and consistent—update the sentence about users withdrawing
funds or exiting positions and any other sentences using contractions
accordingly.
🤖 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/upgrades.mdx`:
- Around line 111-112: Clarify the pending-request cleanup: state that when a
request is approved the contract calls setCodePostponed() and then either
removes CurrentRequest from storage (if no replacement data is provided) or, if
setData() is given a full replacement cell, that replacement cell must already
encode the new storage state without any pending CurrentRequest entry; update
the text to explicitly mention both branches and reference CurrentRequest,
setData(), and setCodePostponed() so readers know where cleanup must happen.
- Line 241: Update the inaccurate sentence about failed migrations in the
upgrades doc: replace the claim "If the migration function fails, the contract
becomes unusable" with a precise statement that if hotUpgradeData() (the
migration function) throws during compute, the entire transaction aborts and no
state changes are applied (the contract remains unchanged), and clarify the real
risk is a migration that succeeds but writes invalid storage, which can corrupt
the contract; modify the paragraph around the hotUpgradeData() explanation
accordingly so it mentions both the abort-on-throw behavior and the true danger
of successful-but-invalid migrations.
- Around line 47-48: Update the wording to state that set_code is applied during
the action phase as part of the sequential transaction phases rather than "after
the transaction completes"; specifically replace the sentence that says "apply
the new code during the action phase after the transaction completes" with a
clear line like: "apply the new code during the action phase — set_code is
processed as part of the transaction's action phase and the new code becomes
active only after that action phase succeeds." Reference the terms set_code and
action phase when making the edit.

---

Duplicate comments:
In `@contract-dev/techniques/upgrades.mdx`:
- Around line 411-418: Shorten and simplify the sentence describing
hotUpgradeData() to be more concise (refer to the sentence mentioning
hotUpgradeData() and setTvmRegisterC3()), remove the unnecessary trailing comma
in the sentence that currently ends with a comma (the line referencing the
migration steps), and move the period outside the parentheses where a sentence
currently ends with the period inside a non-quoted parenthetical (the sentence
around contract.setData()); keep the meaning identical but apply the proposed
wording style polish to those three spots.
- Line 102: The paragraph describing the delayed upgrade pattern contains
informal contractions; replace "don't" with "do not" and "that's" with "That is"
(and scan the rest of upgrades.mdx for any remaining contractions to convert to
their expanded forms) so the technical prose remains formal and
consistent—update the sentence about users withdrawing funds or exiting
positions and any other sentences using contractions accordingly.
🪄 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: 4ca949e7-0934-435b-a961-6be508440df9

📥 Commits

Reviewing files that changed from the base of the PR and between 3be783f and 20f7cf3.

📒 Files selected for processing (1)
  • contract-dev/techniques/upgrades.mdx

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

Actionable comments posted: 2

♻️ Duplicate comments (1)
contract-dev/techniques/upgrades.mdx (1)

108-108: ⚠️ Potential issue | 🟡 Minor

Remove unnecessary comma before "before".

The subordinate clause "before accepting approvals" is restrictive and shouldn't be preceded by a comma.

📝 Proposed fix
-1. The contract waits for the specified timeout, before accepting approvals.
+1. The contract waits for the specified timeout before accepting approvals.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` at line 108, Remove the unnecessary
comma in the sentence "The contract waits for the specified timeout, before
accepting approvals." by deleting the comma before "before" so it reads "The
contract waits for the specified timeout before accepting approvals." Ensure the
corrected sentence replaces the original in the file where that exact line
appears.
🤖 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/upgrades.mdx`:
- Line 417: The sentence contains an unnecessary comma before the infinitive
phrase; remove the comma so it reads "Reorder fields to move `counter` before
`adminAddress`" (reference the words `counter` and `adminAddress` to locate the
sentence and delete the comma before "to").
- Line 315: The sentence contains contractions—change "That's" and "that's" to
their expanded forms ("That is" and "that is") in the paragraph explaining
hotUpgradeData() and method_id so the documentation follows the no-contractions
style; ensure references to hotUpgradeData() and method_id remain unchanged and
read naturally after expansion.

---

Duplicate comments:
In `@contract-dev/techniques/upgrades.mdx`:
- Line 108: Remove the unnecessary comma in the sentence "The contract waits for
the specified timeout, before accepting approvals." by deleting the comma before
"before" so it reads "The contract waits for the specified timeout before
accepting approvals." Ensure the corrected sentence replaces the original in the
file where that exact line appears.
🪄 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: 50973eb2-1908-4005-9539-b46d733124eb

📥 Commits

Reviewing files that changed from the base of the PR and between 20f7cf3 and fc3fefb.

📒 Files selected for processing (1)
  • contract-dev/techniques/upgrades.mdx

Comment thread contract-dev/techniques/upgrades.mdx Outdated
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

♻️ Duplicate comments (3)
contract-dev/techniques/upgrades.mdx (3)

119-120: ⚠️ Potential issue | 🟠 Major

Align delayed-upgrade steps with the actual cleanup branches.

The list says the contract always removes the pending request, but the example only does that in the no-replacement-data branch. Document both branches explicitly so readers do not implement incorrect cleanup logic.

📝 Proposed wording
-1. If the request is approved, the contract schedules new code with `setCodePostponed()` and upgrades data with `setData()`.
-1. The contract removes the pending request from storage.
+1. If the request is approved, the contract schedules new code with `setCodePostponed()` and upgrades data with `setData()`.
+1. If no replacement data is supplied, remove the pending request from current storage. If replacement data is supplied, that data must already encode the post-upgrade storage state without a pending request.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` around lines 119 - 120, The
documentation currently implies the contract always removes the pending request
after approval but the example only removes it in the no-replacement-data
branch; update the steps to match actual cleanup branches by explicitly
describing both flows: one branch where setCodePostponed() is called and
setData() is not used (and the pending request is removed immediately), and the
other branch where setCodePostponed() and setData() are used together and the
pending request is removed in that branch once data replacement completes;
reference the functions setCodePostponed() and setData() and adjust the numbered
list to show both cleanup paths so implementers replicate the correct logic.

50-57: ⚠️ Potential issue | 🟠 Major

Qualify revert behavior by send mode to avoid a contradictory safety claim.

Line 50 states an absolute abort/no-state-change outcome, while Lines 55-56 explicitly describe a SendIgnoreErrors path that can still commit storage and fail code replacement. Please make the default/error-mode distinction explicit in the main paragraph.

📝 Proposed wording
-The upgrade runs in a single transaction. New code becomes active after the transaction completes, and new data is available when the transaction ends. If the message does not provide enough Toncoin to run both the compute phase and the action phase, the entire transaction is aborted and no state changes from the upgrade are applied. Test the upgrade script to estimate gas requirements, and send enough Toncoin to execute the full upgrade transaction.
+The upgrade runs in a single transaction. New code becomes active after the transaction completes, and new data is available when the transaction ends. If the message does not provide enough Toncoin to run both phases, the result depends on send mode: without ignore-errors behavior, the transaction aborts and upgrade state changes are not applied; with `SendIgnoreErrors`, action-phase failures can be ignored, which may leave updated storage with old code. Test the upgrade script to estimate gas requirements, and send enough Toncoin to execute the full upgrade transaction.
According to current TON docs, when using ignore-errors send modes (for example SendIgnoreErrors), can compute-phase storage writes from setData() remain applied if a set_code action in action phase fails due to insufficient funds?
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` around lines 50 - 57, Update the main
paragraph to explicitly distinguish default/error send-mode behavior from
ignore-errors modes: state that under normal send modes (no ignore-errors) the
upgrade runs in a single transaction so if funds are insufficient the entire
transaction is aborted and no state changes are applied; but note that with
ignore-errors modes (e.g., SendIgnoreErrors) compute-phase storage writes (e.g.,
setData()) can still be committed while a subsequent action-phase code
replacement (e.g., set_code) may fail, leaving new storage with old code. Also
ensure the caution aside references these terms (SendIgnoreErrors, compute
phase, action phase, setData, set_code) so readers understand the exception.

434-434: ⚠️ Potential issue | 🟡 Minor

Move terminal punctuation outside the parenthesis in the list item.

Line 434 currently ends with protocols.), which is inconsistent with surrounding prose punctuation.

📝 Proposed wording
-- The contract receives frequent state updates (DEX pools, oracles, lending protocols.)
+- The contract receives frequent state updates (DEX pools, oracles, lending protocols).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` at line 434, The list item text "The
contract receives frequent state updates (DEX pools, oracles, lending
protocols.)" has the period inside the closing parenthesis; update that phrase
to move the terminal period outside the parenthesis so it reads "The contract
receives frequent state updates (DEX pools, oracles, lending protocols)." —
locate the string and adjust the punctuation accordingly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@contract-dev/techniques/upgrades.mdx`:
- Around line 119-120: The documentation currently implies the contract always
removes the pending request after approval but the example only removes it in
the no-replacement-data branch; update the steps to match actual cleanup
branches by explicitly describing both flows: one branch where
setCodePostponed() is called and setData() is not used (and the pending request
is removed immediately), and the other branch where setCodePostponed() and
setData() are used together and the pending request is removed in that branch
once data replacement completes; reference the functions setCodePostponed() and
setData() and adjust the numbered list to show both cleanup paths so
implementers replicate the correct logic.
- Around line 50-57: Update the main paragraph to explicitly distinguish
default/error send-mode behavior from ignore-errors modes: state that under
normal send modes (no ignore-errors) the upgrade runs in a single transaction so
if funds are insufficient the entire transaction is aborted and no state changes
are applied; but note that with ignore-errors modes (e.g., SendIgnoreErrors)
compute-phase storage writes (e.g., setData()) can still be committed while a
subsequent action-phase code replacement (e.g., set_code) may fail, leaving new
storage with old code. Also ensure the caution aside references these terms
(SendIgnoreErrors, compute phase, action phase, setData, set_code) so readers
understand the exception.
- Line 434: The list item text "The contract receives frequent state updates
(DEX pools, oracles, lending protocols.)" has the period inside the closing
parenthesis; update that phrase to move the terminal period outside the
parenthesis so it reads "The contract receives frequent state updates (DEX
pools, oracles, lending protocols)." — locate the string and adjust the
punctuation accordingly.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 47d0b8bb-1434-449b-b181-5c151ff6f77b

📥 Commits

Reviewing files that changed from the base of the PR and between fc3fefb and 3aa9f64.

📒 Files selected for processing (1)
  • contract-dev/techniques/upgrades.mdx

@kay-is kay-is requested a review from delovoyhomie April 29, 2026 09:56
Comment thread contract-dev/techniques/upgrades.mdx Outdated
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

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

♻️ Duplicate comments (2)
contract-dev/techniques/upgrades.mdx (2)

119-120: ⚠️ Potential issue | 🟠 Major

Fix the delayed-flow cleanup step to match actual branches.

Line 120 implies unconditional pending-request removal, but the example only clears CurrentRequest when no replacement data is provided. This is misleading unless replacement data is guaranteed to encode cleanup.

Proposed wording
-1. The contract removes the pending request from storage.
+1. If no replacement data is provided, the contract removes the pending request from current storage. If replacement data is provided, that data must already encode the post-upgrade storage state (without a pending request).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` around lines 119 - 120, The doc text
incorrectly states that the contract unconditionally removes the pending request
after approval; update the wording to reflect the actual control flow: explain
that when approved the contract calls setCodePostponed() and setData(), and only
clears CurrentRequest if the replacement data does not itself encode cleanup
(i.e., the example clears CurrentRequest only when no replacement data is
provided). Reference the symbols setCodePostponed(), setData(), and
CurrentRequest so readers understand the conditional cleanup behavior and match
the example branches.

50-57: ⚠️ Potential issue | 🟠 Major

Clarify default-vs-flagged behavior for failed action phase.

Line 50 says failure “aborts” with no state changes, while Line 55 explains SendIgnoreErrors can still commit storage and skip code update. Make Line 50 explicitly “by default” to avoid contradictory guidance in a safety-critical section.

In TON transaction semantics, when `setData()` runs in compute phase and `setCodePostponed()` fails in action phase due to insufficient funds, what is the default behavior, and how does `SendIgnoreErrors` (flag 2) change whether compute-phase storage updates persist?
Proposed wording
-The upgrade runs in a single transaction. New code becomes active after the transaction completes, and new data is available when the transaction ends. If the message does not provide enough Toncoin to run both the compute phase and the action phase, the entire transaction is aborted and no state changes from the upgrade are applied.
+The upgrade runs in a single transaction. New code becomes active after the transaction completes, and new data is available when the transaction ends. By default, if the message does not provide enough Toncoin to run both the compute phase and the action phase, the transaction is aborted and no upgrade state changes are applied.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@contract-dev/techniques/upgrades.mdx` around lines 50 - 57, Update the
wording to clarify default vs flagged behavior: change the sentence that says
the transaction "aborts and no state changes from the upgrade are applied" to
explicitly state "by default the transaction aborts and no state changes are
applied," and add one short sentence explaining the exception: if the message
uses the SendIgnoreErrors flag (flag 2) then compute-phase effects such as
setData() can persist even when the action-phase setCodePostponed() fails due to
insufficient funds; mention compute phase vs action phase semantics and
reference SendIgnoreErrors, setData(), and setCodePostponed() so readers
understand the flagged behavior difference.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Duplicate comments:
In `@contract-dev/techniques/upgrades.mdx`:
- Around line 119-120: The doc text incorrectly states that the contract
unconditionally removes the pending request after approval; update the wording
to reflect the actual control flow: explain that when approved the contract
calls setCodePostponed() and setData(), and only clears CurrentRequest if the
replacement data does not itself encode cleanup (i.e., the example clears
CurrentRequest only when no replacement data is provided). Reference the symbols
setCodePostponed(), setData(), and CurrentRequest so readers understand the
conditional cleanup behavior and match the example branches.
- Around line 50-57: Update the wording to clarify default vs flagged behavior:
change the sentence that says the transaction "aborts and no state changes from
the upgrade are applied" to explicitly state "by default the transaction aborts
and no state changes are applied," and add one short sentence explaining the
exception: if the message uses the SendIgnoreErrors flag (flag 2) then
compute-phase effects such as setData() can persist even when the action-phase
setCodePostponed() fails due to insufficient funds; mention compute phase vs
action phase semantics and reference SendIgnoreErrors, setData(), and
setCodePostponed() so readers understand the flagged behavior difference.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: d57a94e0-24e0-4a0e-974e-fa823a590a6e

📥 Commits

Reviewing files that changed from the base of the PR and between 3aa9f64 and 77ac90d.

📒 Files selected for processing (1)
  • contract-dev/techniques/upgrades.mdx

The following contract accepts `UpgradeContract` messages that contain new code or data. Only admins can trigger upgrades.

```tolk title="Tolk" expandable
struct (0x1111) UpgradeContract {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Minor nit - 0x1111 is the UpgradeContract opcode tag here, and throw 1111 (line 80, just below) is also the unauthorized-sender exit code. Reusing the same number for two different things makes failures slightly harder to trace from a tx dump. The delayed pattern below uses 100 for the same auth check; might be worth aligning

@Shvandre wdyt?

The following code illustrates the delayed upgrade pattern. The contract accepts `RequestUpgrade`, `RejectUpgrade`, and `ApproveUpgrade` messages. Only admins can trigger these actions.

```tolk title="Tolk" expandable
struct UpgradeContract {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

(re: CurrentRequest field on lines 134, 161, 163, 175, 177, 185-198, 209, 215 - anchored here at the closest in-diff line)

small consistency thing: CurrentRequest is used as both a struct type (line 134) and a struct field (storage.CurrentRequest)

Tolk convention is PascalCase for types and camelCase for fields/variables, so currentRequest for the field would line up with the rest of the file (adminAddress, timeout, timestamp, newUpgrade) and disambiguate the type/field references at a glance

cc @Shvandre

The original contract code before the upgrade:

```tolk title="main.tolk" expandable
import "@stdlib/tvm-lowlevel"
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

line 274, fun hotUpgradeData(additionalData: cell?) { return null; }

this returns null from a function with no declared return type. Since the body is never actually executed (the new code's version takes over after setTvmRegisterC3), return null reads as if the function is supposed to produce a value.

IMHO it will probably cleaner as:

 @method_id(2121)
-fun hotUpgradeData(additionalData: cell?) { return null; }
+fun hotUpgradeData(additionalData: cell?) { }

…optionally with a one-line comment noting that the body is intentionally empty because it's replaced before being called

cc @Shvandre

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Contract dev > Techniques > Upgrading contracts] Style cleanup

4 participants