starknet-tongo

Starknet Tongo Skill

Confidential ERC20 payments on Starknet using the Tongo protocol. Tongo wraps any ERC20 token into encrypted balances using ElGamal encryption and zero-knowledge proofs. No trusted setup required.

When to Use

• Confidential ERC20 payment flows that require encrypted balances or private transfers.
• Compliance or auditor-enabled privacy flows built on top of Tongo accounts.

When NOT to Use

• Standard transparent ERC20 transfers, swaps, or wallet management without privacy requirements.
• Cairo contract authoring, deployment-only tasks, or security auditing of unrelated code.

Quick Start

1. Install the Tongo SDK, configure the Starknet/Tongo keys, and connect a funded Starknet account.
2. Use skills catalog if the flow expands into wallet setup, deployment, or auditing.

Prerequisites

npm install @fatsolutions/tongo-sdk starknet@^9.2.1

To run the demo script (scripts/demo-e2e.ts):

npm install dotenv && npm install -D tsx

Environment variables:

STARKNET_RPC_URL=https://starknet-mainnet.g.alchemy.com/v2/YOUR_KEY
STARKNET_ACCOUNT_ADDRESS=0x...
STARKNET_PRIVATE_KEY=0x...
TONGO_CONTRACT_ADDRESS=0x...
TONGO_PRIVATE_KEY=0x...
TONGO_AUDITOR_PRIVATE_KEY=0x...  # Optional, only needed for auditor/compliance

The demo script additionally requires both sender and receiver keys (test-only):

TONGO_PRIVATE_KEY_SENDER=0x...
TONGO_PRIVATE_KEY_RECEIVER=0x...

Core Concepts

Concept	Description
Fund	Convert ERC20 tokens into encrypted Tongo balances
Transfer	Send encrypted amounts between Tongo accounts (ZK-proven)
Rollover	Merge pending received funds into usable balance
Withdraw	Convert Tongo balance back to ERC20 (public amount)
Ragequit	Emergency full withdrawal of entire balance
Outside Fund	Fund any Tongo account without needing their private key
Auditor	Optional compliance role that can decrypt all transactions

Transfers land in the receiver's pending balance and must be rolled over before they can be spent.

Setup

import { Account as TongoAccount } from "@fatsolutions/tongo-sdk";
import { Account, RpcProvider } from "starknet";

const provider = new RpcProvider({ nodeUrl: process.env.STARKNET_RPC_URL });

// Starknet account for paying gas
const account = new Account({
  provider,
  address: process.env.STARKNET_ACCOUNT_ADDRESS,
  signer: process.env.STARKNET_PRIVATE_KEY,
});

// Tongo account for confidential operations
const tongo = new TongoAccount(
  process.env.TONGO_PRIVATE_KEY,
  process.env.TONGO_CONTRACT_ADDRESS,
  provider,
);

console.log("Tongo address:", tongo.tongoAddress()); // Base58-encoded public key

Operations

Check Encrypted Balance

const state = await tongo.state();
console.log("Balance:", state.balance);   // Decrypted current balance
console.log("Pending:", state.pending);   // Funds received but not yet rolled over
console.log("Nonce:", state.nonce);

Fund (ERC20 -> Tongo)

const fundOp = await tongo.fund({
  amount: 100n,
  sender: account.address,
  fee_to_sender: 0n,  // Optional relayer fee
});

// Requires ERC20 approval + fund call
const response = await account.execute([fundOp.approve, fundOp.toCalldata()]);
await provider.waitForTransaction(response.transaction_hash);

Transfer (Confidential)

// Receiver shares their Tongo address (public -- safe to share)
const receiverTongoAddress = "Base58EncodedPublicKeyFromReceiver";

const transferOp = await tongo.transfer({
  amount: 50n,
  to: receiverTongoAddress, // Public Tongo address, never use receiver's private key
  sender: account.address,
  fee_to_sender: 0n,
});

const response = await account.execute(transferOp.toCalldata());
await provider.waitForTransaction(response.transaction_hash);
// Amount is encrypted on-chain; receiver sees it in pending balance

Rollover (Activate Received Funds)

The receiver calls rollover on their own Tongo account to activate pending funds:

const rolloverOp = await tongo.rollover({
  sender: account.address,
});

const response = await account.execute(rolloverOp.toCalldata());
await provider.waitForTransaction(response.transaction_hash);
// Pending balance moves to current balance

