Trustless TON escrows in one tap, inside Telegram.
PUSHKA is a P2P escrow protocol on the TON blockchain that lets two specific people settle a TON deal with a deadline and an auto-refund safety net — wrapped in a Telegram Mini App. It is written in Tolk, TON's native next-generation contract language.
┌─────────────────────────────────────────────────────────────┐
│ Alice locks 1 TON → Bob accepts with 2 TON → settled │
│ (deadline 24h, optional pinned counterparty, auto-refund) │
└─────────────────────────────────────────────────────────────┘
Those are AMM pool swaps — anonymous, instant, no conditions. PUSHKA
solves the opposite problem: a deal between two specific wallets,
at a specific price, with a deadline, and the ability to
cancel before settlement. See docs/ARCHITECTURE.md
for the competitive analysis.
contracts/src/
├─ PushkaFactory.tolk # singleton: deploys deals, holds protocol fees
├─ PushkaEscrow.tolk # one contract per deal, self-destructs on exit
└─ types.tolk # shared structs, errors and opcodes
contracts/tests/
├─ factory.test.tolk # 9 admin/bookkeeping tests
└─ escrow.test.tolk # 13 end-to-end lifecycle tests (incl. failure paths)
contracts/scripts/deploy.tolk # TON Connect / wallet deploy script
app/ # Vite + React + TON Connect Mini App
docs/
├─ ARCHITECTURE.md # design, threat model, competitive analysis
├─ DEPLOY.md # zero-seed-phrase deploy guide
├─ SECURITY.md # threat model and audit checklist
└─ MARKETING.md # go-to-market playbook
# 1) Install Acton (one-time)
curl -LsSf https://github.com/ton-blockchain/acton/releases/latest/download/acton-installer.sh | sh
source $HOME/.acton/bin/env
# 2) Build & test the contracts
acton build
acton test # ✓ 22 passed in 2 files (~30 ms)
# 3) Install & build the Mini App
npm ci
npm run typecheck
npm run dev # local development server
# 4) Deploy to testnet via TON Connect (no seed phrase needed)
acton run deploy-testnet-tcSee docs/DEPLOY.md for the full guided path from
clean clone to live testnet.
| Component | Status |
|---|---|
| Contracts (Factory + Escrow) | ✅ Compiles in 7 ms, 22/22 native Tolk tests green |
| Native Tolk tests | ✅ Covers happy path + every revert reason |
| TypeScript wrappers | ✅ Auto-generated by acton wrapper --ts |
| Mini App (Create / Accept) | ✅ Vite build 1.6 s, npm run typecheck clean |
| Testnet deploy | ✅ Live on testnet — see addresses below |
| Live E2E run | ✅ One full deal settled on testnet; WithdrawFees verified |
| Mainnet deploy | ⏳ Pending owner funding (≈ 0.22 mainnet TON) |
| Independent audit | ⏳ Not yet — repo is open-source, MIT |
PushkaFactory is deployed on TON testnet and has processed one full
deal lifecycle plus an owner withdrawal:
| What | Where |
|---|---|
| Factory address | kQChkfX-V0mnEPW7SiUu-mcKpiJsWNbLs4WlqztMpvC1mJAm |
| Factory deploy tx | b3bd9155…507506fa |
| Sample deal escrow | kQBiktY7cRmqEM-zLs9FdbEoelsnTYm0OSMzCL_9jQdIMj-6 |
| First Accept (settled, fee 0.0006 TON) | utime 1779787190 |
| Owner WithdrawFees | 5f1cd8bd…cd3cc892 |
| Settlement math | wantAmount × feeBps / 10000 = 0.2 × 30 / 10000 = 0.0006 TON — matches accumulatedFees exactly |
| Owner address | kQDJQPFaK-Ll0qlDHpVnUfcfYlz-lK8e04g6J_LereOq_BIh |
To plug into the Mini App, create .env.local in the repo root:
VITE_PUSHKA_FACTORY_TESTNET=kQChkfX-V0mnEPW7SiUu-mcKpiJsWNbLs4WlqztMpvC1mJAm
VITE_PUSHKA_FACTORY_MAINNET=
VITE_TONAPI_KEY=The contract is intentionally minimal: ~280 lines of Tolk total
(both contracts). The full threat model and audit checklist lives in
docs/SECURITY.md. Reviewers welcome — please open
a GitHub issue for findings.
You never need to give your wallet seed to anyone. The deploy script uses TON Connect: Tonkeeper signs the deploy on your phone, the secret never touches the command line.
MIT — see LICENSE.