@unicitylabs/sphere-sdk 0.5.7 → 0.6.0-dev.1

package/dist/core/index.d.cts

@@ -93,7 +93,7 @@ interface CreateGroupOptions {
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'SIGNING_ERROR';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -261,6 +261,34 @@ declare function deriveAddressInfo(masterKey: MasterKey, basePath: string, index
  * (L1 SDK compatibility)
  */
 declare function generateAddressInfo(privateKey: string, index: number, path: string, prefix?: string): AddressInfo;
+/** Prefix prepended to all signed messages (Bitcoin-like signed message format) */
+declare const SIGN_MESSAGE_PREFIX = "Sphere Signed Message:\n";
+/**
+ * Hash a message for signing using the Bitcoin-like double-SHA256 scheme:
+ *   SHA256(SHA256(varint(prefix.length) + prefix + varint(msg.length) + msg))
+ *
+ * @returns 64-char lowercase hex hash
+ */
+declare function hashSignMessage(message: string): string;
+/**
+ * Sign a message with a secp256k1 private key.
+ *
+ * Returns a 130-character hex string: v (2 chars) + r (64 chars) + s (64 chars).
+ * The recovery byte `v` is `31 + recoveryParam` (0-3).
+ *
+ * @param privateKeyHex - 64-char hex private key
+ * @param message       - plaintext message to sign
+ */
+declare function signMessage(privateKeyHex: string, message: string): string;
+/**
+ * Verify a signed message against a compressed secp256k1 public key.
+ *
+ * @param message       - The original plaintext message
+ * @param signature     - 130-char hex signature (v + r + s)
+ * @param expectedPubkey - 66-char compressed public key hex
+ * @returns `true` if the signature is valid and matches the expected public key
+ */
+declare function verifySignedMessage(message: string, signature: string, expectedPubkey: string): boolean;
 
 /**
  * TXF (Token eXchange Format) Type Definitions
@@ -1247,16 +1275,6 @@ interface TransportProvider extends BaseProvider {
      * @returns true if successful, false if nametag is taken by another pubkey
      */
     publishIdentityBinding?(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
-    /**
-     * @deprecated Use publishIdentityBinding instead
-     * Register a nametag for this identity
-     */
-    registerNametag?(nametag: string, chainPubkey: string, directAddress: string): Promise<boolean>;
-    /**
-     * @deprecated Use publishIdentityBinding instead
-     * Publish nametag binding
-     */
-    publishNametag?(nametag: string, address: string): Promise<void>;
     /**
      * Subscribe to broadcast messages (global/channel)
      */
@@ -3696,6 +3714,15 @@ declare class Sphere {
     get identity(): Identity | null;
     /** Is ready */
     get isReady(): boolean;
+    /**
+     * Sign a plaintext message with the wallet's secp256k1 private key.
+     *
+     * Returns a 130-character hex string: v (2) + r (64) + s (64).
+     * The private key never leaves the SDK boundary.
+     *
+     * @throws SphereError if the wallet is not initialized or identity is missing
+     */
+    signMessage(message: string): string;
     getStorage(): StorageProvider;
     /**
      * Get first token storage provider (for backward compatibility)
@@ -4687,4 +4714,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.d.ts

@@ -93,7 +93,7 @@ interface CreateGroupOptions {
  * }
  * ```
  */
-type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE';
+type SphereErrorCode = 'NOT_INITIALIZED' | 'ALREADY_INITIALIZED' | 'INVALID_CONFIG' | 'INVALID_IDENTITY' | 'INSUFFICIENT_BALANCE' | 'INVALID_RECIPIENT' | 'TRANSFER_FAILED' | 'STORAGE_ERROR' | 'TRANSPORT_ERROR' | 'AGGREGATOR_ERROR' | 'VALIDATION_ERROR' | 'NETWORK_ERROR' | 'TIMEOUT' | 'DECRYPTION_ERROR' | 'MODULE_NOT_AVAILABLE' | 'SIGNING_ERROR';
 declare class SphereError extends Error {
     readonly code: SphereErrorCode;
     readonly cause?: unknown;
@@ -261,6 +261,34 @@ declare function deriveAddressInfo(masterKey: MasterKey, basePath: string, index
  * (L1 SDK compatibility)
  */
 declare function generateAddressInfo(privateKey: string, index: number, path: string, prefix?: string): AddressInfo;
+/** Prefix prepended to all signed messages (Bitcoin-like signed message format) */
+declare const SIGN_MESSAGE_PREFIX = "Sphere Signed Message:\n";
+/**
+ * Hash a message for signing using the Bitcoin-like double-SHA256 scheme:
+ *   SHA256(SHA256(varint(prefix.length) + prefix + varint(msg.length) + msg))
+ *
+ * @returns 64-char lowercase hex hash
+ */
+declare function hashSignMessage(message: string): string;
+/**
+ * Sign a message with a secp256k1 private key.
+ *
+ * Returns a 130-character hex string: v (2 chars) + r (64 chars) + s (64 chars).
+ * The recovery byte `v` is `31 + recoveryParam` (0-3).
+ *
+ * @param privateKeyHex - 64-char hex private key
+ * @param message       - plaintext message to sign
+ */
+declare function signMessage(privateKeyHex: string, message: string): string;
+/**
+ * Verify a signed message against a compressed secp256k1 public key.
+ *
+ * @param message       - The original plaintext message
+ * @param signature     - 130-char hex signature (v + r + s)
+ * @param expectedPubkey - 66-char compressed public key hex
+ * @returns `true` if the signature is valid and matches the expected public key
+ */
+declare function verifySignedMessage(message: string, signature: string, expectedPubkey: string): boolean;
 
 /**
  * TXF (Token eXchange Format) Type Definitions
@@ -1247,16 +1275,6 @@ interface TransportProvider extends BaseProvider {
      * @returns true if successful, false if nametag is taken by another pubkey
      */
     publishIdentityBinding?(chainPubkey: string, l1Address: string, directAddress: string, nametag?: string): Promise<boolean>;
-    /**
-     * @deprecated Use publishIdentityBinding instead
-     * Register a nametag for this identity
-     */
-    registerNametag?(nametag: string, chainPubkey: string, directAddress: string): Promise<boolean>;
-    /**
-     * @deprecated Use publishIdentityBinding instead
-     * Publish nametag binding
-     */
-    publishNametag?(nametag: string, address: string): Promise<void>;
     /**
      * Subscribe to broadcast messages (global/channel)
      */
@@ -3696,6 +3714,15 @@ declare class Sphere {
     get identity(): Identity | null;
     /** Is ready */
     get isReady(): boolean;
+    /**
+     * Sign a plaintext message with the wallet's secp256k1 private key.
+     *
+     * Returns a 130-character hex string: v (2) + r (64) + s (64).
+     * The private key never leaves the SDK boundary.
+     *
+     * @throws SphereError if the wallet is not initialized or identity is missing
+     */
+    signMessage(message: string): string;
     getStorage(): StorageProvider;
     /**
      * Get first token storage provider (for backward compatibility)
@@ -4687,4 +4714,4 @@ interface CheckNetworkHealthOptions {
  */
 declare function checkNetworkHealth(network?: NetworkType, options?: CheckNetworkHealthOptions): Promise<NetworkHealthResult>;
 
-export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic };
+export { type AddressInfo, CHARSET, type CheckNetworkHealthOptions, CurrencyUtils, DEFAULT_DERIVATION_PATH, DEFAULT_TOKEN_DECIMALS, type DerivedKey, type DiscoverAddressProgress, type DiscoverAddressesOptions, type DiscoverAddressesResult, type DiscoveredAddress, type EncryptedData, type EncryptionOptions, type InitProgress, type InitProgressCallback, type InitProgressStep, type KeyPair, type L1Config, type LogHandler, type LogLevel, type LoggerConfig, type MasterKey, SIGN_MESSAGE_PREFIX, type ScanAddressProgress, type ScanAddressesOptions, type ScanAddressesResult, type ScannedAddressResult, Sphere, type SphereCreateOptions, SphereError, type SphereErrorCode, type SphereImportOptions, type SphereInitOptions, type SphereInitResult, type SphereLoadOptions, base58Decode, base58Encode, bytesToHex, checkNetworkHealth, computeHash160, convertBits, createAddress, createBech32, createKeyPair, createSphere, decodeBech32, decrypt, decryptJson, decryptMnemonic, decryptSimple, decryptWithSalt, deriveAddressInfo, deriveChildKey, deriveKeyAtPath, deserializeEncrypted, discoverAddressesImpl, doubleSha256, ec, encodeBech32, encrypt, encryptMnemonic, encryptSimple, entropyToMnemonic, extractFromText, findPattern, formatAmount, generateAddressInfo, generateMasterKey, generateMnemonic, generateRandomKey, getAddressHrp, getPublicKey, getSphere, hash160, hash160ToBytes, hashSignMessage, hexToBytes, identityFromMnemonic, identityFromMnemonicSync, importSphere, initSphere, isEncryptedData, isSphereError, isValidBech32, isValidNametag, isValidPrivateKey, loadSphere, logger, mnemonicToEntropy, mnemonicToSeed, mnemonicToSeedSync, privateKeyToAddressInfo, publicKeyToAddress, randomBytes, randomHex, randomUUID, ripemd160, scanAddressesImpl, serializeEncrypted, sha256, signMessage, sleep, sphereExists, toHumanReadable, toSmallestUnit, validateMnemonic, verifySignedMessage };

package/dist/core/index.js

@@ -955,6 +955,73 @@ function generateAddressInfo(privateKey, index, path, prefix = "alpha") {
     index
   };
 }
+var SIGN_MESSAGE_PREFIX = "Sphere Signed Message:\n";
+function varint(n) {
+  if (n < 253) return new Uint8Array([n]);
+  const buf = new Uint8Array(3);
+  buf[0] = 253;
+  buf[1] = n & 255;
+  buf[2] = n >> 8 & 255;
+  return buf;
+}
+function hashSignMessage(message) {
+  const prefix = new TextEncoder().encode(SIGN_MESSAGE_PREFIX);
+  const msg = new TextEncoder().encode(message);
+  const prefixLen = varint(prefix.length);
+  const msgLen = varint(msg.length);
+  const full = new Uint8Array(prefixLen.length + prefix.length + msgLen.length + msg.length);
+  let off = 0;
+  full.set(prefixLen, off);
+  off += prefixLen.length;
+  full.set(prefix, off);
+  off += prefix.length;
+  full.set(msgLen, off);
+  off += msgLen.length;
+  full.set(msg, off);
+  const hex = Array.from(full).map((b) => b.toString(16).padStart(2, "0")).join("");
+  const h1 = CryptoJS2.SHA256(CryptoJS2.enc.Hex.parse(hex)).toString();
+  return CryptoJS2.SHA256(CryptoJS2.enc.Hex.parse(h1)).toString();
+}
+function signMessage(privateKeyHex, message) {
+  const keyPair = ec.keyFromPrivate(privateKeyHex, "hex");
+  const hashHex = hashSignMessage(message);
+  const hashBytes = Buffer.from(hashHex, "hex");
+  const sig = keyPair.sign(hashBytes, { canonical: true });
+  const pub = keyPair.getPublic();
+  let recoveryParam = -1;
+  for (let i = 0; i < 4; i++) {
+    try {
+      if (ec.recoverPubKey(hashBytes, sig, i).eq(pub)) {
+        recoveryParam = i;
+        break;
+      }
+    } catch {
+    }
+  }
+  if (recoveryParam === -1) {
+    throw new SphereError("Could not find recovery parameter", "SIGNING_ERROR");
+  }
+  const v = (31 + recoveryParam).toString(16).padStart(2, "0");
+  const r = sig.r.toString("hex").padStart(64, "0");
+  const s = sig.s.toString("hex").padStart(64, "0");
+  return v + r + s;
+}
+function verifySignedMessage(message, signature, expectedPubkey) {
+  if (signature.length !== 130) return false;
+  const v = parseInt(signature.slice(0, 2), 16) - 31;
+  const r = signature.slice(2, 66);
+  const s = signature.slice(66, 130);
+  if (v < 0 || v > 3) return false;
+  const hashHex = hashSignMessage(message);
+  const hashBytes = Buffer.from(hashHex, "hex");
+  try {
+    const recovered = ec.recoverPubKey(hashBytes, { r, s }, v);
+    const recoveredHex = recovered.encode("hex", true);
+    return recoveredHex === expectedPubkey;
+  } catch {
+    return false;
+  }
+}
 
 // l1/crypto.ts
 import CryptoJS3 from "crypto-js";
@@ -14084,6 +14151,23 @@ var Sphere = class _Sphere {
     return this._initialized;
   }
   // ===========================================================================
+  // Public Methods - Signing
+  // ===========================================================================
+  /**
+   * Sign a plaintext message with the wallet's secp256k1 private key.
+   *
+   * Returns a 130-character hex string: v (2) + r (64) + s (64).
+   * The private key never leaves the SDK boundary.
+   *
+   * @throws SphereError if the wallet is not initialized or identity is missing
+   */
+  signMessage(message) {
+    if (!this._identity?.privateKey) {
+      throw new SphereError("Wallet not initialized \u2014 cannot sign", "NOT_INITIALIZED");
+    }
+    return signMessage(this._identity.privateKey, message);
+  }
+  // ===========================================================================
   // Public Methods - Providers Access
   // ===========================================================================
   getStorage() {
@@ -15469,6 +15553,17 @@ var Sphere = class _Sphere {
     if (this._identity?.nametag) {
       throw new SphereError(`Unicity ID already registered for address ${this._currentAddressIndex}: @${this._identity.nametag}`, "ALREADY_INITIALIZED");
     }
+    if (!this._payments.hasNametag()) {
+      logger.debug("Sphere", `Minting nametag token for @${cleanNametag}...`);
+      const result = await this.mintNametag(cleanNametag);
+      if (!result.success) {
+        throw new SphereError(
+          `Failed to mint nametag token: ${result.error}`,
+          "AGGREGATOR_ERROR"
+        );
+      }
+      logger.debug("Sphere", `Nametag token minted successfully`);
+    }
     if (this._transport.publishIdentityBinding) {
       const success = await this._transport.publishIdentityBinding(
         this._identity.chainPubkey,
@@ -15492,15 +15587,6 @@ var Sphere = class _Sphere {
       nametags.set(0, cleanNametag);
     }
     await this.persistAddressNametags();
-    if (!this._payments.hasNametag()) {
-      logger.debug("Sphere", `Minting nametag token for @${cleanNametag}...`);
-      const result = await this.mintNametag(cleanNametag);
-      if (!result.success) {
-        logger.warn("Sphere", `Failed to mint nametag token: ${result.error}`);
-      } else {
-        logger.debug("Sphere", `Nametag token minted successfully`);
-      }
-    }
     this.emitEvent("nametag:registered", {
       nametag: cleanNametag,
       addressIndex: this._currentAddressIndex
@@ -16447,6 +16533,7 @@ export {
   CurrencyUtils,
   DEFAULT_DERIVATION_PATH2 as DEFAULT_DERIVATION_PATH,
   DEFAULT_TOKEN_DECIMALS,
+  SIGN_MESSAGE_PREFIX,
   Sphere,
   SphereError,
   base58Decode,
@@ -16489,6 +16576,7 @@ export {
   getSphere,
   hash160,
   hash160ToBytes,
+  hashSignMessage,
   hexToBytes,
   identityFromMnemonic,
   identityFromMnemonicSync,
@@ -16513,11 +16601,13 @@ export {
   scanAddressesImpl,
   serializeEncrypted,
   sha256,
+  signMessage,
   sleep,
   sphereExists,
   toHumanReadable,
   toSmallestUnit,
-  validateMnemonic2 as validateMnemonic
+  validateMnemonic2 as validateMnemonic,
+  verifySignedMessage
 };
 /*! Bundled license information: