[TEP-121] Lockable Jetton Wallet: Enhancing Contract Interface with Locked Balance Feature


This document proposes an enhancement to the Jetton Wallet, specifically through the introduction of a get_locked_balance method. This addition aims to accommodate scenarios where jetton transfers need to be temporarily disabled, without disrupting the functionality of existing services by displaying a zero balance.


The rationale behind this proposal is to address the needs of new contracts that may require the temporary suspension of jetton transfers. Such a feature is pivotal for:

  1. Jetton DAO Contracts: To prevent jetton transfers while voting processes are ongoing.
  2. Jetton Vesting Contracts: To enable the scheduled release of tokens in the future.

By integrating the get_locked_balance method, these contracts can effectively manage jetton availability, enhancing both security and functionality.

Implementation Guide

The get_locked_balance method, when invoked, should return three key pieces of information:

  • Integer Jetton Balance: The current balance of the wallet.
  • Integer Locked Jetton Balance: The amount of jettons that are currently locked.
  • Expiration Date: The UNIX epoch seconds indicating when the locked jettons will be released.


Jetton Wallet Contracts

The Jetton Wallet contracts are expected to implement the get_locked_balance method as follows:

(int, int, int) get_locked_balance() method_id {
  (int balance, slice owner_address,
          slice jetton_master_address, cell jetton_wallet_code,
          int locked, int lock_expiration,
          cell vote_keeper_code) = load_data();
  return (balance, locked, lock_expiration);

This implementation ensures that the wallet can communicate the locked balance and its expiration date, thereby providing clarity and transparency regarding the available and inaccessible jetton amounts.



The proposed standard introduces the limitation of having a single locked balance and a single expiration date for that balance.

Rationale and Alternatives

The design choice to display both the available and locked balances separately aims to enhance user experience and clarity. It allows for a straightforward representation of funds in blockchain explorers and wallets. An alternative approach could involve multiple locked balances with respective expiration dates; however, this could complicate the user interface and backend logic.


The proposed enhancement to the Jetton Wallet, through the addition of a get_locked_balance method, represents a significant step towards more versatile and secure contract interactions. By allowing contracts to manage jetton availability with precision, this proposal not only addresses immediate functional needs but also opens up future possibilities for innovative contract designs and applications.

Comparison Table

Feature Current Implementation Proposed Enhancement
Balance Visibility Total balance only Separates total and locked balances
Transfer Restrictions Not explicitly supported Enables temporary transfer restrictions
Expiration Tracking Not available Provides expiration date for locked balance
Implementation Example Not applicable Provided in proposal
User Experience Limited flexibility Enhanced clarity and functionality

This enhancement underscores a commitment to evolving the Jetton Wallet interface to meet the dynamic needs of the blockchain ecosystem, ensuring both robustness and flexibility in jetton management and transfer protocols.