Skip to content

Feat: WalletKit Gram#463

Open
heyllog wants to merge 4 commits into
mainfrom
feat/walletkit-ton-rename
Open

Feat: WalletKit Gram#463
heyllog wants to merge 4 commits into
mainfrom
feat/walletkit-ton-rename

Conversation

@heyllog

@heyllog heyllog commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Summary by CodeRabbit

  • Breaking Changes
    • Native asset renamed from TON to GRAM across the public API
    • Token metadata now reports name: 'Gram' and symbol: 'GRAM'
    • Staking metadata uses stakeToken.ticker: 'GRAM'
    • Human-readable transaction previews display "Gram Transfer" with GRAM denominations
    • HumanReadableTx type removed from public exports

@heyllog heyllog self-assigned this Jun 15, 2026
@vercel

vercel Bot commented Jun 15, 2026

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
appkit-minter Ready Ready Preview, Comment Jun 15, 2026 10:37am
kit-demo-wallet Ready Ready Preview, Comment Jun 15, 2026 10:37am

Request Review

@coderabbitai

coderabbitai Bot commented Jun 15, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Renames the native asset from TON to GRAM across the @ton/walletkit package: removes the HumanReadableTx public export, renames isValidNanotonAmount to isValidNanoAmount, updates JettonsManager native token metadata to name:'Gram'/symbol:'GRAM', changes transaction preview parsers to output "Gram Transfer"/"GRAM", updates tonstakers DEFAULT_METADATA stakeToken ticker, and propagates terminology through JSDoc, READMEs, and demo examples.

Changes

TON → GRAM rename

