feat(sdk-core): add deriveAddress primitive to BaseCoin

modules/sdk-core/src/bitgo/baseCoin/baseCoin.ts

@@ -47,6 +47,8 @@ import {
   AuditKeyParams,
   AuditDecryptedKeyParams,
   TssVerifyAddressOptions,
+  DeriveAddressOptions,
+  DeriveAddressResult,
 } from './iBaseCoin';
 import { IInscriptionBuilder } from '../inscriptionBuilder';
 import {
@@ -352,6 +354,22 @@ export abstract class BaseCoin implements IBaseCoin {
    */
   abstract isWalletAddress(params: VerifyAddressOptions | TssVerifyAddressOptions): Promise<boolean>;
 
+  /**
+   * Locally derive and return a wallet receive address for the given derivation path,
+   * using public key material only (no private keys, no network access).
+   *
+   * This is the inverse of {@link isWalletAddress}: rather than checking a candidate
+   * address, it *produces* the address from the wallet's keychains and a chain/index.
+   *
+   * Coins opt in by overriding this method; the default implementation throws.
+   *
+   * @param {DeriveAddressOptions} params - parameters for address derivation (keychains, chain, index, …)
+   * @returns {Promise<DeriveAddressResult>} the derived address plus the path and coin-specific data
+   */
+  deriveAddress(params: DeriveAddressOptions): Promise<DeriveAddressResult> {
+    throw new NotImplementedError('deriveAddress is not supported for this coin');
+  }
+
   /**
    * convert address into desired address format.
    * @param address

modules/sdk-core/src/bitgo/baseCoin/iBaseCoin.ts

@@ -210,6 +210,56 @@ export function isTssVerifyAddressOptions<T extends VerifyAddressOptions | TssVe
   );
 }
 
+/**
+ * Options for locally deriving a wallet receive address from a derivation path.
+ *
+ * Unlike {@link VerifyAddressOptions}, which checks a candidate address, these options are
+ * used to *produce* the address offline from public key material only:
+ * - the user/backup/bitgo xpub triple (`pub`) for BIP32 multisig coins, or
+ * - the `commonKeychain` for TSS/MPC coins.
+ *
+ * No private keys and no network access are required.
+ */
+export interface DeriveAddressOptions
+  extends Pick<VerifyAddressOptions, 'format' | 'derivedFromParentWithSeed' | 'multisigTypeVersion'> {
+  // `format`, `derivedFromParentWithSeed` and `multisigTypeVersion` are reused from
+  // VerifyAddressOptions so derive and verify stay in sync on shared fields.
+  /**
+   * Derivation index for the address.
+   * For BIP32 multisig coins this is combined with `chain`; for TSS/MPC coins the
+   * derivation path is `m/{index}` (or `{prefix}/{index}` for SMC wallets).
+   */
+  index: number;
+  /** Derivation chain code (UTXO script-type / external-vs-internal selector). */
+  chain?: number;
+  /**
+   * Public key material for derivation. Each keychain must carry at least one of:
+   * - BIP32 multisig (UTXO, legacy EVM): the user/backup/bitgo xpub triple via `pub`.
+   * - TSS/MPC (SOL, EVM MPC, etc.): the `commonKeychain` (identical across keychains).
+   *
+   * Modelled as a union so a keychain with neither field is a type error. A keychain may
+   * still carry both fields (TSS keychains commonly expose `pub` alongside `commonKeychain`).
+   */
+  keychains?: ({ pub: string } | { commonKeychain: string })[];
+  /** Wallet version, used to disambiguate derivation strategy for some coin families. */
+  walletVersion?: number;
+}
+
+/**
+ * Result of locally deriving a wallet receive address.
+ *
+ * Extends {@link AddressVerificationData} (`chain`, `index`, `coinSpecific`) and adds the
+ * resolved `address` and the HD `derivationPath` actually used.
+ */
+export interface DeriveAddressResult extends AddressVerificationData {
+  /** The derived address. */
+  address: string;
+  /** The derivation index used. */
+  index: number;
+  /** The HD derivation path actually used to derive the address. */
+  derivationPath?: string;
+}
+
 export interface TransactionParams {
   recipients?: ITransactionRecipient[];
   walletPassphrase?: string;
@@ -618,6 +668,7 @@ export interface IBaseCoin {
   verifyTransaction(params: VerifyTransactionOptions): Promise<boolean>;
   verifyAddress(params: VerifyAddressOptions): Promise<boolean>;
   isWalletAddress(params: VerifyAddressOptions | TssVerifyAddressOptions, wallet?: IWallet): Promise<boolean>;
+  deriveAddress(params: DeriveAddressOptions): Promise<DeriveAddressResult>;
   canonicalAddress(address: string, format: unknown): string;
   supportsBlockTarget(): boolean;
   supportsLightning(): boolean;