Confidential Transfers (Tongo Cash)
Privacy-preserving token transfers using ZK proofs on Starknet. Amounts are hidden on-chain; recipients are identified by elliptic curve public keys, not Starknet addresses.
Prerequisites
- Active session required. If not authenticated, run
authenticate-walletskill first. - Tongo credentials configured (
conf-setup). Must be done once before any other confidential command. - Sufficient public token balance for
conf-fundoperations. - StarkFi v0.8.0 or later. In v0.7.2 and earlier every confidential command except
conf-setupfails with a… is not a constructorerror (the package shipped without the Tongo SDK). If you see that error, tell the user to update StarkFi; do not retry.
Rules
- BEFORE any confidential operation, run
npx starkfi@latest statusto verify authentication. conf-setupMUST be called before any other confidential command. It only needs to run once.- BEFORE
conf-fund, checkbalanceto verify sufficient public token balance. - BEFORE
conf-transferorconf-withdraw, checkconf-balanceto verify sufficient active balance. - After the recipient receives a transfer, remind them to run
conf-rolloverto activate pending balance. conf-ragequitis a DESTRUCTIVE operation — it empties the entire confidential balance. Always warn the user and get explicit confirmation.- AFTER any transactional operation (
conf-fund,conf-transfer,conf-withdraw,conf-ragequit,conf-rollover), verify withtx-status. - The Tongo private key is stored locally at
~/.local/share/starkfi/confidential.jsonwith strict0o600permissions and is never sent to the network.
Setup (One-Time)
The user first needs a Tongo Private Key. They can generate or export this key through the Tongo Cash or refer to the Tongo Documentation.
npx starkfi@latest conf-setup --key <TONGO_PRIVATE_KEY> --contract 0x1234…
Commands
Check Balance
npx starkfi@latest conf-balance [--json]
Returns: active balance, pending balance, nonce, Tongo address.
Fund Confidential Account
Move public ERC-20 tokens into a private confidential balance.
npx starkfi@latest conf-fund <amount> [--token <symbol>] [--simulate] [--json]
Transfer Confidentially
Send tokens privately to another Tongo account. Recipient is identified by their public key coordinates (x, y).
npx starkfi@latest conf-transfer <amount> --recipient-x <x> --recipient-y <y> [--token <symbol>] [--simulate] [--json]
Withdraw to Public
Convert private balance back to public ERC-20 tokens.
npx starkfi@latest conf-withdraw <amount> [--to <address>] [--token <symbol>] [--simulate] [--json]
Ragequit (Emergency Exit)
Withdraw the entire confidential balance to a public address immediately.
npx starkfi@latest conf-ragequit [--to <address>] [--json]
Rollover (Activate Pending)
Received transfers start as "pending" and must be rolled over to become spendable.
npx starkfi@latest conf-rollover [--json]
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
amount |
number | Amount for fund/transfer/withdraw | Yes |
--key |
string | Tongo private key (setup only) | Yes (setup) |
--contract |
string | Tongo contract address | Yes (setup) |
--recipient-x |
string | Recipient public key X coordinate | Yes (transfer) |
--recipient-y |
string | Recipient public key Y coordinate | Yes (transfer) |
--token |
string | Token symbol (default: USDC) |
No |
--to |
string | Recipient Starknet address | No |
--simulate |
flag | Estimate fees without broadcasting | No |
--json |
flag | Output as JSON | No |
Examples
User: "Set up my Tongo account"
npx starkfi@latest conf-setup --key <KEY> --contract 0x1234…
User: "Fund 100 USDC into my confidential account"
npx starkfi@latest status
npx starkfi@latest balance --token USDC
npx starkfi@latest conf-fund 100 --token USDC --simulate
npx starkfi@latest conf-fund 100 --token USDC
npx starkfi@latest tx-status <hash>
User: "Send 50 privately to this public key"
npx starkfi@latest conf-balance
npx starkfi@latest conf-transfer 50 --recipient-x 0xABC --recipient-y 0xDEF --simulate
npx starkfi@latest conf-transfer 50 --recipient-x 0xABC --recipient-y 0xDEF
npx starkfi@latest tx-status <hash>
User: "Withdraw 100 from my confidential account"
npx starkfi@latest conf-balance
npx starkfi@latest conf-withdraw 100 --simulate
npx starkfi@latest conf-withdraw 100
npx starkfi@latest tx-status <hash>
User: "Emergency withdraw everything"
# WARN: This empties the entire confidential balance
npx starkfi@latest conf-ragequit
npx starkfi@latest tx-status <hash>
User: "Activate my pending balance"
npx starkfi@latest conf-rollover
npx starkfi@latest tx-status <hash>
Error Handling
| Error | Action |
|---|---|
CONFIDENTIAL_NOT_CONFIGURED |
Run conf-setup with valid Tongo key and contract address. |
CONFIDENTIAL_FAILED |
Check balance, credentials, and retry. |
Insufficient balance |
Check conf-balance for active balance before operations. |
Not authenticated |
Run authenticate-wallet skill first. |
Related Skills
- Use
authenticate-walletto ensure an active session before confidential operations. - Use
balanceto verify public token balance before funding. - Use
sendfor standard (non-private) token transfers. - Use
configto set a custom RPC if experiencing rate limits.