Migration from console wallet

[SWvheerden]

Bounty: Migration from Console Wallet

Tier: L — 150,000 XTM

Description

Implement a migration path that imports an already-synced console wallet database into the new wallet format. The migrated wallet must preserve display transaction IDs so that users see the same transaction history they had in the console wallet. Importing from a pre-synced database avoids the slow full-chain rescan that would otherwise be required via a base node.

Acceptance Criteria

• A CLI command or workflow accepts a synced console wallet database file and imports it into the new wallet
• All completed transactions from the console wallet appear in the new wallet with identical display transaction IDs
• The migrated wallet shows the same balance as the source console wallet
• The migrated wallet contains the same set of unspent outputs as the source
• A test or demonstration proves round-trip correctness (export → import → verify balance and transaction IDs match)

Context

• Original issue: Migration from console wallet #119
• The console wallet stores transaction history in a local SQLite database
• Display transaction IDs are the primary user-facing identifier and must not change during migration
• Risk surface: touches wallet balances and transaction state — sized L accordingly

How to Claim

1. Comment on this issue to signal intent (courtesy, not a lock)
2. Fork the repo and do the work
3. Submit a PR that meets the acceptance criteria
4. First PR that passes review and gets merged wins the bounty
5. On acceptance, XTM payment is processed

Notes

• AI-assisted development is expected and encouraged
• If you get stuck, ask in Discord

[metalaureate]

Original issue description (preserved before bounty rewrite)

We need to be able to do a migration from an already sync console wallet.
We need to keep the display transaction id's the same as the completed transactions, this is the single most important item we need from the migration.
But it will be much faster to complete the sync via a console wallet database then rescan the chain via a base node.

Effort

Meduim

Acceptance criteria:

• Needs to take a console wallet with a scanned database, import this
• After import it needs to have all the same transactions (completed in cw vs display in new wallet)
• Needs to have the same balance
• Needs to have the same set of unspent outputs.

[0xPepeSilvia]

Signalling intent to work on this. Will open a PR shortly.

[0xPepeSilvia]

PR up: #121.

Implementation summary:

• New migrate-from-console-wallet subcommand reads the legacy console wallet's SQLite, re-derives the cipher seed via Argon2id + Blake2b-256 + XChaCha20-Poly1305 to authenticate the source password, then writes the migrated state into a new account.
• Display transaction IDs are preserved verbatim from the source's completed_transactions.tx_id into the destination's displayed_transactions.id (the primary AC).
• Source's last scanned block is copied into scanned_tip_blocks so the next scan does not redo the chain.
• Whole migration runs in a single SQLite write transaction; any failure rolls back the destination DB.
• Five round-trip unit tests in migrate::tests cover cipher seed recovery, wrong-password rejection, transaction ID preservation, scan-tip propagation, and duplicate-account rejection. 81/81 unit tests pass.

Documented in the PR body which acceptance criteria each piece covers.

[sanrishi]

Hey @metalaureate and @SWvheerden, submitting my implementation for #119!

I focused heavily on making this production-safe for real-world legacy wallets. I spent some time ensuring the migration handles complex legacy UTXO groupings without violating the new wallet's strict SQLite constraints, and mapped the history in a way that is completely safe for the background transaction monitors.

Included a --dry-run flag and a full integration test suite (7 tests) that verifies exact 1:1 balance parity to the micro-token. CI is 100% green and most important thing is @gemini-code-assist bot is approved the PR in #122 (comment) this comment!

Looking forward to your review!

[laolaoqi]

Bid: Console Wallet Migration

I am bidding on this bounty (Tier L — 150,000 XTM).

Experience: Rust systems programming, database migrations, backward-compatible data migration paths.

Approach:

1. Map console wallet DB schema to new wallet format
2. Implement import command preserving display transaction IDs
3. Handle edge cases: partial syncs, corrupted DBs, version mismatches
4. Comprehensive tests + migration docs

Estimated delivery: 2-3 weeks

Payment wallet: 0xdFc476D7Bb10230B26500eEE24e300B26d253561

Ready to start. Happy to discuss details.

[0xPepeSilvia]

@metalaureate @SWvheerden — quick context on the two open PRs.

Reviewing #122 surfaced a real correctness bug that was in my original #121: when a legacy wallet contains multi-output incoming transactions (recipient + change, or batched one-sided sends), multiple outputs rows share the same received_in_tx_id. The destination has a UNIQUE index on outputs.tx_id, so the second insert would have hit UNIQUE constraint failed and rolled back the whole migration. Credit to @sanrishi for catching that.

Just pushed 9bde274 on #121:

