TON Teleport BTC smart contracts

Open-source smart contracts and tooling for TON Teleport BTC. This repository contains FunC contracts, TypeScript wrappers, a CLI for on-chain interaction, and a comprehensive test suite.

Repository structure

• contracts – FunC smart contracts and libraries
  • bitcoin_client – Bitcoin block header verification (SPV client) (source, docs)
  • configurator-light – System configuration management: parameters, inspectors, global state (source)
  • coordinator – DKG coordination and peg-out transaction signing (source)
  • deposit – Credential primitives for deposit recovery (source)
  • jetton-btc – tgBTC jetton (minter + wallet) (minter, wallet)
  • pegin_tx – Peg-in helper contract (source)
  • pegout_tx – Peg-out transaction contract (source)
  • teleport – Main Teleport contract handling Bitcoin deposits, minting tgBTC and handling tgBTC burns (source)
  • libs – Shared FunC libraries (BTC parsing/validation, math, crypto, TON message helpers) (folder)
  • mock.fc – Simple mock contract for tests (source)
• wrappers – TypeScript contract wrappers (serialization, getters, deploy/build helpers)
• tests – Jest-based test suite for contracts and libraries
• scripts – Deployment and operational scripts (Blueprint runners)
• bitcoin – Bitcoin utilities (tapscript, tx builder, secp256k1 helpers)

---

Prerequisites

• Bun (recommended) or Node.js for running scripts
• Git

Install Bun:

# macOS (Homebrew)
brew install oven-sh/bun/bun

# or, via the official install script (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

bun --version

Official Installation guide

Install dependencies:

bun install

---

Build all contracts

Compile every contract with Blueprint:

bun run build

Artifacts are written to build/<ContractName>/*.fif and build/<ContractName>.compiled.json.

Testing

Run the full test suite:

bun jest --verbose

Tests use Jest and run fully offline (no blockchain access required for unit tests).

---

Contract flows (sequence diagrams)

Pegin flow

BTC deposit is proven via SPV; Teleport verifies and mints tgBTC to the user.

sequenceDiagram
  actor wallet as User
  participant tport as Teleport
  participant block as Confirmed Block
  participant minter as Jetton Minter
  participant jetton-wallet as Jetton Wallet

  wallet ->>+ tport: op::teleport::transfer_btc
  Note over tport: calculate tap merkle root
  Note over tport: create deposit record
  tport ->>- block: op::confirmed_block::req_merkle_root
  activate block
  block -->>+ tport: return block_merkle_root
  deactivate block
  Note over tport: verify merkle proof
  Note over tport: tweak internal key
  Note over tport: find utxo
  Note over tport: check utxo amount >= pegin limit
  create participant pegintx as PeginTx
  tport ->>- pegintx: deploy pegin_tx + op::pegin_tx::initialize
  activate pegintx
  pegintx -->>+ tport: deploy succeeded
  deactivate pegintx
  Note over tport: delete deposit record
  Note over tport: add utxo to utxo_set
  Note over tport: reduce utxo amount by service fee
  Note over tport: emit event::mint
  tport ->>- minter: op::mint
  activate minter
  minter ->> jetton-wallet: op::internal_transfer
  deactivate minter
  activate jetton-wallet
  jetton-wallet ->> wallet: send change
  deactivate jetton-wallet

Loading

Pegout flow

User burns tgBTC on TON. Teleport creates a PegoutTx, which notifies the Coordinator to start the signing process for BTC withdrawal.

sequenceDiagram
  actor user as User
  participant jwallet as Jetton Wallet
  participant minter as Jetton Minter
  participant tport as Teleport
  participant pegout as PegoutTx
  participant coordinator as Coordinator

  user->>jwallet: Burn tgBTC
  activate jwallet
  jwallet->>minter: Burn notification
  deactivate jwallet
  activate minter
  minter->>tport: op::burn_notification
  deactivate minter
  activate tport
  Note over tport: calculate tx fee
  Note over tport: build txid
  Note over tport: reset utxo_set and add new single utxo
  Note over tport: emit event::burn
  tport->>pegout: deploy pegout_tx + op::initialize
  deactivate tport
  activate pegout
  pegout->>coordinator: op::coordinator::create_pegout_tx
  activate coordinator
  Note over coordinator: add pegout record to g::unsigned_pegouts
  deactivate coordinator
  pegout->>user: send change
  deactivate pegout

Loading

New key flow

Validators generate a group threshold key and send it to the Coordinator. The Coordinator notifies Teleport about the new key. Teleport updates the internal key, rotates UTXO state, and creates a PegoutTx to transfer all locked BTC to the new key.

sequenceDiagram
  actor oracles as Oracles
  participant coord as Coordinator
  participant tport as Teleport
  participant pegout as PegoutTx

  oracles ->> coord: public key package + session public key
  activate coord
  coord ->> tport: op::teleport::send_internal_key
  deactivate coord
  activate tport
  Note over tport: update internal key and calc tweaked internal key
  Note over tport: emit event::new_key
  Note over tport: build txid
  Note over tport: reset utxo_set and add single utxo with txid
  tport ->> pegout: deploy with prev internal key
  deactivate tport
  activate pegout
  pegout ->> coord: op::coordinator::create_pegout_tx
  activate coord
  Note over coord: add pegout record to g::unsigned_pegouts
  deactivate coord
  pegout ->> coord: send change
  deactivate pegout

Loading

---

CLI (interactive monitor and tools)

The CLI lets you query on-chain state, inspect code hashes, decode cells.

1) Network and wallet

Set an API key (if using the provided Toncenter endpoint):

export API_KEY=YOUR_TONCENTER_API_KEY

Set MNEMONIC and WALLET_VERSION env vars.

Start on mainnet (default script uses --mnemonic and a --mainnet endpoint):

bun run cli:mainnet

Start on testnet (default script uses --mnemonic and a migrate-testnet.toncenter.com endpoint):

NOTE: use testnet addresses in contract.json.

bun run cli

2) Contract addresses

The CLI looks up addresses in contracts.json file in the repo root.

3) Using the CLI

Once started, type help (or h) to list commands. Aliases are shown in parentheses.

Example: verbose DKG state

> gd -v

---

TON Testnet deployment script (example)

Run deployment flow with Blueprint:

bun run deploy:all