feat: mint safe wallets via hardened user-child derivation

[danielpeng1]

SDK Safe.createWallet now peeks the sequential index, hardened-derives the user child, registers it public-only, and mints.

• User child path is m/<n>' from GET …/derivation-index; backup and BitGo children stay server soft-derive
• Child registration sends pub, parent, and safeId only. no more encryptedPrv or derivedFromParentWithSeed
• keychains.add forwards parent; signing scans sequential m/<n>' until the registered pub matches
• TSS and ed25519 mint still throw

Tests

• Happy-path mint asserts public-only register + mint body keys: [userChildId]
• Rejects explicit TSS, TSS-default coins, wrong peeked slot, ed25519, empty/wrong passphrase
• Sign-time tests cover m/<n>' and reject '' / '1e2' as indexes

Ticket: WCN-1203

[linear-code]

WCN-1203

[danielpeng1]

@claude review

[github-actions]

Claude finished @danielpeng1's task —— View job

---

Code Review Progress

• Read repository guidelines (CLAUDE.md)
• Examine core implementation changes in safe.ts
• Review interface and type changes
• Analyze keychain and derivation logic changes
• Review test coverage and scenarios
• Check for security considerations
• Provide comprehensive review feedback

---

Code Review Feedback

This PR implements hardened user-child derivation for Safe wallet creation with excellent attention to security and correctness. Here's my detailed analysis:

🟢 Strengths

Security-First Design:

• Hardened derivation (m/<n>') provides cryptographic isolation between child keys, preventing exposure of sibling keys even if one is compromised
• Public-only registration eliminates storage of private key material on the server - the child keychain is registered with only pub, parent, and safeId
• Sequential index peeking prevents collision issues during concurrent wallet creation
• Self-verification via deriveAndSelfCheckSafeChildHardened() provides additional safety against derivation errors

Robust Error Handling:

• Comprehensive validation covers TSS rejection, ed25519 rejection, empty passphrases, and derivation mismatches
• Clear error messages with specific context (e.g., safe.ts:128 slot validation, safe.ts:144 password validation)
• Proper inheritance from standard error types for consistent error handling

Excellent Test Coverage:

• Tests verify the exact API contract: public-only registration without encryptedPrv or derivedFromParentWithSeed
• Edge cases are well covered: wrong slots, invalid passphrases, unsupported coin types
• Signing-time tests validate the scanning mechanism for m/<n>' derivation paths

🟡 Areas for Consideration

Performance & Scalability:

1. Sequential scanning concern (safeDerivation.ts:72-86): The signing-time scan of m/0'..m/4096' could become a bottleneck for wallets with high derivation indices. Consider:

   • Caching successful derivation matches
   • Store the derivation index on the child keychain for direct lookup
   • Implement early termination strategies for common cases

2. API efficiency: The current flow requires multiple sequential API calls (derivation-index peek → keychain registration → wallet mint). Consider batching these operations if the server supports it.

Documentation & Maintainability:

1. Missing derivation path storage: Unlike traditional custody paths that store derivationPath, safe children only store parent. This makes debugging derivation issues more difficult - consider adding the resolved path to audit logs.

2. Slot mapping logic (safe.ts:48-60): The mapping from coin type to safe slot could benefit from better documentation of the business logic behind these assignments.

🔍 Technical Details

Interface Changes (iKeychains.ts:149-150):

/** Safe user-root key id this child was derived from. @experimental */
parent?: string;

The @experimental tag and clear documentation are good practices for this new feature.

Keychain Registration (safe.ts:149-155):

const child = await keychains.add({
  pub: derived.pub,
  source: 'user',
  keyType: 'independent', 
  parent: userRootId,
  safeId: this.id(),
});

Correctly omits encryptedPrv and derivedFromParentWithSeed, enforcing the public-only contract.

Derivation Logic (safeDerivation.ts:62-69):
The double-derivation self-check is a good defensive programming practice, though it adds computational overhead. The deterministic nature of BIP32 makes this primarily a guard against implementation bugs.

🟢 Code Quality

• Type safety: Proper use of TypeScript with strict interfaces and comprehensive validation
• Error handling: Consistent error types with clear inheritance hierarchy
• Testing: Comprehensive test suite with both positive and negative cases
• Documentation: Good inline comments explaining the security rationale

🎯 Final Assessment

This is a well-implemented security feature that properly addresses the core requirement of hardened derivation for Safe wallets. The implementation correctly balances security (hardened derivation, no server-side private key storage) with functionality (sequential index management, comprehensive validation).

Recommendation: ✅ Approve - The implementation is secure, well-tested, and follows good practices. The performance considerations noted above are optimizations for future iterations rather than blocking issues.

---

• Branch: WCN-1203/safe-create-wallet

[kisslove-dewangan]

lgtm