1. resolve_destination_tx_id — first occurrence of a legacy received_in_tx_id keeps it verbatim; subsequent occurrences fall back to a deterministic hash-derived id. Counted into MigrationReport.tx_id_collisions_resolved so it's visible to the user.
2. Balance verification — source_balance computed up-front, cross-checked against net_balance(), surfaced as balance_match: bool. CLI aborts on mismatch.
3. --dry-run flag — runs the full migration code path and rolls back without committing, so users can rehearse the migration.
4. Tests: 4 new unit tests for the collision logic (including 3-way collisions) + a dry-run integration test. 10/10 migration tests pass.

Happy to defer to whichever PR you prefer on technical merit. If it's #122, no objection — sanrishi's catch was the right call. If you'd rather take #121 forward, glad to address any review feedback either of you have.

[sanrishi]

Thanks for the shoutout @0xPepeSilvia, and great work getting the --dry-run and collision checks added to your branch!

Just to add a bit more context for @metalaureate and @SWvheerden as you evaluate the two approaches: while the SQLite unique constraint crash is definitely critical, the other major safety invariant I built PR #122 around is preventing network rebroadcast loops via monitor.rs.

If historical legacy transactions are mapped directly into the new completed_transactions table with mocked or empty serialization blobs, the background TransactionMonitor will actively attempt to deserialize and rebroadcast them to the network on startup. To guarantee node safety and prevent network spam, PR #122 explicitly isolates historical imports strictly to displayed_transactions (satisfying the UI requirement) and balance_changes.

Since PR #122 was architected natively around both the database constraints and the monitor safety invariants from the very first commit (and includes 7 integration tests proving strict 1:1 parity), it might provide a safer baseline to merge.

But I am completely happy to defer to the maintainers' preference here as well! It was a fun edge-case to track down.

[SWvheerden]

I pasted this in both prs.

We need to construct the timeline, using mostly the outputs, with help of the transactions.
Meaning we need to match all ouputs(unspent and spent to each transaction)
and then in order add debits and credit balance changes with their display transactions.

Then after this, we need to double check the statuses of the transactions via a basenode, so we mark the confirmations etc correct,.

[laolaoqi]

?? Bounty Bid: Migration from Console Wallet

I can build the console wallet migration path for the new wallet format.

What I Deliver

• CLI command (wallet-migrate --source ) accepting synced console wallet database
• Full transaction history preservation with identical display TX IDs
• Balance consistency verification - migrated wallet matches source wallet balance
• Rust implementation integrated with minotari-cli codebase
• Unit tests + integration tests covering migration scenarios
• Backward compatibility - existing wallet users unaffected

Why Me

• Strong Rust/Systems programming experience
• Experience with blockchain wallet data structures and database migration patterns
• Can work within existing minotari-cli architecture and Tari coding standards

Timeline

• 24-48 hours for implementation, tests, and PR

Wallet for Payment

�x6c21794E27C34E93cd0049918d04Da58FC72595c

Happy to discuss approach and acceptance criteria in more detail.

[0xPepeSilvia]

@sanrishi — fair point on the monitor rebroadcast risk, and worth raising. Looking again at #121: the migrator never inserts into completed_transactions (only displayed_transactions, balance_changes, outputs, inputs, accounts, scanned_tip_blocks), so the runtime concern doesn't materialise. But the converter file did still build an unused CompletedTxRecord from an earlier design, which made the intent ambiguous on a read-through. Cleaned that up in 0088293 with a comment explaining why we deliberately keep that table empty for historical imports — same reasoning you arrived at.

@SWvheerden — understood on the timeline reconstruction. To make sure I have the shape right:

1. Walk outputs (unspent and spent) as the primary source of truth.
2. Match each output to its containing source transaction by hash, and group outputs per tx.
3. Walk the resulting (tx, output-group) tuples in chronological order, emitting balance_changes (credits for outputs the wallet received, debits for outputs the wallet spent) interleaved with their displayed_transactions rows, instead of two separate loops.
4. After the in-memory reconstruction, call a base node to refresh per-transaction status — confirmations, mined-or-not, reorged-out — so the imported view reflects current chain state rather than the console wallet's frozen snapshot.

If that's the right read of what you're asking for, happy to take this on — basenode RPC integration is the substantial piece. Want me to keep iterating on #121, or would you prefer to pick whichever of #121 / #122 you'd rather take forward and have just that one work toward the spec? Don't mind either way.

[SWvheerden]

you can keep iterating in 121, I dont really mind.
But 121 does do old_completed_transactions -> display_transactions its not quite right.
We need to do old_outputs + old_compeleted_transactions -> ouputs + display_transactions
Its more the outputs thats important to use, but we can use the completed transactions so we dont have to go thourgh the complex task of trying to match them like scanning does