Add withdrawable fee jettons via JettonWithdrawable by krebernisak · Pull Request #833 · smartcontractkit/chainlink-ton

krebernisak · 2026-08-18T08:39:11Z

Summary

Adds withdrawal of accrued fee jettons to the TON TokenPools via a new shared, stateless handler, JettonWithdrawable (lib/funding/jetton_withdrawable.tolk), mirroring EVM FeeTokenHandler.WithdrawFeeTokens.

This replaces the per-pool manual fee sweep with a generalized, msg-driven flow that all three pool families can share.

Highlights

Shared handler (JettonWithdrawable)

onWithdraw(msgValue, sender, msg, maxAmount, allowedRecipients) -> coins relays caller-supplied AskToTransfer pairs to the specified jetton wallets.
Enforces, in a single loop:
- inbound-value coverage: msgValue >= running sum(transfer.value) + MIN_RESERVE,
- per-transfer maxAmount bound,
- optional allowedRecipients allowlist (throws ZeroAddressNotAllowed for zero/none dest regardless), and a no-customPayload guard.
Each relayed ask is tagged with a WithdrawContext (opcode + initiator) via customPayload, so a bounce is recognized and the initiator is notified with a WithdrawFailed reply (onWithdrawBounced).

Pool wiring

burn/mint & lockbox: use the base unbounded relay, and onBouncedMessage is extended to discriminate a fee-withdraw AskToTransfer bounce from the existing pool-op asks.
lock/release (no-lockbox demo): keeps the extra accruedFees ledger. Fees accrue on confirmed lock settle (onLockOrBurnTransferContinueWithFeeSettlement); withdrawals are bounded by the ledger and decrement it by the total actually moved (onWithdrawFeeTokensBounded, maxAmount = st.accruedFees). A bounced withdraw ask re-credits the ledger.
Adds JettonWithdrawable_Withdraw as a TokenPool_InMessage, dispatched on onInternalMessage to onWithdrawFeeTokensDispatch.

Tests

Shared TokenPool.withdrawFeeTokens.behavior.ts runs in all three pool specs (LockRelease, BurnMint, Lockbox): accrues-on-lock, withdraw-as-owner, withdraw-as-feeAdmin, reject-non-owner.
Bounded-ledger overdraw-guard test (lock/release only).
New bounce-discrimination coverage for the withdraw ask in each family.

Notes

Auth (owner / fee-admin) is enforced by the caller before invoking the handler; the handler itself only enforces the per-transfer allowlist/limit/value guards.
Follow-up (see onramp/messages.tolk TODO): migrate the OnRamp's native-TON WithdrawFeeTokens to this shared handler so it can also sweep fee jettons.

…ll on mint

duck-types

Looks good! Left some comments

duck-types · 2026-08-20T12:13:01Z

