@dimcool/wallet 0.1.0-beta.1

package/README.md

@@ -0,0 +1,106 @@
+# @dimcool/wallet
+
+Non-custodial wallet toolkit for DIM agents.
+
+Canonical docs:
+
+- https://docs.dim.cool/capabilities/agent-wallet
+- https://docs.dim.cool/guides/wallet-package
+
+`@dimcool/wallet` helps you:
+
+- create/load wallets from mnemonic or private key
+- sign Solana messages and transactions
+- authenticate to DIM with `wallet.login(...)`
+- run high-level DIM wallet actions (`send`, `getBalances`, `getInfo`)
+
+## Install
+
+```bash
+npm install @dimcool/wallet
+```
+
+## Quick Start
+
+```ts
+import { Wallet } from '@dimcool/wallet';
+
+const wallet = new Wallet({
+  enabledNetworks: ['solana'],
+  fromPrivateKey: process.env.DIM_WALLET_PRIVATE_KEY!,
+  rpcUrls: {
+    solana: 'https://api.mainnet-beta.solana.com',
+  },
+});
+
+const session = await wallet.login({
+  referralCode: 'optional-referrer',
+  walletMeta: { type: 'keypair' },
+});
+
+console.log('Logged in as', session.user.id);
+console.log('Addresses', wallet.getAddresses());
+```
+
+## Create Wallet
+
+### From mnemonic
+
+```ts
+const wallet = new Wallet({
+  enabledNetworks: ['solana', 'evm'],
+  fromMnemonic: process.env.DIM_MNEMONIC!,
+  // Solana default path: m/44'/501'/0'/0'
+  // Optional alternatives:
+  // solanaDerivationPath: "m/44'/501'/1'/0'",
+  // solanaAccountIndex: 1,
+  rpcUrls: {
+    solana: 'https://api.mainnet-beta.solana.com',
+    evm: 'https://mainnet.infura.io/v3/<key>',
+  },
+});
+```
+
+### From private key
+
+```ts
+const wallet = new Wallet({
+  enabledNetworks: ['solana'],
+  fromPrivateKey: process.env.DIM_WALLET_PRIVATE_KEY!,
+});
+```
+
+## Core APIs
+
+```ts
+wallet.getAddresses(); // { solana?: string, evm?: string }
+wallet.solana?.signMessage('hello');
+wallet.solana?.signAndSendTransaction(tx);
+```
+
+### DIM Convenience Methods
+
+```ts
+await wallet.login({ referralCode: 'optional-referrer' });
+await wallet.setUsername('agentname');
+await wallet.getInfo();
+await wallet.getBalances();
+await wallet.send({ recipient: 'alice.sol', amount: 1.25, token: 'USDC' });
+```
+
+## SDK Interoperability (Optional)
+
+If you also use `@dimcool/sdk`, `wallet.getSigner()` returns an SDK-compatible signer:
+
+```ts
+const signer = wallet.getSigner();
+// signer: { address, signMessage, signTransaction }
+```
+
+## Notes
+
+- `recipient` in `wallet.send(...)` can be a DIM username, Solana address, or `.sol` domain.
+- `.sol` domains are resolved server-side during transfer preparation.
+- Works in Node.js and browser environments.
+- EVM signing/sending APIs are scaffolded and will be expanded in upcoming releases.
+- `wallet.swap(...)` is reserved for upcoming aggregator-backed swap routes.

package/dist/index.cjs