Withdraw (Tongo -> ERC20)

const withdrawOp = await tongo.withdraw({
  amount: 25n,
  to: "0x...", // Starknet address receiving ERC20
  sender: account.address,
  fee_to_sender: 0n,
});

const response = await account.execute(withdrawOp.toCalldata());
await provider.waitForTransaction(response.transaction_hash);

Ragequit (Emergency Full Withdrawal)

const ragequitOp = await tongo.ragequit({
  to: "0x...", // Starknet address receiving ERC20
  sender: account.address,
  fee_to_sender: 0n,
});

const response = await account.execute(ragequitOp.toCalldata());
await provider.waitForTransaction(response.transaction_hash);
// Entire balance withdrawn; more efficient than regular withdraw for full amount

Outside Fund (Fund Any Account)

const outsideFundOp = await tongo.outside_fund({
  amount: 100n,
  to: "Base58EncodedTongoAddressOfRecipient", // Tongo address of the receiver
});

const response = await account.execute([
  outsideFundOp.approve,
  outsideFundOp.toCalldata(),
]);
await provider.waitForTransaction(response.transaction_hash);

Auditor Usage

An optional auditor can decrypt all transaction amounts for compliance:

import { Auditor } from "@fatsolutions/tongo-sdk";

const auditor = new Auditor(
  process.env.TONGO_AUDITOR_PRIVATE_KEY,
  process.env.TONGO_CONTRACT_ADDRESS,
  provider,
);

// Tongo address of the user to audit (Base58, shared publicly by the user)
const userTongoAddress = "Base58EncodedTongoAddressOfUser";

// Get user balance
const balance = await auditor.getUserBalance(0, userTongoAddress);
console.log("Declared balance:", balance.amount);

// Get transfer history
const transfers = await auditor.getUserTransferOut(0, userTongoAddress);
transfers.forEach(t => console.log(`Transferred ${t.amount} to ${t.to}`));

// Get real balance including pending
const realBalance = await auditor.getRealuserBalance(0, userTongoAddress);

Transaction History

// All events for an account
// NOTE: Using 0 scans from genesis and will be slow on mainnet.
// In production, use the Tongo contract's deployment block instead.
const history = await tongo.getTxHistory(0, "latest", "all");

// Specific event types
const funds = await tongo.getEventsFund(0);
const transfersIn = await tongo.getEventsTransferIn(0);
const transfersOut = await tongo.getEventsTransferOut(0);
const withdrawals = await tongo.getEventsWithdraw(0);
const rollovers = await tongo.getEventsRollover(0);
const ragequits = await tongo.getEventsRagequit(0);

Operation Parameters

Operation	Required Fields	Optional Fields
fund	amount, sender	fee_to_sender
transfer	amount, to (PubKey), sender	fee_to_sender
withdraw	amount, to (address), sender	fee_to_sender
ragequit	to (address), sender	fee_to_sender
rollover	sender	--
outside_fund	amount, to (PubKey)	--

The fee_to_sender field enables relayer/paymaster patterns where a third party submits the transaction and receives a fee.

Error Handling

Error	Cause	Resolution
You dont have enough balance	Insufficient encrypted balance	Check state().balance before transfer/withdraw
Your pending amount is 0	Nothing to rollover	Wait for incoming transfer before rollover
Decryption of Cipherbalance has failed	Wrong private key or corrupted data	Verify Tongo private key matches account
Malformed or tampered ciphertext	Invalid encrypted data	Re-fetch state and retry
Transaction reverted on-chain	Invalid ZK proof	Ensure correct amounts and keys

Security Notes

• Critical: TONGO_PRIVATE_KEY is non-recoverable. There is no seed phrase or recovery mechanism. Loss of this key means permanent loss of all encrypted balances. Store it with the same care as an offline hardware wallet seed.
• Tongo private keys are separate from Starknet account keys
• Transfer amounts are encrypted on-chain; only sender, receiver, and optional auditor can see them
• Withdraw amounts are public (visible on-chain)
• No trusted setup: security based on discrete logarithm over the Stark curve
• Audited by ZKSECURITY
• ~120K Cairo steps per transfer verification

References

• Tongo GitHub
• Tongo SDK npm
• Academic paper (ePrint 2019/191)
• SHE Library (Starknet Homomorphic Encryption)