+
+        val taggedAsk = AskToTransfer {
+            queryId: ask.queryId,
+            jettonAmount: ask.jettonAmount,


This assertion should be done outside the loop. It will revert all enqueued AskToTransfer anyway

Also, if I recal correctly, the emit also consumes value. Double check that you are not loosing balance when the received value is just enough to pay for the transfer values

Take a look at contracts/tests/utils/sendInternalMessage.ts and how it's used to check for balance difference

Yes, the value check could be improved.

I'll fix by using reserveToncoinsOnBalance with (1) original balance, + (2) rent due, + (3) rent reserve, or fail

duck-types · 2026-08-20T12:24:07Z

+        val relay = createMessage({
+            bounce: BounceMode.RichBounce,
+            value: transfer.value,
+            dest: transfer.wallet,


Beware that this field is ment for custom Jetton implementations (see jetton specification).

custom_payload - optional custom data (which is used by either sender or receiver jetton wallet for inner logic).

Although this is pretty smart, it's a hack. We should maybe document that this library does not support Jettons that make use of customPayload, and use a more descriptive error here

Reworked here: f5cb23c

Now using fwd payload wrap protocol (new) Jetton_ForwardPayloadWrap instead of taking over the customPayload field.

duck-types · 2026-08-20T12:28:18Z

+        };
+
+        // Relay the transfer with the caller's value, paying forwarding fees out of it
+        // (SEND_MODE_REGULAR). Rich bounce returns the full original ask (with the context) on failure.


This should be checked at the end against totalWithdrawn

Yeah, thanks for raising. There were gaps in logic here supporting N transfers but only a single limit with maxAmount. I've replaced it with maxAmount: map<address, coins>?, and now keep track of totalWithdrawn per wallet which should cover gaps.

Fixed here: ef9ebb0

duck-types · 2026-08-20T12:32:11Z

+// TODO: generalized — this was added before TON token support and only supports withdrawing native TON.
+// Migrate to the shared `JettonWithdrawable_WithdrawFeeTokens` (lib/funding/jetton_withdrawable.tolk)
+// so the OnRamp can also withdraw accrued fee jettons, like the TokenPool does.
 struct (0x7052dc75) OnRamp_WithdrawFeeTokens {


I don't think this can be just migrated. JettonWithdrawable_WithdrawFeeTokens doesn't support withdrawing native TON from the balance.

I can reword, but the point is I think eventually we will want to handle fees in fee tokens (e.g., EVM ramp doesn't keep fees in ETH).

At that point we want to use JettonWithdrawable_WithdrawFeeTokens. We might still keep the native TON withdraw, used for rent.

duck-types · 2026-08-20T12:47:50Z

+//
+// Elements are decoded via the shared tlbe codec so both scalars and structs
+// (including ones carrying ^ refs) are supported.
+type Array[T any] []T


xssnick/tonutils-go v1.17 added support for array tags. I spent some time in July working on this branch bumping tontuils-go to latest, but never finished the work

I will scope out a follow up for this if we already don't have a ticket

There is a ticket I've updated here: https://smartcontract-it.atlassian.net/browse/NONEVM-4680

duck-types

I'm not 100% sold on the opcode manual parsing

duck-types · 2026-09-04T17:12:09Z

+/// Parses a `Jetton_ForwardPayloadWrap` from a `forwardPayload`, or `null`
+@inline
+fun Jetton_ForwardPayloadWrap.from(forwardPayload: ForwardPayloadRemainder): Jetton_ForwardPayloadWrap? {
+    val wrapCell = loadForwardPayloadAsCell(forwardPayload);


You are potentially allocating an extra cell unecessarily.

Suggested change

val wrapCell = loadForwardPayloadAsCell(forwardPayload);

val wrapSlice = loadForwardPayloadAsSlice(forwardPayload);

duck-types · 2026-09-04T17:20:24Z

+    var s = wrapCell.beginParse();
+    if (s.loadUint(32) != Jetton_ForwardPayloadWrap_OPCODE) {
+        return null;
+    }


Why don't you use builtin decoder?

Suggested change

var s = wrapCell.beginParse();

if (s.loadUint(32) != Jetton_ForwardPayloadWrap_OPCODE) {

return null;

}

val UnpackException = 0xff

try {

return Jetton_ForwardPayloadWrap.fromCell(wrapCell, UnpackOptions { throwIfOpcodeDoesNotMatch: UnpackException})

} catch (e) {

if (e is UnpackException) {

return null;

}

throw e;

}

Alternativelly, you can use reflect.serializationPrefixOf to get the opcode instead of having a constant

You can also use a lazy loading + match

Sure, polished code here

duck-types · 2026-09-04T17:22:52Z

+
+struct (0x2d61600c) Jetton_ForwardPayloadWrap {
+    /// The address the tagged operation is reported back to on failure.
+    initiator: address


Shouldn't this go inside the context, too? It's only used when the message bounces

I've put this in the wrap for convenience as in most cases you will at least need the initiator.

krebernisak added 29 commits July 30, 2026 11:36

Add TP <> ContextExecutor integration to support async flow continuation

4eba166

Stash current behaviour - throw on error in transfer continuation

ebd58f4

Lock or burn transfer error handling and return

57e1f96

LockReleaseLockboxTokenPool use ContextExecutor vs. local st

6609721

yarn fmt

983976a

Fix lint

f55fcce

Update Go bindings

f2c3b99

Share code in TP lib + docs

542c047

CE - wait for deploy confirmation before continuation

7a74975

Merge branch 'main' into feat/tp-ctx-executor

5e311fc

Fix golangci-lint

20d7012

Remove local review

fe72522

Add TODOs for forwardTonAmount

1fd8dec

Migrate CE to OffRampAccount to support async flow

a7ddd88

Fix lock_release & lockbox flow

be605f4

Embed AskToTransfer in oa withdraw, check msg.transferInitiator == nu…

649181a

…ll on mint

Document OffRampAccount contract

081b30d

TP compose consumeIn/OutboundRateLimit functions

f658fdc

Replace CE on burn_mint burn path with CCT burn flow fwdPayload

821d44a

Fix oplint

42b38b5

rm tests/debug_cells.test.ts

4e054d7

Add OnRampAccount + handle TP deposit auth

c0d7e48

Improve TP error handling - return transfer

0e79a88

PR feedback - missing lazy

f8f3aa9

DepositAccount contract for on/off-ramp escrows

cebfbd8

Remove DepositAccount allowedJettonWallet

f500af1

Fix lint

be3ecde

DepositAccount Go bindings

cf792f0

Simplify deposit acc bounce handling

12b8781

krebernisak requested a review from a team as a code owner August 18, 2026 08:39

krebernisak force-pushed the feat/fee-withdraw branch from d4c30e4 to 3b99492 Compare August 19, 2026 08:01

Add Go bindings + tlbe.Array

c9f9c64

krebernisak force-pushed the feat/fee-withdraw branch from 3b99492 to c9f9c64 Compare August 19, 2026 08:46

Polish docs and fix lint

1bdd966

duck-types requested changes Aug 20, 2026

View reviewed changes

duck-types reviewed Aug 20, 2026

View reviewed changes

Base automatically changed from feat/deposit-acc to main August 27, 2026 18:59

nicolasgnr added the Flag label Sep 1, 2026

krebernisak added 7 commits September 1, 2026 18:58

Merge branch 'main' into feat/fee-withdraw

678af3c

Remove CE files post merge, polish

656d271

Polish + rm unused compilation targets

b68a7a6

Fix lock/release tp fee withdrawal + Go bindings

684ea62

Add proper isZeroAddress check

3cc11a8

Fix withdrawable maxAmount checks

db655f8

Improve value check onWithdraw via reserve

ef9ebb0

duck-types previously approved these changes Sep 2, 2026

View reviewed changes

vicentevieytes previously approved these changes Sep 3, 2026

View reviewed changes

Add Jetton_ForwardPayloadWrap, used by JettonWithdrawable

f5cb23c

krebernisak dismissed stale reviews from vicentevieytes and duck-types via f5cb23c September 4, 2026 15:51

krebernisak added 2 commits September 4, 2026 17:57

Merge branch 'main' into feat/fee-withdraw

5b82cf5

Remove duplicated field - ctx.withdrawInitiator

2134a01

duck-types previously approved these changes Sep 4, 2026

View reviewed changes

krebernisak added 2 commits September 7, 2026 12:10

PR feedback + polish

a8e7b05

Merge branch 'main' into feat/fee-withdraw

68bfaa0

krebernisak dismissed duck-types’s stale review via 68bfaa0 September 7, 2026 10:11

krebernisak added 2 commits September 7, 2026 12:20

Fix oplint

ecbfeda

Fix Go binding - lock/release storage

92bbadc

duck-types approved these changes Sep 7, 2026

View reviewed changes

krebernisak enabled auto-merge (squash) September 7, 2026 11:57

	val wrapCell = loadForwardPayloadAsCell(forwardPayload);
	val wrapSlice = loadForwardPayloadAsSlice(forwardPayload);

-    var s = wrapCell.beginParse();
-    if (s.loadUint(32) != Jetton_ForwardPayloadWrap_OPCODE) {
-        return null;
-    }
+    val UnpackException = 0xff
+    try {
+        return Jetton_ForwardPayloadWrap.fromCell(wrapCell, UnpackOptions { throwIfOpcodeDoesNotMatch: UnpackException})
+    } catch (e) {
+        if (e is UnpackException) {
+            return null;
+        }
+        throw e;
+    }

Uh oh!

Conversation

krebernisak commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Highlights

Tests

Notes

Uh oh!

duck-types left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

duck-types left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

krebernisak commented Aug 18, 2026 •

edited

Loading