@@ -0,0 +1,430 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Wallet: () => Wallet,
+  createWallet: () => createWallet,
+  getWallet: () => getWallet
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/polyfills.ts
+if (typeof globalThis !== "undefined" && !globalThis.process) {
+  globalThis.process = {
+    env: {}
+  };
+}
+
+// src/index.ts
+var import_sdk = require("@dimcool/sdk");
+var import_web3 = require("@solana/web3.js");
+var import_bs58 = __toESM(require("bs58"), 1);
+var bip39 = __toESM(require("bip39"), 1);
+var import_ethers = require("ethers");
+var import_micro_ed25519_hdkey = require("micro-ed25519-hdkey");
+var nacl = __toESM(require("tweetnacl"), 1);
+var DEFAULT_SOLANA_RPC = "https://api.mainnet-beta.solana.com";
+var DEFAULT_API_URL = "https://api.dim.cool";
+var DEFAULT_APP_ID = "dim-agents";
+var DEFAULT_SOLANA_DERIVATION_PATH = "m/44'/501'/0'/0'";
+var EVM_DERIVATION_PATH = "m/44'/60'/0'/0/0";
+var USDC_MULTIPLIER = 1e6;
+var SOLANA_SECRET_KEY_LENGTH = 64;
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  if (typeof btoa === "undefined") {
+    throw new Error("Base64 conversion is not available in this environment.");
+  }
+  return btoa(binary);
+}
+function parseSolanaSecretKey(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("Private key is required.");
+  }
+  try {
+    const decoded = new Uint8Array(import_bs58.default.decode(trimmed));
+    if (decoded.length === 32 || decoded.length === SOLANA_SECRET_KEY_LENGTH) {
+      return decoded;
+    }
+  } catch {
+  }
+  try {
+    if (typeof Buffer !== "undefined") {
+      const decoded = new Uint8Array(Buffer.from(trimmed, "base64"));
+      if (decoded.length === 32 || decoded.length === SOLANA_SECRET_KEY_LENGTH) {
+        return decoded;
+      }
+    } else if (typeof atob !== "undefined") {
+      const binary = atob(trimmed.replace(/\s/g, ""));
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+      }
+      if (bytes.length === 32 || bytes.length === SOLANA_SECRET_KEY_LENGTH) {
+        return bytes;
+      }
+    }
+  } catch {
+  }
+  throw new Error(
+    "Invalid Solana private key format. Use base58 or base64 for 32/64-byte secrets."
+  );
+}
+function normalizeEvmPrivateKey(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("EVM private key is required.");
+  }
+  const prefixed = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+  if (!/^0x[0-9a-fA-F]{64}$/.test(prefixed)) {
+    throw new Error(
+      "Invalid EVM private key format. Expected 32-byte hex key."
+    );
+  }
+  return prefixed;
+}
+function isEvmHexKey(input) {
+  const prefixed = input.startsWith("0x") ? input : `0x${input}`;
+  return /^0x[0-9a-fA-F]{64}$/.test(prefixed);
+}
+function createDefaultStorage() {
+  if (typeof window !== "undefined") {
+    return new import_sdk.BrowserLocalStorage();
+  }
+  return new import_sdk.NodeStorage();
+}
+function toTransferMinorUnits(amount, token) {
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new Error("Amount must be a positive number.");
+  }
+  if (token === "SOL") {
+    return Math.round(amount * import_web3.LAMPORTS_PER_SOL);
+  }
+  return Math.round(amount * USDC_MULTIPLIER);
+}
+function getSolanaDerivationPath(options) {
+  if (options.solanaDerivationPath) return options.solanaDerivationPath;
+  if (options.solanaAccountIndex != null) {
+    if (!Number.isInteger(options.solanaAccountIndex) || options.solanaAccountIndex < 0) {
+      throw new Error("solanaAccountIndex must be a non-negative integer.");
+    }
+    return `m/44'/501'/${options.solanaAccountIndex}'/0'`;
+  }
+  return DEFAULT_SOLANA_DERIVATION_PATH;
+}
+var Wallet = class {
+  constructor(options) {
+    this.sdk = null;
+    this.solanaKeypair = null;
+    this.evmWallet = null;
+    this.currentUser = null;
+    if (!options.enabledNetworks.length) {
+      throw new Error("enabledNetworks must include at least one network.");
+    }
+    this.enabledNetworks = new Set(options.enabledNetworks);
+    this.solanaDerivationPath = getSolanaDerivationPath(options);
+    this.rpcUrls = {
+      solana: options.rpcUrls?.solana || DEFAULT_SOLANA_RPC,
+      evm: options.rpcUrls?.evm
+    };
+    this.sdkConfig = {
+      appId: options.sdk?.appId || DEFAULT_APP_ID,
+      baseUrl: options.sdk?.baseUrl || DEFAULT_API_URL,
+      storage: options.sdk?.storage || createDefaultStorage()
+    };
+    this.solana = this.enabledNetworks.has("solana") ? {
+      signMessage: async (message) => {
+        const kp = this.requireSolanaKeypair();
+        return nacl.sign.detached(
+          new TextEncoder().encode(message),
+          kp.secretKey
+        );
+      },
+      signAndSendTransaction: async (transaction) => {
+        const connection = new import_web3.Connection(this.rpcUrls.solana, "confirmed");
+        const kp = this.requireSolanaKeypair();
+        transaction.partialSign(kp);
+        const signed = transaction.serialize({
+          requireAllSignatures: false
+        });
+        return connection.sendRawTransaction(signed);
+      }
+    } : void 0;
+    this.ethereum = this.enabledNetworks.has("evm") ? {
+      signMessage: async (_message) => {
+        throw new Error("EVM signing is not implemented yet.");
+      }
+    } : void 0;
+    if (options.fromMnemonic) {
+      this.initializeFromMnemonic(options.fromMnemonic);
+    } else if (options.fromPrivateKey) {
+      this.initializeFromPrivateKey(options.fromPrivateKey);
+    }
+  }
+  getSdk() {
+    if (this.sdk) return this.sdk;
+    this.sdk = new import_sdk.SDK({
+      appId: this.sdkConfig.appId,
+      baseUrl: this.sdkConfig.baseUrl,
+      storage: this.sdkConfig.storage
+    });
+    return this.sdk;
+  }
+  requireSolanaKeypair() {
+    if (!this.solanaKeypair) {
+      throw new Error("Solana keypair is not configured.");
+    }
+    return this.solanaKeypair;
+  }
+  initializeFromMnemonic(mnemonic) {
+    if (!bip39.validateMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase.");
+    }
+    if (this.enabledNetworks.has("solana")) {
+      const seed = bip39.mnemonicToSeedSync(mnemonic);
+      const hd = import_micro_ed25519_hdkey.HDKey.fromMasterSeed(seed.toString("hex"));
+      const node = hd.derive(this.solanaDerivationPath);
+      if (!node.privateKey) {
+        throw new Error("Failed to derive Solana private key from mnemonic.");
+      }
+      this.solanaKeypair = import_web3.Keypair.fromSeed(node.privateKey);
+    }
+    if (this.enabledNetworks.has("evm")) {
+      const account = import_ethers.HDNodeWallet.fromPhrase(
+        mnemonic,
+        void 0,
+        EVM_DERIVATION_PATH
+      );
+      this.evmWallet = new import_ethers.Wallet(account.privateKey);
+    }
+  }
+  initializeFromPrivateKey(input) {
+    if (typeof input === "string") {
+      if (this.enabledNetworks.size === 1 && this.enabledNetworks.has("solana")) {
+        this.setKeypair(input);
+        return;
+      }
+      if (this.enabledNetworks.size === 1 && this.enabledNetworks.has("evm")) {
+        this.setEvmPrivateKey(input);
+        return;
+      }
+      if (isEvmHexKey(input)) {
+        this.setEvmPrivateKey(input);
+        return;
+      }
+      this.setKeypair(input);
+      return;
+    }
+    if (this.enabledNetworks.has("solana") && input.solana) {
+      this.setKeypair(input.solana);
+    }
+    if (this.enabledNetworks.has("evm") && input.evm) {
+      this.setEvmPrivateKey(input.evm);
+    }
+  }
+  setKeypair(privateKey) {
+    if (!this.enabledNetworks.has("solana")) {
+      throw new Error("Solana network is not enabled.");
+    }
+    const keyBytes = typeof privateKey === "string" ? parseSolanaSecretKey(privateKey) : privateKey;
+    if (keyBytes.length !== 32 && keyBytes.length !== SOLANA_SECRET_KEY_LENGTH) {
+      throw new Error(
+        `Invalid key length: expected 32 or 64 bytes, got ${keyBytes.length}.`
+      );
+    }
+    this.solanaKeypair = import_web3.Keypair.fromSecretKey(keyBytes);
+  }
+  setEvmPrivateKey(privateKey) {
+    if (!this.enabledNetworks.has("evm")) {
+      throw new Error("EVM network is not enabled.");
+    }
+    this.evmWallet = new import_ethers.Wallet(normalizeEvmPrivateKey(privateKey));
+  }
+  generateSolanaKeypair() {
+    if (!this.enabledNetworks.has("solana")) {
+      throw new Error("Solana network is not enabled.");
+    }
+    this.solanaKeypair = import_web3.Keypair.generate();
+    return {
+      publicKey: this.solanaKeypair.publicKey.toBase58(),
+      secretKey: this.solanaKeypair.secretKey
+    };
+  }
+  // Intentionally no persistence in v1; wallet state is process memory only.
+  async loadFromStorage() {
+    return false;
+  }
+  clear() {
+    this.solanaKeypair = null;
+    this.evmWallet = null;
+    this.currentUser = null;
+  }
+  hasKeypair() {
+    return this.solanaKeypair !== null;
+  }
+  getPublicKey() {
+    return this.solanaKeypair?.publicKey.toBase58() ?? null;
+  }
+  getSolanaKeypair() {
+    return this.requireSolanaKeypair();
+  }
+  getSolanaPrivateKeyBase58() {
+    return import_bs58.default.encode(this.requireSolanaKeypair().secretKey);
+  }
+  getAddresses() {
+    return {
+      ...this.solanaKeypair ? { solana: this.solanaKeypair.publicKey.toBase58() } : {},
+      ...this.evmWallet ? { evm: this.evmWallet.address } : {}
+    };
+  }
+  getSigner() {
+    const keypair = this.requireSolanaKeypair();
+    return {
+      address: keypair.publicKey.toBase58(),
+      signMessage: async (message) => {
+        const signature = nacl.sign.detached(
+          new TextEncoder().encode(message),
+          keypair.secretKey
+        );
+        return toBase64(signature);
+      },
+      signTransaction: async (transaction) => {
+        transaction.partialSign(keypair);
+        return transaction;
+      }
+    };
+  }
+  async login(options) {
+    const sdk = this.getSdk();
+    sdk.wallet.setSigner(this.getSigner());
+    const response = await sdk.auth.loginWithWallet({
+      referralCode: options?.referralCode,
+      walletMeta: options?.walletMeta || { type: "keypair" }
+    });
+    this.currentUser = response.user;
+    if (options?.username && !response.user.username) {
+      const newUsername = await this.setUsername(options.username);
+      this.currentUser = { ...response.user, username: newUsername || null };
+      return { ...response, user: this.currentUser };
+    }
+    return response;
+  }
+  async setUsername(username) {
+    const sdk = this.getSdk();
+    const availability = await sdk.users.isUsernameAvailable(username);
+    if (!availability.valid) {
+      throw new Error("Username is invalid. Use 3-20 alphanumeric characters.");
+    }
+    if (!availability.available) {
+      throw new Error(`Username "${username}" is already taken.`);
+    }
+    const updated = await sdk.users.updateUsername(username);
+    this.currentUser = updated;
+    return updated.username;
+  }
+  async getInfo() {
+    const sdk = this.getSdk();
+    const isAuthenticated = sdk.auth.isAuthenticated();
+    if (!isAuthenticated) {
+      return {
+        isAuthenticated: false,
+        addresses: this.getAddresses()
+      };
+    }
+    if (!this.currentUser) {
+      const sessions = await sdk.auth.getLatestSessions(1);
+      const userId = sessions.sessions[0]?.userId;
+      if (userId) {
+        this.currentUser = await sdk.users.getUserById(userId);
+      }
+    }
+    return {
+      isAuthenticated: true,
+      addresses: this.getAddresses(),
+      userId: this.currentUser?.id,
+      username: this.currentUser?.username ?? null
+    };
+  }
+  async getBalances() {
+    const sdk = this.getSdk();
+    if (!sdk.auth.isAuthenticated()) {
+      throw new Error("Wallet must be logged in before calling getBalances().");
+    }
+    return sdk.wallet.getBalances();
+  }
+  async send(options) {
+    const sdk = this.getSdk();
+    const token = options.token || "USDC";
+    const amountMinor = toTransferMinorUnits(options.amount, token);
+    const result = await sdk.wallet.send(options.recipient, amountMinor, token);
+    return {
+      signature: result.signature,
+      status: result.status,
+      recipientAddress: result.recipientAddress,
+      amountMinor,
+      token,
+      feeMinor: result.fee
+    };
+  }
+  async swap(_options) {
+    throw new Error(
+      "wallet.swap is not implemented yet. Planned with aggregator-backed routes (e.g. Jupiter)."
+    );
+  }
+};
+var walletSingleton = null;
+function createWallet(options) {
+  return new Wallet(options);
+}
+function getWallet(options) {
+  if (!walletSingleton) {
+    if (!options) {
+      throw new Error(
+        "Wallet singleton is not initialized. Call getWallet(options) once first."
+      );
+    }
+    walletSingleton = new Wallet(options);
+  }
+  return walletSingleton;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Wallet,
+  createWallet,
+  getWallet
+});

