Free, open-source, offline-first expense tracker and budget app for Android. Budgets, goals, dues, insights — all on-device. No server. No sign-up. No ads.
Track shared expenses for trips, homes and nights out. See who owes whom, settle up in fewer payments, and add as many expenses as you like. Free and open source.
13 specialized AI agents analyze Korean & US stocks in real-time. Open source, free to use.
Translation pending
8h +1★ 790Finance
Do you operate this project?
Owners of public repositories under a personal GitHub account can sign in to verify ownership and manage the introduction themselves. No administrator approval is needed.
Organization repository · verify with a repository file
Sign in, generate a verification file, and commit it to this repository’s default branch within 30 minutes. Files on other branches or forks do not count. Then check the file below to manage the project without administrator approval. Keep the file to retain your access.
If needed, you will go to sign-in. After signing in, return here and press your chosen verification button again.
Run /nomorevibe verify in your project folder to verify ownership and manage the introduction yourself.
Username-to-wallet identity layer for multi-chain crypto payments.
Replace 0x4f3edf83…d8a3c2 with @derrick. Paytag maps one human-readable name to your addresses on Ethereum, Base, Solana and Bitcoin. Names live in an immutable, admin-free registry on Base; the API reads them straight from the contracts; an npm SDK resolves them in one call; a web app registers and manages them from your wallet.
Zero config — the SDK ships with https://api.paytag.dev as the default base URL. To read on-chain state instead, use resolveViaIndexer('derrick'); it has the same shape plus owner, raw records and source: 'onchain'. See packages/sdk/README.md for resolveAddress, available, custom clients, and error codes.
Architecture
flowchart TD
U["User + browser wallet"] --> W["Web app<br/>paytag.dev"]
W -->|"signed tx"| C["PaytagRegistry + PaytagResolver<br/>Base Sepolia, immutable"]
O["API<br/>Express + Supabase"] -->|"eth_call (Multicall3)"| C
O -->|"events, lazily<br/>(lists only)"| C
O -->|"/onchain/*"| S["@paytagdev/sdk"]
O -->|"/onchain/*"| W
S --> W
S --> X["Any app"]
S -.->|"default source: off-chain /resolve"| O
Base is canonical. Ownership lives only in the registry; Solana, Bitcoin and other EVM chains are records on the name (ENSIP-9 coin types), never parallel deployments.
The contracts are immutable and admin-free. Lookups read current contract state directly, so there's no sync lag and nothing to go stale. The two lists that need history (names by owner, names pointing at an address) come from an events table that catches up only when a list is read, and every entry is re-checked against live state. RPC cost scales with use, not with time.
One SDK, two sources.resolve() reads the off-chain API (the original MVP), resolveViaIndexer() the on-chain registry (through the API's /onchain endpoints), with the same response shape.
/status probes the API (and its database), an on-chain lookup and the contracts live.
Every on-chain write in the app follows the same lifecycle (one hook, useOnchainTx, driven by a unit-tested state machine). Registration is shown: two transactions, a commit that hides the name and a reveal that claims it. Each write is simulated first, so failures surface before the wallet opens. Record edits work the same way. After the receipt, every on-chain read asks the API for at least that block (minBlock), so the page reflects the write without waiting for anything:
sequenceDiagram
autonumber
actor U as User
participant A as Web app
participant W as Wallet
participant B as Base Sepolia
participant P as API
U->>A: Register @alice
Note over A: Step 1: reserve (commit). The name stays hidden
A->>B: Simulate commit(hash(alice, wallet, secret))
A->>W: Request signature
W->>B: Broadcast commit
A->>B: Wait for receipt
Note over A: Countdown on chain time, at least 15 s
Note over A: Step 2: register (reveal)
A->>B: Simulate register("alice", secret) (eth_call)
alt Would revert
B-->>A: Custom error, e.g. NameTaken
A-->>U: Readable reason, and the wallet never opens
else Would succeed
A->>W: Request signature
alt Rejected
W-->>A: User rejected
A-->>U: "Rejected in your wallet"
else Signed
W->>B: Broadcast register
A->>B: Wait for receipt (a cancel or replacement counts as failure)
A-->>U: Done, with Basescan link
A->>P: GET /onchain/names?owner=…&minBlock=<receipt block>
P->>B: Multicall3: owner, epoch, records (at ≥ that block)
P-->>A: The new name, already yours
end
end
Layer
Choice
Contracts
Solidity 0.8.26, Foundry (unit, fuzz, invariant, gas snapshots)
On-chain reads
viem + Multicall3 against public Base Sepolia RPC (keyed fallback); lists from a Supabase events table synced via Blockscout
SDK
TypeScript, tsup (ESM + CJS), zero runtime dependencies
Runs the web app on your machine against the live API (Node 24, the version CI, Fly and Vercel run):
git clone --recurse-submodules https://github.com/ansah25/paytag && cd paytag
npm install
NEXT_PUBLIC_API_BASE_URL=https://api.paytag.dev npm run web:dev # http://localhost:3002
On Windows PowerShell, set the variable first: $env:NEXT_PUBLIC_API_BASE_URL="https://api.paytag.dev"; npm run web:dev.
Everything on-chain works from there (look up, register, manage, with a Base Sepolia wallet), as does resolving and sending to off-chain names. Signing in to claim an off-chain name needs your own API, because the hosted one only accepts sign-ins from paytag.dev. If a page can't reach the hosted services, check paytag.dev/status; the full-local setup below runs without them.
API (needs a Supabase project; the free tier is fine):
cp .env.example .env
# Fill in SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, JWT_SECRET (32+ chars)
Apply the schema once in your Supabase SQL editor by running each file in supabase/migrations/ in order (0001_init.sql through 0008_onchain_events.sql), then:
npm run dev # API on http://localhost:3000
npm run web:dev # web app on http://localhost:3002, using the local API by default
The local API reads Base Sepolia over the public RPC; its on-chain lists catch up on the first request (or run npx ts-node --transpile-only scripts/onchain-backfill.ts once).
Contracts:cd contracts && forge test (see Contract tests).
On-chain protocol (Base)
Live on Base Sepolia (contracts v0.2): register a name in two steps (commit, then reveal), point it at your addresses on each chain, make it your wallet's primary name, transfer it, and resolve it publicly at paytag.dev/on-chain/<name>. See Architecture for how the pieces connect.
Design: Base is the canonical registry. Solana and Bitcoin addresses live as records on the EVM name (keyed by ENSIP-9 / SLIP-44 coin type), not as parallel deployments. One source of truth for ownership; every other chain is resolved through records. Both contracts are immutable and admin-free.
Per-chain address records scoped to the current epoch, forward-verified reverse resolution
What v0.2 enforces in the contracts:
A transfer clears the name. Each name carries an epoch, stored in the same slot as its owner, and a transfer to a different owner increments it. Records are keyed by (name, epoch), so the previous owner's addresses stop resolving at once, for every reader, including anyone calling addr() directly. Their primary name goes dark with them, because reverse() only accepts the current epoch's ETH record.
Commit-reveal registration.commit(hash) first; register(name, secret) between 15 seconds and 24 hours later. The name isn't legible on-chain or in the mempool before the transaction that claims it, and the minimum age keeps commit and reveal in different blocks. Commitments are stored per committer, so nobody can disturb someone else's.
Name rules match the API exactly: 3–20 characters, [a-z0-9_], ASCII A–Z lowercased, everything else rejected, and the API's reserved usernames (paytag, admin, support, …) blocked forever. A backend test (tests/reservedOnChain.test.ts) fails if the two reserved lists drift apart.
Deployed addresses
Base Sepolia (chain 84532), verified on Basescan and Sourcify. Deployed at block 48167395 from the Deploy script; the full record is in contracts/broadcast/. The ABI is frozen at tag v0.2.0-contracts.
v0.1 (0xC465…5012 / 0xdd08…9142, tag v0.1.0-contracts): records survived a transfer (a known trade-off when it shipped), and so did primary names (found while building the indexer the same day); only the indexer hid both, and only from its own readers. Registration had no commit-reveal. Writing the design write-up made the case for moving both fixes into the contracts; v0.2 does that. Before v0.2 was deployed, an independent review also caught a commitment-griefing bug in its first draft (a shared commitment map let anyone restart another user's clock); commitments are now stored per committer.
Pre-v0.1 (0xf082…8721 / 0xa403…e828): a pre-merge review found that it emitted misleading events for zero-address ETH records and lacked the reserved-name blocklist. Nothing was built on it.
Tests, coverage, gas
The contracts are covered on every metric, not just lines: 100% of lines, statements, branches (23/23) and functions in both contracts (forge coverage). The strongest evidence is the 6 stateful invariants below, checked against a full ghost model over 256 random sequences per run (16,384 calls locally, 32,768 in CI's deeper profile). Alongside them, in contracts/test/:
Unit: every external function, including each revert path (length bounds, charset, non-ASCII/homoglyph bytes, reserved names and their case variants, taken names and case variants, non-owner writes, ETH record length and zero address, reverse mismatch), commit-reveal (too new, too old, same-block reveal, exact bounds, wrong secret, reveal from another wallet, reuse, a pending reveal raced by a fresh commitment, a griefer re-committing your public hash, retrying after a reverted reveal) and epochs (transfer clears records and the old owner's primary name, self-transfer keeps them, A → B → A starts empty).
Fuzz:testFuzz_normalizeIsIdempotent, testFuzz_normalizeMatchesReference (contract vs. an independent reference model over arbitrary bytes, including the exact revert reason), testFuzz_registerThenResolve, the reserved list, ownership and reverse authorization.
Invariants: a stateful handler drives random register / transfer / setRecord / setReverse sequences across five actors against a full ghost model of owners, epochs, records and reverse claims. Every registration goes through commit-reveal with a griefer re-committing the public hash just before it matures, and a separate action tries to register without a usable commitment. After every call it checks that:
every registered node has exactly one owner, writes succeed exactly when the caller owns the node, and owner writes with valid input never revert
every name's epoch equals the number of transfers to a different owner
every record the resolver serves equals the last value the current owner wrote in the current epoch; anything from before the latest transfer reads as empty
reverse(a) is exactly the model's answer, and round-trips (addr(reverse(a), 60) == a) wherever it is set
no two distinct names collide to the same node, no name or case variant registers twice, and no reserved name registers at all
no registration ever succeeds without the caller's own, mature commitment
Mutation-checked during development (the mutants aren't committed): for v0.1, seven deliberate bugs, each caught by the invariant suite (commit 3e558ab): reverse always returning zero, owner ETH writes reverting, non-ETH records dropped, transfer always reverting, the reverse re-check removed, the reserved check removed, and the transfer auth check removed. For v0.2, five more (PR #14): no epoch bump on transfer, the minimum commitment age removed, addr ignoring the epoch, reverse ignoring the epoch, and a shared commitment map.
File
Lines
Statements
Branches
Functions
PaytagRegistry.sol
100% (59/59)
100% (64/64)
100% (13/13)
100% (12/12)
PaytagResolver.sol
100% (28/28)
100% (39/39)
100% (10/10)
100% (5/5)
Every package's tests run in CI on each push: contracts (unit, fuzz, invariants, and a gas-snapshot drift check), backend, SDK, and web (including a drift check that the app's copies of the ABIs, codec and name rules match the API's).
Registering now takes two transactions, so it costs a commit plus a register (about 96–100k gas before base costs, against 51–55k in v0.1). A transfer costs almost the same, because the epoch shares the owner's storage slot and is written in the same SSTORE. Reads that check the epoch (addr, reverse, setReverse) pay for one cold call to the registry, about 5.4k gas inside a transaction; reading a name off-chain through eth_call costs nothing either way. setRecord already called the registry for the owner, and now gets the epoch from the same call.
Before v0.1 shipped, an optimization pass made two changes that v0.2 keeps:
In-place normalization.register used to allocate a second buffer and copy byte by byte. It now lowercases the calldata copy in place inside an unchecked loop, with single-comparison range checks (uint8(c - 0x61) < 26). The saving scales with name length.
Packed ETH records. Coin type 60 moved out of mapping(… => bytes) into a dedicated mapping(bytes32 => address). Reverse checks are now one SLOAD with no memory decode.
The reserved-name check costs about 800 gas per register (28 hash comparisons; it also adds about 1.3 KB of bytecode). The zero-address check costs 73 gas per ETH write.
What I didn't change, and why: writes are dominated by the 22.1k cold SSTORE, which no layout trick avoids. A 32-byte Solana key costs two slots (length + data) because Solidity only inlines bytes of up to 31 bytes. Packing it into one bytes32 would need a coin-type-specific layout, adding complexity for about 20k gas once per record. I wasn't willing to make that trade.
On-chain reads
Served by the API under api.paytag.dev/onchain, same response shapes as the Ponder indexer that used to serve them (so the SDK's resolveViaIndexer reads them unchanged). The indexer polled the chain every second, roughly 86,000 RPC calls a day, to watch two contracts that emit almost nothing. It was decommissioned on 2026-10-24 (service, database and the indexer.paytag.dev DNS record), and RPC cost now scales with reads instead of with time. SDK versions before 0.7.0 default resolveViaIndexer to that host; point their indexerUrl at https://api.paytag.dev/onchain, or upgrade.
Endpoint
Returns
GET /onchain/resolve/:name
{ username, node, owner, registeredAt, epoch, recordsReset, addresses, records, source: "onchain" }. Same base shape as the API's /resolve. epoch counts transfers to a different owner; recordsReset is true when the name changed owner and the current owner hasn't set a record since
GET /onchain/reverse/:address
{ address, username }. username is null unless the claim is live (PaytagResolver.reverse())
GET /onchain/available/:name
{ available, reason?, suggestions }. Format, the registry's reserved list, then taken
GET /onchain/names?owner=0x…
Names an address owns now
GET /onchain/pointing?account=0x…
Names whose ETH record is the address but which it doesn't own (candidates for its primary name)
resolve, reverse, names and pointing take ?minBlock=<n>: the answer reflects at least block n (the app passes the block of the write it just made), or is 503 { code: "ONCHAIN_BEHIND" } if the RPC hasn't reached it. An RPC outage is 503 { code: "ONCHAIN_UNAVAILABLE" }.
How it works:
Lookups read the contracts directly. One eth_call to Multicall3 per lookup: owner, epoch, the ETH / Base / SOL / BTC records and the block number, all at the same block. Current state, so there's no sync lag and nothing to go stale. Cached for 30s like the rest of the API (negative answers too); minBlock skips an entry read before that block. The contracts can't list a name's records, so records holds the coin types the app writes.
Lists come from an events table that syncs lazily.onchain_events (migration 0008) keeps NameRegistered, Transfer and RecordSet. When a list is requested, the API catches the table up to head - 10 (a reorg margin), reads the few blocks past it fresh, and re-checks every candidate against live state. So a stale or reorged row can make a list miss a name for a moment, never show a wrong one. The catch-up uses Blockscout's logs API (one call per contract for any gap); if that fails (or hasn't finished indexing), eth_getLogs in 200-block chunks (the public RPC refuses ranges over 200), at most ONCHAIN_MAX_CHUNKS_PER_REQUEST per request, with progress persisted.
Shared state lives in Postgres. The cursor is one row, shared by every Fly machine, and a lease on it (taken with a conditional UPDATE, expiring by itself) makes a second concurrent sync skip rather than duplicate work. Not an advisory lock: PostgREST runs each call on a pooled connection, so a session lock would stick to whichever connection took it.
RPC endpoints. The public https://sepolia.base.org first (from web/lib/endpoints.json, the same entry the CSP allows), then BASE_SEPOLIA_RPC_FALLBACK_URL if set (a keyed provider; server-side only).
Name text is checked. A NameRegistered row is only stored if the name hashes to its node, since the name (and registration time) can't be re-checked against contract state later.
Reserved names are answered locally from the registry's hard-coded hashes (generated into src/onchain/generated/reservedNodes.ts and drift-checked in CI).
Records use ENSIP-9 encodings: SOL is the raw 32-byte key, BTC is the scriptPubKey, EVM chains are 20 address bytes. Test vectors are in tests/onchain/vectors.json.
Rollout of a fresh deployment: run migration 0008, then npx ts-node --transpile-only scripts/onchain-backfill.ts once, so no request ever pays for the backfill. A daily keep-alive workflow reads Postgres (a free Supabase project pauses after a week without activity) and keeps the events table near the head.
Known trade-offs
Free, first-come, permanent registration. Commit-reveal stops a pending reveal from being raced, as long as it lands within 15 seconds of being broadcast (before a competitor's fresh commitment could mature), but not first-come squatting: anyone can register any free name for the gas of a commit and a register, with no fees or expiry. That's acceptable on a testnet; a mainnet deployment would want pricing or expiry.
Registration is two transactions, at least 15 seconds apart. The app runs the countdown and keeps the commitment's secret in the browser until the reveal; losing it just means reserving again.
A transfer clears everything, including a return. After a transfer away and back (A → B → A), A starts from empty records and has to set them again. The app shows such a name as Unconfigured, and the API reports recordsReset, rather than letting it quietly resolve to nothing.
Two namespaces, linked by ownership. On-chain names (the Base registry, at /on-chain/<name>) and Paytag accounts (the off-chain API, at paytag.dev/<name>) keep separate records. A Paytag account is linked when the on-chain name of the same spelling is owned by the account's verified Ethereum address; the API reads the registry when it builds a resolution (cached in memory for 30s, like the rest of it) and stores nothing in the database. New Paytag signups can't take a name held on-chain by another wallet (409 USERNAME_TAKEN_ONCHAIN), but the contract is permissionless, so the reverse can't be enforced: the /on-chain app warns and asks for confirmation instead. Only public data is compared, so the link status never reveals which wallet registered an account. While the registry is on testnet, on-chain isn't canonical: if the chain can't be read, signups go ahead.
On-chain reads cost a registry call.addr and reverse read the current epoch from the registry, about 5.4k gas inside a transaction. Free off-chain.
ASCII-only names. This removes Unicode homoglyphs entirely. ASCII lookalikes (0/o, 1/l) remain, so names are displayed in a monospace font.
Fixed reserved list. The contract has no admin, so the blocklist can't change after deployment. Adding a reserved name means a redeploy, and the drift test enforces that.
Registration pays its own gas. Gas sponsorship through a paymaster was evaluated and deferred, to keep the first on-chain release dependency-free and the registration path identical for every wallet.
Contract tests
git submodule update --init --recursive
cd contracts && forge test
API
Method
Path
Auth
Description
GET
/health
—
Health check
GET
/auth/nonce?wallet=0x…
—
Issue nonce for wallet signing
POST
/auth/verify
—
Verify the signed SIWE message ({ wallet, signature, nonce, domain }), return JWT
POST
/auth/logout-all
JWT
Revoke every session of the account
POST
/register
JWT
Register a username
GET
/me
JWT
The wallet's username and profile
PATCH
/me/profile
JWT
Update display name (≤ 40) and bio (≤ 120); null clears
POST
/add-address
JWT
Add or update an address for a chain (resets its verification)
DELETE
/address/:chain
JWT
Remove the address for a chain
POST
/verify-address/nonce
JWT
Get a single-use message to sign with a mapped address (Ethereum, Solana)
POST
/verify-address
JWT
Submit the signature; marks the address verified
GET
/resolve/:username
—
Resolve username → addresses, verification, profile and on-chain link status
GET
/available/:username?wallet=0x…
—
Check availability, with suggestions. TAKEN_ONCHAIN when the name is held on-chain by a wallet other than wallet
Sign-in nonces are stateless: each carries its issue time and a MAC binding it to the wallet, and nothing is stored when one is issued, so requesting a nonce can never invalidate someone else's. They expire after NONCE_TTL_SECONDS and are single-use (spent nonces are recorded on successful sign-in and remembered well past their lifetime). /auth/nonce, /auth/verify and /register share a limit of 20 requests a minute per client IP. Every string input has a length cap, and published addresses are checksum-validated per chain (EIP-55, base58check, bech32/bech32m, 32-byte Solana keys).
Public read endpoints (/resolve, /available, /onchain/*, /health) are CORS-open. /resolve responses carry Cache-Control: public, max-age=30, stale-while-revalidate=60. /resolve, /available and /onchain/* share a limit of 120 requests a minute per client IP (per API machine; the web app's server-rendered pages present API_SERVER_KEY instead); over it, 429 { code: "RATE_LIMITED" } with Retry-After. In production the API sits behind Cloudflare: a Transform Rule adds a secret x-paytag-edge header, the API refuses requests without it (except /health, for Fly's checks), and the limit keys on Cloudflare's CF-Connecting-IP. IPv6 clients are limited per /64. Roll out in this order: add the Transform Rule first (harmless on its own), then set EDGE_SECRET on Fly; the other way round refuses every real request. /ping is /health behind the guard (it also reads Postgres), and www.paytag.dev/status probes it, so a mismatch shows there as the API being down. Only one secret is accepted, so rotating it means a short window of 403s between changing the rule and the Fly secret.
onchain.status is linked (the on-chain name's owner is the verified ethereum address), not_linked (held on-chain, by another address), none (not registered on-chain), or unavailable when the chain couldn't be read. (syncing is no longer sent: the API reads the registry directly.) /resolve and /available wait up to 800ms for the read and /register up to 1s, then carry on without the answer.
When Postgres can't be reached, any endpoint that reads it answers 503 { code: "DATABASE_UNAVAILABLE" }, which clients can retry. The API itself doesn't retry: each Supabase request gets SUPABASE_TIMEOUT_MS (default 5s), once, then fails. /register is safe to retry after a 503: if the earlier attempt had committed, the same wallet asking for the same name gets its account back instead of USERNAME_TAKEN. Resuming a paused project: a paused Supabase project doesn't wake on a request (it's restored from the dashboard), and its first queries after a restore can take longer than 5s. Those return 503 and /status shows the database down, even though the project is up and warming. If the 503s persist for more than a minute or two after a restore, raise the budget until it's warm (flyctl secrets set SUPABASE_TIMEOUT_MS=30000, then unset it).
{ "error": "Username not found", "code": "USER_NOT_FOUND" }
Auth flow
Client calls GET /auth/nonce?wallet=0x…&domain=<its host> → receives { nonce, message }. domain must be on the API's SIWE_DOMAINS allowlist and, from a browser, match the request's Origin.
Client signs message exactly as given: a Sign-In with Ethereum (EIP-4361) message naming the domain, so wallets warn when another site asks for it.
Client POSTs { wallet, signature, nonce, domain } to /auth/verify → receives { token, wallet }. The API rebuilds the message itself; without nonce/domain it answers 400 CLIENT_OUTDATED.
Client uses Authorization: Bearer <token> on protected routes. Tokens last 24 h, name their issuer and audience, and carry the account's session version: POST /auth/logout-all signs the account out everywhere.
Sign-in is EOA-only (ecrecover); smart-contract wallets (EIP-1271) can't sign in yet.
Nonces are stateless (issued with a MAC binding them to the wallet; nothing stored at issue), TTL-bounded (default 300 s) and single-use: a successful sign-in records the nonce in auth_nonces_used, kept well past the TTL, so a replay is refused.
Username rules
Lowercase, 3–20 characters, [a-z0-9_]. One username per wallet.
Contracts v0.2: transfer epochs (a transfer clears records and the old owner's primary name, in the contract) and commit-reveal registration; SDK 0.4.0
Link on-chain names and Paytag accounts by ownership; SDK 0.5.0
Retire the Ponder indexer: on-chain reads straight from the contracts, lists from a lazily synced events table; SDK 0.7.0. Indexer decommissioned 2026-10-24
