Import Starknet accounts created in Xverse #734

Summary

Seed import should find Starknet accounts created in Xverse. Most of the work is already done. Xverse derives keys on the same ladder as Bramble (m/44'/9004'/{i}'/0/0, straight from the BIP-39 seed), and its accounts use an Argent 0.4-shaped constructor that Bramble already encodes. What's missing is one class hash that Xverse switched to in mid-2025. Bramble doesn't know it, so recent Xverse accounts land at addresses the scan never derives.

What Xverse does (from source)

Source: secretkeylabs/xverse-core develop @ ec24922ea6e9. The files are starknet/utils.ts, starknet/constants.ts, account/starknet.ts and account/index.ts.

• Keys: HDKey.fromMasterSeed(bip39 seed) → m/44'/9004'/{derivationIndex}'/0/0 → @scure/starknet grindKey. The index always sits on the hardened account level. Legacy Xverse wallets ("index" derivation type) still pass their index there for Starknet, so they don't need a second axis. There's no ETH-seeded tree like Ready's (Seed import finds zero Ready (Argent X) software accounts — wrong master seed, wrong axis #505) and no passphrase.
• Address: calculateContractAddressFromHash(salt = pubkey, class, calldata, deployer = 0). That's the same deploy shape as Ready's standard account.
• Constructor: owner = Signer::Starknet(pubkey), guardian = None. That's our existing signer-owner-guardian-option shape (["0x0", pubkey, "0x1"]). Xverse only supports this one template (argent-x-v0_4_0-with-0-guardians).
• Class hash: two eras.
  • Before 2025-06-30, Xverse used 0x036078…45927f, the official Argent 0.4.0 class and our ARGENT_ACCOUNT_CLASS_HASH.
  • On 2025-06-30 (xverse-core Privacy: keep the viewing key off the RPC, honour lock and auto-lock, and fail closed on stale fee prices #499, "Change account class hash to Argent Xverse"), it switched to 0x663fc01a0dbe1bacc4cd2a4c856eb9784b255a20988aa33d4d52b6fc20bd024. That class isn't in Argent's public deployments/account.txt. Xverse's comment points at a Cairo Native recompile. The public Xverse release came after the switch, so most real accounts should be on this class.
• Lazy deploy: Xverse deploys the account on its first outgoing transaction. Many Xverse accounts are funded but undeployed, for example a user who only received strkBTC/WBTC.

The 0x663fc01a… class is declared on mainnet (starknet_getClass via mainnet.nodes.starknet.org). Its ABI is Argent's: IAccount, IArgentUserAccount (get_owner/get_guardian/get_version), sessions, outside execution, upgradeable, and constructor(owner: Signer, guardian: Option<Signer>). In other words, it's an Argent 0.4.x build with the 0.4.0 calldata layout.

Where Bramble stands today

• Pre-switch Xverse accounts should already import. recoveryScanShapes() (apps/extension/src/background/onboarding/onboarding-ops.ts) scans ARGENT_ACCOUNT_CLASS_HASH on the wallet's own starknet-bip44 ladder, which is Xverse's ladder and class. This is unverified.
• Post-switch accounts are missed. 0x663fc01a… isn't in ACCOUNT_CLASSES (packages/foundation/wallet-model/src/accounts/account-families.ts). Even if we added it as an Argent deployment class, the scan only walks other Argent classes on the argentx-bip44 ladder, never on starknet-bip44.

Proposed change

1. Add 0x663fc01a… to ACCOUNT_CLASSES as family: "argent", label: "argent 0.4.0 (xverse)", constructorShape: "signer-owner-guardian-option", roles: ["deployment", "implementation"]. Set authorizationShape only after the signing check below. Update the table's doc comment, since it now holds a vendor-specific Argent build.
2. Add one scan shape: Argent at 0x663fc01a… on the starknet-bip44 ladder. Don't scan every Argent class on that ladder. Only these two pairs are known to exist.
3. Decide how an undeployed, funded Xverse account gets deployed. Bramble can deploy Argent 0.4.0, but deploy code paths may assume ARGENT_ACCOUNT_CLASS_HASH (see isCreatableCandidate and transactions/deployment.ts). Either deploy at the Xverse class, or refuse with a clear notice like the Braavos counterfactual flow does.
4. Add an xverse fixture group to tools/vendor-dataset/manifest/ and a vendorDerivation for it, then extend docs/VENDOR_IMPORT_DATASET.md with these Phase 0 findings.

Checks before trusting this

• Ground truth from the real app. xverse-core was last pushed 2025-08-01, and the shipped Xverse app could have moved past it. Create a throwaway seed in Xverse (extension, and mobile separately), activate one account, leave one funded but undeployed, add a second account, and confirm Bramble finds all of them at the expected index.
• Signing. Confirm 0x663fc01a… accepts Argent 0.4's signer-array encoding (argent-signer-array) and that account-compatibility.ts treats it like 0.4.0. Test on a fake-chain E2E plus one live mainnet transfer.
• Version. Read get_version() on a deployed Xverse account to pin which Argent release this build is.
• Upgrades. An Xverse account that upgrades to an official Argent class must still be recognised. It keeps its address, and the new class is already in the table as an implementation.
• Bitcoin-only Xverse users have no Starknet account. That's expected and shouldn't surface as an error.

Out of scope

• Xverse Ledger accounts. I found no evidence that Xverse supports Starknet on Ledger.
• Xverse's paymaster (AVNU) fee flow. It doesn't affect discovery.

Size

Steps 1–2 are a few lines plus tests (tests/ scan-shape coverage and the class table). Step 3 and the live verification take most of the effort.