package/dist/index.d.cts

@@ -0,0 +1,120 @@
+import { WalletSigner, WalletMeta, LoginResponse, BalanceResponse, TransferToken, SubmitTransferResponse, IStorage } from '@dimcool/sdk';
+import { Transaction, Keypair } from '@solana/web3.js';
+
+type EnabledNetwork = 'solana' | 'evm';
+interface WalletRpcUrls {
+    solana?: string;
+    evm?: string;
+}
+interface WalletSdkConfig {
+    appId?: string;
+    baseUrl?: string;
+    storage?: IStorage;
+}
+type WalletPrivateKeyInput = string | {
+    solana?: string;
+    evm?: string;
+};
+interface WalletOptions {
+    enabledNetworks: EnabledNetwork[];
+    fromMnemonic?: string;
+    fromPrivateKey?: WalletPrivateKeyInput;
+    solanaDerivationPath?: string;
+    solanaAccountIndex?: number;
+    rpcUrls?: WalletRpcUrls;
+    sdk?: WalletSdkConfig;
+}
+interface WalletAddresses {
+    solana?: string;
+    evm?: string;
+}
+interface WalletLoginOptions {
+    referralCode?: string;
+    username?: string;
+    walletMeta?: WalletMeta;
+}
+interface WalletInfo {
+    addresses: WalletAddresses;
+    isAuthenticated: boolean;
+    userId?: string;
+    username?: string | null;
+}
+interface WalletSendOptions {
+    recipient: string;
+    amount: number;
+    token?: TransferToken;
+}
+interface WalletSendResult {
+    signature: string;
+    status: SubmitTransferResponse['status'];
+    recipientAddress: string;
+    amountMinor: number;
+    token: TransferToken;
+    feeMinor: number;
+}
+interface WalletSwapOptions {
+    from: string;
+    to: string;
+    amount: string | number;
+}
+interface WalletSolanaApi {
+    signMessage(message: string): Promise<Uint8Array>;
+    signAndSendTransaction(transaction: Transaction): Promise<string>;
+}
+interface WalletEvmApi {
+    signMessage(message: string): Promise<string>;
+}
+interface WalletApi {
+    readonly solana?: WalletSolanaApi;
+    readonly ethereum?: WalletEvmApi;
+    getAddresses(): WalletAddresses;
+    getSigner(): WalletSigner;
+    login(options?: WalletLoginOptions): Promise<LoginResponse>;
+    setUsername(username: string): Promise<string | null | undefined>;
+    getInfo(): Promise<WalletInfo>;
+    getBalances(): Promise<BalanceResponse>;
+    send(options: WalletSendOptions): Promise<WalletSendResult>;
+    swap(options: WalletSwapOptions): Promise<never>;
+}
+
+declare class Wallet implements WalletApi {
+    private readonly enabledNetworks;
+    private readonly rpcUrls;
+    private readonly solanaDerivationPath;
+    private readonly sdkConfig;
+    private sdk;
+    private solanaKeypair;
+    private evmWallet;
+    private currentUser;
+    readonly solana?: WalletSolanaApi;
+    readonly ethereum?: WalletEvmApi;
+    constructor(options: WalletOptions);
+    private getSdk;
+    private requireSolanaKeypair;
+    private initializeFromMnemonic;
+    private initializeFromPrivateKey;
+    setKeypair(privateKey: string | Uint8Array): void;
+    setEvmPrivateKey(privateKey: string): void;
+    generateSolanaKeypair(): {
+        publicKey: string;
+        secretKey: Uint8Array;
+    };
+    loadFromStorage(): Promise<boolean>;
+    clear(): void;
+    hasKeypair(): boolean;
+    getPublicKey(): string | null;
+    getSolanaKeypair(): Keypair;
+    getSolanaPrivateKeyBase58(): string;
+    getAddresses(): WalletAddresses;
+    getSigner(): WalletSigner;
+    login(options?: WalletLoginOptions): Promise<LoginResponse>;
+    setUsername(username: string): Promise<string | null | undefined>;
+    getInfo(): Promise<WalletInfo>;
+    getBalances(): Promise<BalanceResponse>;
+    send(options: WalletSendOptions): Promise<WalletSendResult>;
+    swap(_options: WalletSwapOptions): Promise<never>;
+}
+declare function createWallet(options: WalletOptions): Wallet;
+declare function getWallet(options?: WalletOptions): Wallet;
+
+export { type EnabledNetwork, Wallet, type WalletAddresses, type WalletApi, type WalletEvmApi, type WalletInfo, type WalletLoginOptions, type WalletOptions, type WalletPrivateKeyInput, type WalletRpcUrls, type WalletSdkConfig, type WalletSendOptions, type WalletSendResult, type WalletSolanaApi, type WalletSwapOptions, createWallet, getWallet };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import { WalletSigner, WalletMeta, LoginResponse, BalanceResponse, TransferToken, SubmitTransferResponse, IStorage } from '@dimcool/sdk';
+import { Transaction, Keypair } from '@solana/web3.js';
+
+type EnabledNetwork = 'solana' | 'evm';
+interface WalletRpcUrls {
+    solana?: string;
+    evm?: string;
+}
+interface WalletSdkConfig {
+    appId?: string;
+    baseUrl?: string;
+    storage?: IStorage;
+}
+type WalletPrivateKeyInput = string | {
+    solana?: string;
+    evm?: string;
+};
+interface WalletOptions {
+    enabledNetworks: EnabledNetwork[];
+    fromMnemonic?: string;
+    fromPrivateKey?: WalletPrivateKeyInput;
+    solanaDerivationPath?: string;
+    solanaAccountIndex?: number;
+    rpcUrls?: WalletRpcUrls;
+    sdk?: WalletSdkConfig;
+}
+interface WalletAddresses {
+    solana?: string;
+    evm?: string;
+}
+interface WalletLoginOptions {
+    referralCode?: string;
+    username?: string;
+    walletMeta?: WalletMeta;
+}
+interface WalletInfo {
+    addresses: WalletAddresses;
+    isAuthenticated: boolean;
+    userId?: string;
+    username?: string | null;
+}
+interface WalletSendOptions {
+    recipient: string;
+    amount: number;
+    token?: TransferToken;
+}
+interface WalletSendResult {
+    signature: string;
+    status: SubmitTransferResponse['status'];
+    recipientAddress: string;
+    amountMinor: number;
+    token: TransferToken;
+    feeMinor: number;
+}
+interface WalletSwapOptions {
+    from: string;
+    to: string;
+    amount: string | number;
+}
+interface WalletSolanaApi {
+    signMessage(message: string): Promise<Uint8Array>;
+    signAndSendTransaction(transaction: Transaction): Promise<string>;
+}
+interface WalletEvmApi {
+    signMessage(message: string): Promise<string>;
+}
+interface WalletApi {
+    readonly solana?: WalletSolanaApi;
+    readonly ethereum?: WalletEvmApi;
+    getAddresses(): WalletAddresses;
+    getSigner(): WalletSigner;
+    login(options?: WalletLoginOptions): Promise<LoginResponse>;
+    setUsername(username: string): Promise<string | null | undefined>;
+    getInfo(): Promise<WalletInfo>;
+    getBalances(): Promise<BalanceResponse>;
+    send(options: WalletSendOptions): Promise<WalletSendResult>;
+    swap(options: WalletSwapOptions): Promise<never>;
+}
+
+declare class Wallet implements WalletApi {
+    private readonly enabledNetworks;
+    private readonly rpcUrls;
+    private readonly solanaDerivationPath;
+    private readonly sdkConfig;
+    private sdk;
+    private solanaKeypair;
+    private evmWallet;
+    private currentUser;
+    readonly solana?: WalletSolanaApi;
+    readonly ethereum?: WalletEvmApi;
+    constructor(options: WalletOptions);
+    private getSdk;
+    private requireSolanaKeypair;
+    private initializeFromMnemonic;
+    private initializeFromPrivateKey;
+    setKeypair(privateKey: string | Uint8Array): void;
+    setEvmPrivateKey(privateKey: string): void;
+    generateSolanaKeypair(): {
+        publicKey: string;
+        secretKey: Uint8Array;
+    };
+    loadFromStorage(): Promise<boolean>;
+    clear(): void;
+    hasKeypair(): boolean;
+    getPublicKey(): string | null;
+    getSolanaKeypair(): Keypair;
+    getSolanaPrivateKeyBase58(): string;
+    getAddresses(): WalletAddresses;
+    getSigner(): WalletSigner;
+    login(options?: WalletLoginOptions): Promise<LoginResponse>;
+    setUsername(username: string): Promise<string | null | undefined>;
+    getInfo(): Promise<WalletInfo>;
+    getBalances(): Promise<BalanceResponse>;
+    send(options: WalletSendOptions): Promise<WalletSendResult>;
+    swap(_options: WalletSwapOptions): Promise<never>;
+}
+declare function createWallet(options: WalletOptions): Wallet;
+declare function getWallet(options?: WalletOptions): Wallet;
+
+export { type EnabledNetwork, Wallet, type WalletAddresses, type WalletApi, type WalletEvmApi, type WalletInfo, type WalletLoginOptions, type WalletOptions, type WalletPrivateKeyInput, type WalletRpcUrls, type WalletSdkConfig, type WalletSendOptions, type WalletSendResult, type WalletSolanaApi, type WalletSwapOptions, createWallet, getWallet };