Layer / File(s) Summary
Changeset release declaration
.changeset/rename-ton-to-gram.md
Declares a patch release for @ton/walletkit and documents all breaking rename changes for consumers.
Validation API: remove HumanReadableTx, rename isValidNanoAmount
packages/walletkit/src/validation/transaction.ts, packages/walletkit/src/validation/index.ts, packages/walletkit/src/types/index.ts, packages/walletkit/src/validation/wallet.ts
Removes exported HumanReadableTx interface; renames isValidNanotonAmountisValidNanoAmount in implementation and barrel export; updates internal call sites, validation error text, and wallet balance error message to say "nano units".
JettonsManager: native token renamed to GRAM
packages/walletkit/src/core/JettonsManager.ts
Introduces GRAM_ADDRESS constant; updates TON_INFO metadata to name:'Gram'/symbol:'GRAM'; adjusts cache key creation, normalizedCacheKey, and clearCache repopulation to reference GRAM_ADDRESS.
WalletTonClass: use renamed isValidNanoAmount
packages/walletkit/src/core/wallet/extensions/ton.ts
Updates import and both call sites (single and multi TON transfer) to use isValidNanoAmount.
Runtime parsers and emulation mapper: GRAM labels
packages/walletkit/src/types/toncenter/parsers/TonTransfer.ts, packages/walletkit/src/types/toncenter/parsers/Contract.ts, packages/walletkit/src/clients/tonapi/mappers/map-emulation.ts
Changes simplePreview output from "Ton Transfer"/"TON" to "Gram Transfer"/"GRAM" for outgoing and incoming transfers; updates SmartContractExec value suffix; changes JettonSwap fallback asset symbol in dex transfer details.
Tonstakers constants and staking provider: stakeToken.ticker GRAM
packages/walletkit/src/defi/staking/tonstakers/constants.ts, packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.spec.ts, packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts, packages/walletkit/src/defi/staking/StakingManager.ts, packages/walletkit/src/defi/staking/tonstakers/PoolContract.ts, packages/walletkit/src/defi/staking/tonstakers/README.md
Updates DEFAULT_METADATA stakeToken.ticker from 'TON' to 'GRAM' for mainnet and testnet; aligns spec assertions and test config; updates provider and manager JSDoc.
API model interfaces: JSDoc unit/name updates
packages/walletkit/src/api/models/..., packages/walletkit/src/api/interfaces/GaslessAPI.ts, packages/walletkit/src/utils/computeMoneyFlow.ts, packages/walletkit/src/utils/messageBuilders.ts, packages/walletkit/src/defi/swap/dedust/utils.ts
Updates JSDoc wording across all API model interfaces, utility comments, and gasless API to use GRAM/nano units terminology in place of TON/nanotons.
Demo example code: GRAM constant and label updates
demo/examples/src/appkit/swap/dedust.ts, demo/examples/src/appkit/swap/omniston.ts, demo/examples/src/send-ton.ts, demo/examples/src/send-nft.ts, demo/examples/src/ui/render-money-flow.tsx, demo/examples/src/ui/summarize-transaction.tsx, demo/examples/src/__tests__/*
Replaces TON constant with GRAM in DeDust and Omniston swap examples; updates send example comments; changes jettonAddress label for AssetType.ton to 'GRAM' in UI helpers and corresponding tests.
READMEs, examples, and dev docs: GRAM terminology
packages/walletkit/README.md, packages/walletkit/DEVELOPMENT.md, packages/walletkit/examples/*, packages/walletkit/src/defi/gasless/README.md, packages/walletkit/src/defi/swap/dedust/README.md, packages/walletkit/src/defi/swap/omniston/README.md, template/packages/walletkit/README.md, template/packages/walletkit/src/defi/staking/tonstakers/README.md
Propagates GRAM terminology through all README files, example markdown docs, and development docs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

  • Rebranding of the TON's main currency docs#2209: This PR directly implements the currency rebranding initiative described in that issue, replacing all "TON" ticker references with "GRAM" across WalletKit's public API, metadata, transaction previews, validation, and documentation.

Poem

🐇 Hop hop, the ticker's changed today,
From TON to GRAM we've found our way!
The metadata's fresh, the symbols bright,
"Gram Transfer" gleams in the preview light.
With nano units counting every trace,
This rabbit stamps GRAM in every place! 🌟

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 53.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check ❓ Inconclusive The title 'Feat: WalletKit Gram' is vague and generic, using 'Gram' without context about what the change actually entails (renaming TON to GRAM across the codebase). Consider a more descriptive title such as 'Rename native asset from TON to GRAM across WalletKit' or 'Feat: Rename TON to GRAM in WalletKit API and documentation' to clearly convey the scope and nature of the breaking change.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/walletkit-ton-rename

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.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 2

🧹 Nitpick comments (1)
packages/walletkit/src/core/JettonsManager.ts (1)

25-25: ⚡ Quick win

Consider adding a clarifying comment for GRAM_ADDRESS.

The constant name GRAM_ADDRESS with value 'TON' may be confusing to future developers. Since 'TON' is the internal identifier and GRAM is the display name/symbol, a comment explaining this distinction would improve clarity.

📝 Suggested comment
-const GRAM_ADDRESS = 'TON';
+// Internal identifier for the native asset (value 'TON' is the on-chain identifier; 'GRAM' is the display name)
+const GRAM_ADDRESS = 'TON';
🤖 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 `@packages/walletkit/src/core/JettonsManager.ts` at line 25, Add a clarifying
comment above the GRAM_ADDRESS constant definition to explain that 'TON' is the
internal blockchain identifier while GRAM is the display name or symbol used in
the user interface. This will help future developers understand why the constant
is named GRAM_ADDRESS but has the value 'TON', reducing potential confusion
about the distinction between the internal identifier and the display symbol.
🤖 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 @.changeset/rename-ton-to-gram.md:
- Line 2: The version bump declaration in the changeset is set to patch, but the
actual changes being made (removing the exported HumanReadableTx type and
renaming the isValidNanoAmount function) are breaking changes that require a
major version bump according to semantic versioning. Change the version bump
type from patch to major in the changeset file to accurately reflect the
breaking nature of these changes.

In `@packages/walletkit/src/defi/staking/tonstakers/PoolContract.ts`:
- Around line 17-24: Update the JSDoc comments for the PoolData interface fields
to reflect the asset name rename from TON to GRAM. In the PoolContract.ts file,
modify the documentation comments for the totalBalance, supply,
projectedBalance, and projectedSupply fields to replace references to "TON" and
"tsTON" with the appropriate new asset names (GRAM and corresponding staking
token names) to ensure the generated API documentation reflects the current
naming convention across the package.

---

Nitpick comments:
In `@packages/walletkit/src/core/JettonsManager.ts`:
- Line 25: Add a clarifying comment above the GRAM_ADDRESS constant definition
to explain that 'TON' is the internal blockchain identifier while GRAM is the
display name or symbol used in the user interface. This will help future
developers understand why the constant is named GRAM_ADDRESS but has the value
'TON', reducing potential confusion about the distinction between the internal
identifier and the display symbol.
🪄 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: 421540a9-20e1-4a18-ae15-79d7ae06f104

📥 Commits

Reviewing files that changed from the base of the PR and between 835f505 and 82fa071.

⛔ Files ignored due to path filters (1)
  • packages/walletkit/src/types/toncenter/__snapshots__/AccountEvent.spec.ts.snap is excluded by !**/*.snap
