walsmith-core

Source code backing the security-sensitive parts of walsmith.fun — a Solana vanity-wallet forge.

This repository is the transparency layer. If you're about to pay Walsmith for a wallet and want to verify the claims we make about how those wallets are generated and handled, this is the code you read.

TL;DR: The trustless tier generates your key entirely inside your own browser. Our server hosts a static page and takes a payment. It never sees, logs, or stores your private key. The code below is the entire key-generation pipeline. Audit it.

---

What's here

Path	What it is
web/trustless/	The pages your browser actually runs. Open index.html in your editor — keygen happens in worker.js via crypto.getRandomValues() + libsodium.crypto_sign_seed_keypair. Zero network calls send the key anywhere.
shared/crypto.py	NaCl SecretBox wrapper used for at-rest encryption of inventory / deposit keys (server-side). Standard XSalsa20-Poly1305.
shared/base58.py	Solana-alphabet base58 helpers.
shared/ed25519.py	Ed25519 scalar math primitives — legacy from an earlier trustless-tier design, kept for reference.
bot/trustless.py	HMAC-SHA256 scanner-unlock tokens + pricing tiers. This is the code that authorizes your browser to run the scanner after payment. Token body is signed with our master key; you can decode the body (it's public base64-json) but can't forge a new one.
bot/api_keys.py	B2B wallet-gen API — sha256 key hashing (plaintext never persisted), atomic purchase_inventory_atomic (single SQLite transaction covering inventory mark-sold + credit debit + purchase audit row).
bot/db.py	SQLite schema + CRUD for every persistent object: orders, inventory, payments, alert_subs + alert_events, gifts, api_keys, api_purchases, trustless_redemptions, discount_codes, kv_settings. No secrets.
bot/config.py	.env loader + lazy master-key accessor.
tests/	58 unit tests across: HMAC forgery + expiry + lamports math, discount code lifecycle, gift claim atomicity, API key sha256-at-rest, alerts DB layer. Run with python -m unittest discover tests (see note below on env var).

What's NOT here (and why)

Walsmith is a running commercial service. Some components are intentionally kept private:

• aiohttp endpoints (bot/api.py) — the HTTP routes themselves live behind the server. Their behaviour is testable via live HTTPS (rate limits, auth, response schemas). The security-critical modules they call (api_keys, trustless, db) are in this repo.
• Payment watcher + sweep loop (bot/payments.py, bot/sweep.py) — detects Solana deposits and moves funds to treasury. Not a customer-key codepath.
• Scanner + AI curator (scanner/*, tools/find_flagship.py) — our pattern-hunting rig and the AI curation tooling are our operational moat.
• Telegram bot handlers + admin dashboard (bot/handlers.py, bot/admin.py) — UI, not security.
• Operational config + secrets — .env, live DB, server IPs, cron specifics.
• On-chain alerts + Helius webhook management (bot/alerts_*, bot/helius_webhooks.py) — alerts are a separate product; code stays closed until we decide it adds audit value.

We may open more of this later. For now: the trustless-tier integrity claim and the B2B API auth/credit logic both stand on what's in this repo, and that's what we're inviting you to verify.

How to audit the "trustless" claim yourself

1. Read web/trustless/worker.js. This is the Web Worker that does keygen.

   • Seed: crypto.getRandomValues(new Uint8Array(32)) — browser's CSPRNG.
   • Keypair: sodium.crypto_sign_seed_keypair(seed) — libsodium's standard Ed25519 derivation.
   • Match test: bs58.encode(publicKey).startsWith(pattern) (prefix mode) or .endsWith(...) (suffix mode).
   • On hit: self.postMessage({ type: "found", address, secret, ... }) — published ONLY to the main-thread worker handler, never sent over the network.

2. Read web/trustless/index.html. The only calls that leave your browser to our server are:

   • GET /api/trustless/price — price quote, returns tier table.
   • POST /api/trustless/create-deposit / POST /api/trustless/redeem — requests a deposit address or validates a Phantom tx. Body contains the pattern you chose but not the generated key (the key doesn't exist yet at this point).
   • GET /api/trustless/check-deposit/:id — polls for payment confirmation.
   • POST /api/gift/register — if you create a gift link, sends the AES-GCM ciphertext of your key, never the key itself. The AES key is stored in the URL fragment which browsers don't send in the request line.

   Open DevTools → Network tab. Run a full generation. Confirm no request ever contains the sk64 in its body.

3. Run the tests. pip install pynacl base58, then TELEGRAM_BOT_TOKEN=x python -m unittest discover tests. 58 assertions pass covering HMAC forgery, expiry, tamper detection, pricing math, discount code lifecycle, gift claim atomicity, API key sha256-at-rest, and alerts-bot DB layer. (The TELEGRAM_BOT_TOKEN=x placeholder is because bot/config.py loads .env at import and refuses to start without a token — set any non-empty value to satisfy it.)

4. Skim bot/trustless.py. The HMAC token is standard hmac.new(key, body, hashlib.sha256). No custom crypto. No bespoke key derivation. If hmac.compare_digest is secure (it is), our token is secure.

Gotchas we want you to see

• The Phantom Connect flow (Path A) lets you pay directly with a wallet extension. Phantom pays the Solana network fees, broadcasts the signed tx, and returns a signature to our server. We verify the signature on-chain via Helius getTransaction before issuing the unlock token.
• The manual deposit flow (Path B) gives you an ephemeral Solana address that lives only for that session. The per-session secret key lives encrypted at rest under MASTER_KEY_B64; we decrypt ONLY when sweeping funds to the treasury. Customer's own vanity key is never generated in this flow.
• Gifts are one-shot by design. The POST /api/gift/:id/claim endpoint atomically sets opened_at the first time it's called. Everyone else hits 410 Gone. The decryption key lives in the URL fragment (the #k=... part) — browsers never send fragments in HTTP requests, so a server breach cannot recover claimed gifts' plaintexts.

Report a security issue

Open a private security advisory from this repo's Security tab. See SECURITY.md for the full threat model + disclosure policy.

License

MIT. See LICENSE.