How passwords keep you safe

This section explains how the password mechanism in TON Teleport ensures users can securely retrieve BTC deposits if a transaction isn't processed in time. Even if BTC is sent to an expired address, or it expires during confirmation, a refund is still possible using the password.

TON Teleport is currently on Testnet. Do not send real funds and don’t use mainnet wallets.

📖 What you will learn

• why passwords are needed for recovering lost deposits

• how the encryption and recovery process works

• what keeps your password safe

📚 Before we begin

Make sure you have:

• Testnet wallet in TON (e.g., Tonkeeper from our previous guide)

• Signet wallet in BTC (e.g., UniSat or Electrum from our previous guide)

• burned and minted your first tgBTC from our previous guides

🚀 Why was the password mechanism created?

In the TON ecosystem, blockchain validators rotate every 18 hours. During each rotation period, a specific validator group is responsible for managing the Bitcoin held at that time, and then passes control to the next group.

Creating a password to make a deposit and ask for a refund if needed.

To initiate a BTC deposit, the system generates a unique deposit address that incorporates three key components:

• Recipient address: Specifies where to send tgBTC within the TON network.

• Aggregated validator key: A single key derived from the current validator group using FROST. It combines individual validator keys and enables the group to collectively manage BTC.

• User’s public key: Part of the password-generated key pair, embedded into the deposit address and used to verify refund transactions.

If a user sends BTC with a low transaction fee and the transaction gets stuck, or if BTC is sent to an outdated deposit address, the system may no longer be able to process the deposit. This happens when the deposit address is no longer valid due to validator rotation.

To address this, we developed a password-based mechanism that allows users to securely recover their BTC in such cases.

Refunding BTC using your password.

When the time period passes, which is two days on testnet or one month on mainnet, the system requires a valid signature to release the funds. Since the public key is embedded in the deposit address, the Bitcoin network accepts the transaction as long as it is signed with the correct decrypted secret key.

⚡️ What is a password in TON Teleport?

A password lets users recover their BTC if their deposit address is no longer valid. If TON Teleport cannot process the transaction, the user can withdraw their BTC to any chosen address.

Key features of the password:

• No login, no recovery: The password exists independently, with no way to reset or retrieve it.

• Reusable or unique: A single password can secure multiple Peg-ins, or users can create a new one for each deposit.

• Blockchain-based recovery: The password encrypts a secret recovery key that is stored on-chain and can only be decrypted by the user.

• Time-locked access: BTC becomes available for withdrawal only after a fixed period of two days on testnet or one month on mainnet.

• Optional usage: Using the key pair is optional. Developers who integrate programmatically and are confident their system can register the deposit correctly may choose not to include it.

• Advanced privacy options: For privacy-conscious users, it’s possible to generate and manage key pairs manually, perform encryption and decryption outside the browser, and avoid uploading any encrypted data to TON. While the default system is secure and user-friendly, full control is available for those who prefer handling everything themselves.

⚙️ How does the password work under the hood?

When creating a password in the browser, it is not stored anywhere. The system generates a key pair: a public key and a secret key.

• The public key is embedded in the BTC deposit address.

• The secret key is encrypted using the password and stored on the TON blockchain in encrypted form.

Process flow:

1. The user creates a password, and the system generates a key pair.

2. The secret key is encrypted using the password and stored on-chain.

3. If a refund is needed, the user downloads the encrypted key.

4. The user enters the password in the browser to decrypt the key.

5. The browser creates a transaction, signs it with the secret key, and submits it.

The secret key is never stored in plaintext, not on the device and not in the blockchain. Only the encrypted version is ever saved, and it can only be unlocked using the correct password.

🦄 Inside password encryption at deep tech level

We use cryptographic primitives to secure passwords and encrypted data:

1. SHA-256 for hashing strings.

2. Argon2 is used through the crypto_pwhash function to derive a key from the password.

3. ChaCha20-Poly1305 for encrypting data.

4. A unique nonce prevents ciphertext reuse attacks.

Password encryption process:

1. Hashing the password with a salt using SHA-256.

2. Deriving a secure key from the hash with Argon2.

3. Encrypting the key with ChaCha20-Poly1305.

4. Store the encrypted data on-chain securely.

Password decryption process:

1. Extracting salt and nonce from encrypted data.

2. Generating a secure key from the password using Argon2.

3. Decrypting the secret key with ChaCha20-Poly1305.

4. Sign the refund transaction and broadcast it to the Bitcoin network.

💎 What's next?

Now you understand how passwords work in TON Teleport! Dive deeper into the whitepaper to explore how validators operate in TON Teleport BTC.

Read the whitepaper to learn more.