📒 Files selected for processing (56)
  • .changeset/rename-ton-to-gram.md
  • demo/examples/src/__tests__/transfers.test.ts
  • demo/examples/src/__tests__/ui.test.ts
  • demo/examples/src/appkit/swap/dedust.ts
  • demo/examples/src/appkit/swap/omniston.ts
  • demo/examples/src/send-nft.ts
  • demo/examples/src/send-ton.ts
  • demo/examples/src/ui/render-money-flow.tsx
  • demo/examples/src/ui/summarize-transaction.tsx
  • packages/walletkit/DEVELOPMENT.md
  • packages/walletkit/README.md
  • packages/walletkit/examples/js-bridge-usage.md
  • packages/walletkit/examples/ledger-usage.md
  • packages/walletkit/src/api/interfaces/GaslessAPI.ts
  • packages/walletkit/src/api/models/blockchain/AccountState.ts
  • packages/walletkit/src/api/models/core/AssetType.ts
  • packages/walletkit/src/api/models/core/TokenAmount.ts
  • packages/walletkit/src/api/models/core/TokenInfo.ts
  • packages/walletkit/src/api/models/emulation/EmulationMessage.ts
  • packages/walletkit/src/api/models/emulation/EmulationTransaction.ts
  • packages/walletkit/src/api/models/gasless/GaslessConfig.ts
  • packages/walletkit/src/api/models/jettons/JettonsTransferRequest.ts
  • packages/walletkit/src/api/models/nfts/NFTRawTransferRequest.ts
  • packages/walletkit/src/api/models/nfts/NFTTransferRequest.ts
  • packages/walletkit/src/api/models/staking/StakeParams.ts
  • packages/walletkit/src/api/models/staking/StakingProviderInfo.ts
  • packages/walletkit/src/api/models/staking/StakingProviderMetadata.ts
  • packages/walletkit/src/api/models/staking/StakingQuoteParams.ts
  • packages/walletkit/src/api/models/tons/TONTransferRequest.ts
  • packages/walletkit/src/api/models/transactions/Transaction.ts
  • packages/walletkit/src/api/models/transactions/TransactionTrace.ts
  • packages/walletkit/src/api/models/transactions/TransactionTraceMoneyFlow.ts
  • packages/walletkit/src/clients/tonapi/mappers/map-emulation.ts
  • packages/walletkit/src/core/JettonsManager.ts
  • packages/walletkit/src/core/wallet/extensions/ton.ts
  • packages/walletkit/src/defi/gasless/README.md
  • packages/walletkit/src/defi/staking/StakingManager.ts
  • packages/walletkit/src/defi/staking/tonstakers/PoolContract.ts
  • packages/walletkit/src/defi/staking/tonstakers/README.md
  • packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.spec.ts
  • packages/walletkit/src/defi/staking/tonstakers/TonStakersStakingProvider.ts
  • packages/walletkit/src/defi/staking/tonstakers/constants.ts
  • packages/walletkit/src/defi/swap/dedust/README.md
  • packages/walletkit/src/defi/swap/dedust/utils.ts
  • packages/walletkit/src/defi/swap/omniston/OmnistonSwapProvider.spec.ts
  • packages/walletkit/src/defi/swap/omniston/README.md
  • packages/walletkit/src/types/index.ts
  • packages/walletkit/src/types/toncenter/parsers/Contract.ts
  • packages/walletkit/src/types/toncenter/parsers/TonTransfer.ts
  • packages/walletkit/src/utils/computeMoneyFlow.ts
  • packages/walletkit/src/utils/messageBuilders.ts
  • packages/walletkit/src/validation/index.ts
  • packages/walletkit/src/validation/transaction.ts
  • packages/walletkit/src/validation/wallet.ts
  • template/packages/walletkit/README.md
  • template/packages/walletkit/src/defi/staking/tonstakers/README.md
