sparkname: a command-line tool for Spark Name transfers by apeir

Goal: 450 FIRO ($314.21) Wallets
Proposal Seeking community approval

Why?

Spark Name transfers went live with the November 2025 upgrade, but there is still no wallet button for them. The Spark Names guide tells people to open Help → Debug window → Console and run three RPC commands across two wallets:

  1. the receiver runs requestsparknametransfer and sends the hash to the sender,
  2. the sender runs transfersparkname and sends a proof back,
  3. the receiver runs registersparkname with six arguments.

All three calls must repeat the same name, addresses, years and additional data exactly. A mistake only shows up when the final transaction is rejected, and the node usually says nothing more than "Spark name transaction was rejected". The sender is also asked to sign a hash they cannot read: nothing in the console flow shows them which address they are giving the name to.

Names are starting to change hands (the registry has around 500 names, and short names cost 10–1,000 FIRO a year), so this is the step where users lose time or make mistakes. Neither Firo Core's GUI nor the mobile Spark library supports transfers today (sparkmobile's sparkname.h says "registration-only").

What?

sparkname, a small open-source command-line tool, already built: https://github.com/apeirs/sparkname

  • sparkname request NAME: receiver creates a request file (looks up the current owner address, picks a fresh address from their wallet, calls requestsparknametransfer).
  • sparkname approve request.json: sender's node recomputes the request hash itself and refuses to sign if it doesn't match, then shows name, from, to, term and fee, asks for confirmation and calls transfersparkname (optional unlock-and-relock).
  • sparkname complete request.json proof.json: receiver re-checks everything and broadcasts the registersparkname transfer.
  • sparkname status NAME --txid …: who holds the name, expiry, and whether the transfer has been mined.
  • Checks done before anything is signed or paid: the name is still registered to the address in the request; it hasn't been renewed since (v2.1 binds the proof to the expiry height); the sender's wallet holds it; the new address belongs to the receiver and has no name yet; remaining validity plus the new years stays within 15 years; the receiver's private balance covers the name fee. Error messages from the node come with a next step.
  • One Python file, standard library only, talks to the user's own firod over JSON-RPC (same credential lookup as firo-cli). It never handles keys: signing stays in the wallet.
  • 30 offline tests against a fake node that enforces the same rules, plus a README with a full worked example.
  • Tested against a real node: on 2026-10-14 I ran the official Firo Core v0.14.18.1 release (checksum and [email protected] signature verified) as two regtest nodes past the Spark Names v2.1 height and moved a name back and forth with the tool. The txids, heights and transcript are in the README. Highlights: alice → bob 275d8cc876a3e8b9a29e5656fa58fc37860264b8fc7aa8c703851bc377a11175 (bob paid 1 FIRO + 0.00076728 network fee; validity stacked to height 423302), then bob → alice from an encrypted wallet with --unlock and additional data, 65f56763f7f2c2e13c3049905942ed11914a7aaf9d9ac9310bf8558c59558322. The refusals (edited request, wrong wallet, stale proof, 15-year cap and others) were checked against the real node too. The run turned up two node behaviours a console user would trip over, and the tool now handles both: requestsparknametransfer hashes a wrong old address without complaint, and a locked wallet reports a non-zero unlocked_until.
  • MIT licensed. On funding, copyright is assigned to the Firo Project as the FCS rules require.

How much?

450 FIRO in total (≈ $418 at $0.93/FIRO).

item hours
Reading the transfer consensus code (PRs #1663, #1696, #1844, v2.1 inputs hash) and designing the flow 3
Tool: request / approve / complete / status, pre-checks, error mapping 5
Test suite (fake node with firod's rules, RPC transport tests) 3
README and worked example 1
Testnet end-to-end run, firo-site guide PR, review fixes (milestones below) 2
Total 14 h

14 hours at about $27/hour is $378; with the 10% volatility premium the FCS rules allow, that is $416, or 450 FIRO.

Milestones

# deliverable FIRO
1 Repository public and tagged v1.0 (done at submission; regtest run already done, see above). A real end-to-end transfer of a Spark Name between two wallets on Firo testnet, with both transaction ids and the command transcript added to the README so anyone can check them on the public explorer. 300
2 A pull request to firoorg/firo-site adding the tool to the Spark Names guide as an alternative to the console steps (merging is up to the maintainers), and 60 days of bug fixes for issues reported on GitHub or the forum. 150

Payout per milestone to the address in the proposal. If the community would rather see this inside Firo Core's Qt wallet, the tested flow and checks here carry over directly, and I'm happy to discuss that as a separate follow-up proposal.

— apeir

Events
  • Proposal created 2026-10-14 20:26
  • Discourse topic posted 2026-10-14 20:26
Meta
firo
This proposal is being discussed. Donation details will appear once the proposal is moved to the next stage.