@flatcash/bearerswap

Private token transfers on Ethereum. Send any ERC-20 token without revealing sender-recipient links on-chain.

BearerSwap uses a commit-reveal pattern with a privacy relayer that adds timing randomization, breaking the correlation between deposit and withdrawal.

Install

npm install @flatcash/bearerswap ethers

Quick Start

import { BearerSwap } from '@flatcash/bearerswap';

// Initialize with your private key (sender)
const bs = new BearerSwap({
  privateKey: process.env.PRIVATE_KEY,
  rpcUrl: 'https://eth.drpc.org',
});

// 1. Commit tokens (locks them in the contract)
const { secret, nonce, txHash } = await bs.commit(
  '0x853d955aCEf822Db058eb8505911ED77F175b99e', // FLAT token
  '100.0',                                        // amount
  '0xRecipientAddress...'                         // recipient
);

console.log(`Committed! TX: ${txHash}`);
console.log(`Share these with recipient: secret=${secret}, nonce=${nonce}`);

// 2. Deliver (recipient or anyone calls this)
const delivery = await bs.deliver(secret, recipientAddress, nonce);
console.log(`Delivery queued! ETA: ${delivery.estimatedDeliveryMinutes} min`);

How It Works

Sender                    Contract                  Relayer                  Recipient
  |                          |                        |                        |
  |-- commit(hash, token) -->|                        |                        |
  |   (locks tokens + ETH)   |                        |                        |
  |                          |                        |                        |
  |--- share secret+nonce ---|------------------------|------> (off-chain) --->|
  |                          |                        |                        |
  |                          |                        |<-- deliver(s,r,n) -----|
  |                          |                        |                        |
  |                          |   (random 2-45 min)    |                        |
  |                          |                        |                        |
  |                          |<--- reveal(s,r,n) -----|                        |
  |                          |--- tokens + ETH -------|----------------------->|

Privacy guarantees:

• On-chain, the commit contains only a hash — no recipient info
• The relayer adds a random delay (2–45 min, exponential distribution)
• The recipient receives tokens + a small ETH stipend for gas
• No link between sender and recipient is visible on-chain

API Reference

new BearerSwap(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | relayerUrl | string | https://flat.cash | Relayer API URL | | rpcUrl | string | https://eth.drpc.org | Ethereum RPC endpoint | | privateKey | string | — | Sender's private key | | provider | ethers.Provider | — | Custom provider | | signer | ethers.Signer | — | Custom signer |

bs.commit(token, amount, recipient, decimals?)

Locks tokens in the BearerSwap contract. Returns { secret, nonce, commitHash, txHash }.

bs.deliver(secret, recipient, nonce)

Queues the reveal via the relayer. Returns { success, estimatedDeliveryMinutes, flatAmount }.

bs.status()

Returns relayer health: balance, queue size, availability.

bs.resolve(identifier)

Resolves a FlatID username or ENS name to an Ethereum address.

BearerSwap.computeHash(secret, recipient, nonce)

Static helper to compute the commit hash for verification.

Use Cases

AI Agent Payments

// Your autonomous agent pays for services privately
const bs = new BearerSwap({ privateKey: AGENT_WALLET_KEY });
const { secret, nonce } = await bs.commit(FLAT_TOKEN, '10.0', serviceProvider);
// Agent shares secret with service provider via API
await fetch(serviceProviderUrl, { body: JSON.stringify({ secret, nonce }) });

Private Payroll

// Pay employees without revealing individual salaries on-chain
for (const employee of employees) {
  const { secret, nonce } = await bs.commit(FLAT_TOKEN, employee.salary, employee.address);
  await sendEncryptedMessage(employee.email, { secret, nonce });
}

Tipping / Donations

// Anonymous tips to content creators
const { secret, nonce } = await bs.commit(FLAT_TOKEN, '5.0', creatorAddress);
// Share via any private channel

Supported Tokens

Any ERC-20 token on Ethereum mainnet. Primary tokens:

• FLAT (0x853d955aCEf822Db058eb8505911ED77F175b99e) — CPI-pegged stablecoin
• SAVE — Locked FLAT with yield

Contract

• BearerSwap V3: 0x5de315Dab49012c5bbeC41d7a3B25c6829a3e566
• Network: Ethereum Mainnet
• Verified on Etherscan: View Contract

Fees

• Protocol fee: 0 (no fees extracted)
• Gas: Sender pays commit gas + ETH stipend (~0.0004 ETH)
• Relayer: Free — operated by the FLAT Protocol

License

MIT — Flat Protocol team