💤 Files with no reviewable changes (1)
  • packages/walletkit/src/types/index.ts

@@ -0,0 +1,11 @@
---
"@ton/walletkit": patch

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Semantic versioning violation: breaking changes require a major bump, not patch.

Line 2 declares a patch version bump, but the changeset removes the exported HumanReadableTx type and renames the public isValidNanoAmount function (both breaking changes for consumers). According to semantic versioning, breaking changes require a major version increment.

🔧 Proposed fix
 ---
-"`@ton/walletkit`": patch
+"`@ton/walletkit`": major
 ---
📝 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
"@ton/walletkit": patch
"`@ton/walletkit`": major
🤖 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 @.changeset/rename-ton-to-gram.md at line 2, The version bump declaration in
the changeset is set to patch, but the actual changes being made (removing the
exported HumanReadableTx type and renaming the isValidNanoAmount function) are
breaking changes that require a major version bump according to semantic
versioning. Change the version bump type from patch to major in the changeset
file to accurately reflect the breaking nature of these changes.

Comment on lines +17 to 24
/** Total TON balance in the pool (nano units) */
totalBalance: bigint;
/** Total tsTON supply (nanotsTON) */
/** Total tsTON supply (nano units) */
supply: bigint;
/** Projected TON balance at round end (nanoTON) */
/** Projected TON balance at round end (nano units) */
projectedBalance: bigint;
/** Projected tsTON supply at round end (nanotsTON) */
/** Projected tsTON supply at round end (nano units) */
projectedSupply: bigint;

Copy link
Copy Markdown

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

Align the PoolData docs with the GRAM rename.

These public comments still describe the pool totals in TON, which will leak the old asset name into generated API docs and conflict with the rest of the package rename.

Suggested wording update
-    /** Total TON balance in the pool (nano units) */
+    /** Total GRAM balance in the pool (nano units) */
-    /** Total tsTON supply (nano units) */
+    /** Total tsTON supply (nano units) */
-    /** Projected TON balance at round end (nano units) */
+    /** Projected GRAM balance at round end (nano units) */
-    /** Projected tsTON supply at round end (nano units) */
+    /** Projected tsTON supply at round end (nano units) */
📝 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
/** Total TON balance in the pool (nano units) */
totalBalance: bigint;
/** Total tsTON supply (nanotsTON) */
/** Total tsTON supply (nano units) */
supply: bigint;
/** Projected TON balance at round end (nanoTON) */
/** Projected TON balance at round end (nano units) */
projectedBalance: bigint;
/** Projected tsTON supply at round end (nanotsTON) */
/** Projected tsTON supply at round end (nano units) */
projectedSupply: bigint;
/** Total GRAM balance in the pool (nano units) */
totalBalance: bigint;
/** Total tsTON supply (nano units) */
supply: bigint;
/** Projected GRAM balance at round end (nano units) */
projectedBalance: bigint;
/** Projected tsTON supply at round end (nano units) */
projectedSupply: bigint;
🤖 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 `@packages/walletkit/src/defi/staking/tonstakers/PoolContract.ts` around lines
17 - 24, Update the JSDoc comments for the PoolData interface fields to reflect
the asset name rename from TON to GRAM. In the PoolContract.ts file, modify the
documentation comments for the totalBalance, supply, projectedBalance, and
projectedSupply fields to replace references to "TON" and "tsTON" with the
appropriate new asset names (GRAM and corresponding staking token names) to
ensure the generated API documentation reflects the current naming convention
across the package.

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.

1 participant