package/dist/index.js

@@ -0,0 +1,399 @@
+// src/polyfills.ts
+if (typeof globalThis !== "undefined" && !globalThis.process) {
+  globalThis.process = {
+    env: {}
+  };
+}
+
+// src/index.ts
+import {
+  BrowserLocalStorage,
+  NodeStorage,
+  SDK
+} from "@dimcool/sdk";
+import {
+  Connection,
+  Keypair,
+  LAMPORTS_PER_SOL
+} from "@solana/web3.js";
+import bs58 from "bs58";
+import * as bip39 from "bip39";
+import { HDNodeWallet, Wallet as EvmWallet } from "ethers";
+import { HDKey } from "micro-ed25519-hdkey";
+import * as nacl from "tweetnacl";
+var DEFAULT_SOLANA_RPC = "https://api.mainnet-beta.solana.com";
+var DEFAULT_API_URL = "https://api.dim.cool";
+var DEFAULT_APP_ID = "dim-agents";
+var DEFAULT_SOLANA_DERIVATION_PATH = "m/44'/501'/0'/0'";
+var EVM_DERIVATION_PATH = "m/44'/60'/0'/0/0";
+var USDC_MULTIPLIER = 1e6;
+var SOLANA_SECRET_KEY_LENGTH = 64;
+function toBase64(bytes) {
+  if (typeof Buffer !== "undefined") {
+    return Buffer.from(bytes).toString("base64");
+  }
+  let binary = "";
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  if (typeof btoa === "undefined") {
+    throw new Error("Base64 conversion is not available in this environment.");
+  }
+  return btoa(binary);
+}
+function parseSolanaSecretKey(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("Private key is required.");
+  }
+  try {
+    const decoded = new Uint8Array(bs58.decode(trimmed));
+    if (decoded.length === 32 || decoded.length === SOLANA_SECRET_KEY_LENGTH) {
+      return decoded;
+    }
+  } catch {
+  }
+  try {
+    if (typeof Buffer !== "undefined") {
+      const decoded = new Uint8Array(Buffer.from(trimmed, "base64"));
+      if (decoded.length === 32 || decoded.length === SOLANA_SECRET_KEY_LENGTH) {
+        return decoded;
+      }
+    } else if (typeof atob !== "undefined") {
+      const binary = atob(trimmed.replace(/\s/g, ""));
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+      }
+      if (bytes.length === 32 || bytes.length === SOLANA_SECRET_KEY_LENGTH) {
+        return bytes;
+      }
+    }
+  } catch {
+  }
+  throw new Error(
+    "Invalid Solana private key format. Use base58 or base64 for 32/64-byte secrets."
+  );
+}
+function normalizeEvmPrivateKey(input) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("EVM private key is required.");
+  }
+  const prefixed = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+  if (!/^0x[0-9a-fA-F]{64}$/.test(prefixed)) {
+    throw new Error(
+      "Invalid EVM private key format. Expected 32-byte hex key."
+    );
+  }
+  return prefixed;
+}
+function isEvmHexKey(input) {
+  const prefixed = input.startsWith("0x") ? input : `0x${input}`;
+  return /^0x[0-9a-fA-F]{64}$/.test(prefixed);
+}
+function createDefaultStorage() {
+  if (typeof window !== "undefined") {
+    return new BrowserLocalStorage();
+  }
+  return new NodeStorage();
+}
+function toTransferMinorUnits(amount, token) {
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new Error("Amount must be a positive number.");
+  }
+  if (token === "SOL") {
+    return Math.round(amount * LAMPORTS_PER_SOL);
+  }
+  return Math.round(amount * USDC_MULTIPLIER);
+}
+function getSolanaDerivationPath(options) {
+  if (options.solanaDerivationPath) return options.solanaDerivationPath;
+  if (options.solanaAccountIndex != null) {
+    if (!Number.isInteger(options.solanaAccountIndex) || options.solanaAccountIndex < 0) {
+      throw new Error("solanaAccountIndex must be a non-negative integer.");
+    }
+    return `m/44'/501'/${options.solanaAccountIndex}'/0'`;
+  }
+  return DEFAULT_SOLANA_DERIVATION_PATH;
+}
+var Wallet = class {
+  constructor(options) {
+    this.sdk = null;
+    this.solanaKeypair = null;
+    this.evmWallet = null;
+    this.currentUser = null;
+    if (!options.enabledNetworks.length) {
+      throw new Error("enabledNetworks must include at least one network.");
+    }
+    this.enabledNetworks = new Set(options.enabledNetworks);
+    this.solanaDerivationPath = getSolanaDerivationPath(options);
+    this.rpcUrls = {
+      solana: options.rpcUrls?.solana || DEFAULT_SOLANA_RPC,
+      evm: options.rpcUrls?.evm
+    };
+    this.sdkConfig = {
+      appId: options.sdk?.appId || DEFAULT_APP_ID,
+      baseUrl: options.sdk?.baseUrl || DEFAULT_API_URL,
+      storage: options.sdk?.storage || createDefaultStorage()
+    };
+    this.solana = this.enabledNetworks.has("solana") ? {
+      signMessage: async (message) => {
+        const kp = this.requireSolanaKeypair();
+        return nacl.sign.detached(
+          new TextEncoder().encode(message),
+          kp.secretKey
+        );
+      },
+      signAndSendTransaction: async (transaction) => {
+        const connection = new Connection(this.rpcUrls.solana, "confirmed");
+        const kp = this.requireSolanaKeypair();
+        transaction.partialSign(kp);
+        const signed = transaction.serialize({
+          requireAllSignatures: false
+        });
+        return connection.sendRawTransaction(signed);
+      }
+    } : void 0;
+    this.ethereum = this.enabledNetworks.has("evm") ? {
+      signMessage: async (_message) => {
+        throw new Error("EVM signing is not implemented yet.");
+      }
+    } : void 0;
+    if (options.fromMnemonic) {
+      this.initializeFromMnemonic(options.fromMnemonic);
+    } else if (options.fromPrivateKey) {
+      this.initializeFromPrivateKey(options.fromPrivateKey);
+    }
+  }
+  getSdk() {
+    if (this.sdk) return this.sdk;
+    this.sdk = new SDK({
+      appId: this.sdkConfig.appId,
+      baseUrl: this.sdkConfig.baseUrl,
+      storage: this.sdkConfig.storage
+    });
+    return this.sdk;
+  }
+  requireSolanaKeypair() {
+    if (!this.solanaKeypair) {
+      throw new Error("Solana keypair is not configured.");
+    }
+    return this.solanaKeypair;
+  }
+  initializeFromMnemonic(mnemonic) {
+    if (!bip39.validateMnemonic(mnemonic)) {
+      throw new Error("Invalid mnemonic phrase.");
+    }
+    if (this.enabledNetworks.has("solana")) {
+      const seed = bip39.mnemonicToSeedSync(mnemonic);
+      const hd = HDKey.fromMasterSeed(seed.toString("hex"));
+      const node = hd.derive(this.solanaDerivationPath);
+      if (!node.privateKey) {
+        throw new Error("Failed to derive Solana private key from mnemonic.");
+      }
+      this.solanaKeypair = Keypair.fromSeed(node.privateKey);
+    }
+    if (this.enabledNetworks.has("evm")) {
+      const account = HDNodeWallet.fromPhrase(
+        mnemonic,
+        void 0,
+        EVM_DERIVATION_PATH
+      );
+      this.evmWallet = new EvmWallet(account.privateKey);
+    }
+  }
+  initializeFromPrivateKey(input) {
+    if (typeof input === "string") {
+      if (this.enabledNetworks.size === 1 && this.enabledNetworks.has("solana")) {
+        this.setKeypair(input);
+        return;
+      }
+      if (this.enabledNetworks.size === 1 && this.enabledNetworks.has("evm")) {
+        this.setEvmPrivateKey(input);
+        return;
+      }
+      if (isEvmHexKey(input)) {
+        this.setEvmPrivateKey(input);
+        return;
+      }
+      this.setKeypair(input);
+      return;
+    }
+    if (this.enabledNetworks.has("solana") && input.solana) {
+      this.setKeypair(input.solana);
+    }
+    if (this.enabledNetworks.has("evm") && input.evm) {
+      this.setEvmPrivateKey(input.evm);
+    }
+  }
+  setKeypair(privateKey) {
+    if (!this.enabledNetworks.has("solana")) {
+      throw new Error("Solana network is not enabled.");
+    }
+    const keyBytes = typeof privateKey === "string" ? parseSolanaSecretKey(privateKey) : privateKey;
+    if (keyBytes.length !== 32 && keyBytes.length !== SOLANA_SECRET_KEY_LENGTH) {
+      throw new Error(
+        `Invalid key length: expected 32 or 64 bytes, got ${keyBytes.length}.`
+      );
+    }
+    this.solanaKeypair = Keypair.fromSecretKey(keyBytes);
+  }
+  setEvmPrivateKey(privateKey) {
+    if (!this.enabledNetworks.has("evm")) {
+      throw new Error("EVM network is not enabled.");
+    }
+    this.evmWallet = new EvmWallet(normalizeEvmPrivateKey(privateKey));
+  }
+  generateSolanaKeypair() {
+    if (!this.enabledNetworks.has("solana")) {
+      throw new Error("Solana network is not enabled.");
+    }
+    this.solanaKeypair = Keypair.generate();
+    return {
+      publicKey: this.solanaKeypair.publicKey.toBase58(),
+      secretKey: this.solanaKeypair.secretKey
+    };
+  }
+  // Intentionally no persistence in v1; wallet state is process memory only.
+  async loadFromStorage() {
+    return false;
+  }
+  clear() {
+    this.solanaKeypair = null;
+    this.evmWallet = null;
+    this.currentUser = null;
+  }
+  hasKeypair() {
+    return this.solanaKeypair !== null;
+  }
+  getPublicKey() {
+    return this.solanaKeypair?.publicKey.toBase58() ?? null;
+  }
+  getSolanaKeypair() {
+    return this.requireSolanaKeypair();
+  }
+  getSolanaPrivateKeyBase58() {
+    return bs58.encode(this.requireSolanaKeypair().secretKey);
+  }
+  getAddresses() {
+    return {
+      ...this.solanaKeypair ? { solana: this.solanaKeypair.publicKey.toBase58() } : {},
+      ...this.evmWallet ? { evm: this.evmWallet.address } : {}
+    };
+  }
+  getSigner() {
+    const keypair = this.requireSolanaKeypair();
+    return {
+      address: keypair.publicKey.toBase58(),
+      signMessage: async (message) => {
+        const signature = nacl.sign.detached(
+          new TextEncoder().encode(message),
+          keypair.secretKey
+        );
+        return toBase64(signature);
+      },
+      signTransaction: async (transaction) => {
+        transaction.partialSign(keypair);
+        return transaction;
+      }
+    };
+  }
+  async login(options) {
+    const sdk = this.getSdk();
+    sdk.wallet.setSigner(this.getSigner());
+    const response = await sdk.auth.loginWithWallet({
+      referralCode: options?.referralCode,
+      walletMeta: options?.walletMeta || { type: "keypair" }
+    });
+    this.currentUser = response.user;
+    if (options?.username && !response.user.username) {
+      const newUsername = await this.setUsername(options.username);
+      this.currentUser = { ...response.user, username: newUsername || null };
+      return { ...response, user: this.currentUser };
+    }
+    return response;
+  }
+  async setUsername(username) {
+    const sdk = this.getSdk();
+    const availability = await sdk.users.isUsernameAvailable(username);
+    if (!availability.valid) {
+      throw new Error("Username is invalid. Use 3-20 alphanumeric characters.");
+    }
+    if (!availability.available) {
+      throw new Error(`Username "${username}" is already taken.`);
+    }
+    const updated = await sdk.users.updateUsername(username);
+    this.currentUser = updated;
+    return updated.username;
+  }
+  async getInfo() {
+    const sdk = this.getSdk();
+    const isAuthenticated = sdk.auth.isAuthenticated();
+    if (!isAuthenticated) {
+      return {
+        isAuthenticated: false,
+        addresses: this.getAddresses()
+      };
+    }
+    if (!this.currentUser) {
+      const sessions = await sdk.auth.getLatestSessions(1);
+      const userId = sessions.sessions[0]?.userId;
+      if (userId) {
+        this.currentUser = await sdk.users.getUserById(userId);
+      }
+    }
+    return {
+      isAuthenticated: true,
+      addresses: this.getAddresses(),
+      userId: this.currentUser?.id,
+      username: this.currentUser?.username ?? null
+    };
+  }
+  async getBalances() {
+    const sdk = this.getSdk();
+    if (!sdk.auth.isAuthenticated()) {
+      throw new Error("Wallet must be logged in before calling getBalances().");
+    }
+    return sdk.wallet.getBalances();
+  }
+  async send(options) {
+    const sdk = this.getSdk();
+    const token = options.token || "USDC";
+    const amountMinor = toTransferMinorUnits(options.amount, token);
+    const result = await sdk.wallet.send(options.recipient, amountMinor, token);
+    return {
+      signature: result.signature,
+      status: result.status,
+      recipientAddress: result.recipientAddress,
+      amountMinor,
+      token,
+      feeMinor: result.fee
+    };
+  }
+  async swap(_options) {
+    throw new Error(
+      "wallet.swap is not implemented yet. Planned with aggregator-backed routes (e.g. Jupiter)."
+    );
+  }
+};
+var walletSingleton = null;
+function createWallet(options) {
+  return new Wallet(options);
+}
+function getWallet(options) {
+  if (!walletSingleton) {
+    if (!options) {
+      throw new Error(
+        "Wallet singleton is not initialized. Call getWallet(options) once first."
+      );
+    }
+    walletSingleton = new Wallet(options);
+  }
+  return walletSingleton;
+}
+export {
+  Wallet,
+  createWallet,
+  getWallet
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dimcool/wallet",
+  "version": "0.1.0-beta.1",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:tsc": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@dimcool/sdk": "0.1.0",
+    "@solana/web3.js": "^1.95.4",
+    "bip39": "^3.1.0",
+    "bs58": "^6.0.0",
+    "ethers": "^6.15.0",
+    "micro-ed25519-hdkey": "^0.1.2",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^5.0.0"
+  }
+}