@empereur-rouge/pms-sdk 0.3.8 → 0.5.0

package/dist/index.d.cts

@@ -1,118 +1,3 @@
-/**
- * PmsWallet - Wallet pour le réseau PMS.
- *
- * Supporte:
- * - Génération de wallet avec mnémonique 24 mots (BIP39)
- * - Import depuis clé privée
- * - Signature de messages
- * - Export de la phrase mnémonique
- *
- * @example
- * ```typescript
- * // Générer un nouveau wallet
- * const wallet = PmsWallet.generate();
- * console.log(wallet.mnemonic); // 24 mots
- *
- * // Restaurer depuis mnemonic
- * const wallet2 = PmsWallet.fromMnemonic("word1 word2 ...");
- *
- * // Signer un message
- * const sig = await wallet.sign(messageBytes);
- * ```
- */
-/**
- * Wallet PMS avec gestion des clés cryptographiques.
- */
-declare class PmsWallet {
-    /** Clé privée secp256k1 (32 bytes) - pour signatures */
-    private readonly _privateKey;
-    /** Clé publique secp256k1 non compressée (65 bytes: 04 + x + y) */
-    private readonly _publicKey;
-    /** Clé privée X25519 (32 bytes) - pour chiffrement */
-    private readonly _x25519PrivateKey;
-    /** Clé publique X25519 (32 bytes) */
-    private readonly _x25519PublicKey;
-    /** Phrase mnémonique (24 mots) si générée/importée */
-    private readonly _mnemonic?;
-    /**
-     * Constructeur privé - utiliser les méthodes statiques.
-     */
-    private constructor();
-    /**
-     * Génère un nouveau wallet avec une phrase de 24 mots.
-     */
-    static generate(): PmsWallet;
-    /**
-     * Crée un wallet à partir d'une phrase mnémonique (12, 15, 18, 21 ou 24 mots).
-     * @throws Error si la phrase est invalide
-     */
-    static fromMnemonic(mnemonic: string): PmsWallet;
-    /**
-     * Crée un wallet à partir d'une clé privée hexadécimale.
-     */
-    static fromPrivateKey(privateKeyHex: string): PmsWallet;
-    /**
-     * Crée un wallet à partir d'une seed (32 bytes).
-     */
-    static fromSeed(seed: Uint8Array): PmsWallet;
-    /**
-     * Adresse du wallet (clé publique hex).
-     * Format: "04" + 64 bytes hex = 130 caractères
-     */
-    get address(): string;
-    /**
-     * Clé publique en bytes.
-     */
-    get publicKey(): Uint8Array;
-    /**
-     * Clé publique en hex.
-     */
-    get publicKeyHex(): string;
-    /**
-     * Phrase mnémonique (si disponible).
-     * @returns undefined si le wallet a été créé depuis une clé privée
-     */
-    get mnemonic(): string | undefined;
-    /**
-     * Clé publique X25519 en hex (pour chiffrement).
-     * Utiliser cette clé comme destinataire pour encryptPayload().
-     */
-    get x25519PublicKeyHex(): string;
-    /**
-     * Clé privée X25519 en hex (pour déchiffrement).
-     * ⚠️ Ne pas exposer cette clé publiquement !
-     */
-    get x25519PrivateKeyHex(): string;
-    /**
-     * Signe un message avec la clé privée.
-     * @param message - Message à signer (sera hashé avec SHA256)
-     * @returns Signature DER encodée en hex
-     */
-    sign(message: Uint8Array): string;
-    /**
-     * Signe un message déjà hashé.
-     * @param hash - Hash 32 bytes du message
-     * @returns Signature DER encodée en hex
-     */
-    signHash(hash: Uint8Array): string;
-    /**
-     * Exporte la clé privée en hex.
-     * ⚠️ À utiliser avec précaution !
-     */
-    exportPrivateKey(): string;
-    /**
-     * Vérifie une signature.
-     * @param message - Message original
-     * @param signature - Signature DER hex
-     * @param publicKeyHex - Clé publique hex du signataire
-     */
-    static verify(message: Uint8Array, signature: string, publicKeyHex: string): boolean;
-}
-/**
- * Vérifie si une phrase mnémonique est valide.
- */
-declare function isValidMnemonic(mnemonic: string): boolean;
-
 /**
  * Types TypeScript pour le SDK PMS.
  *
@@ -125,6 +10,27 @@ interface OutputRef {
     /** Index de l'output dans la transaction */
     index: number;
 }
+/**
+ * Condition de déverrouillage d'un output (protocole 2.2, dag-pms v0.10.0).
+ *
+ * Sérialisation serde externally-tagged :
+ * - variant unit → string JSON `"PubKey"` ;
+ * - variants à données → `{ "MultiSig": {...} }` / `{ "HashLock": {...} }`.
+ *
+ * La condition est figée À LA CRÉATION de l'output. Au spend, le validateur
+ * lit la condition depuis l'UTXO STOCKÉ (jamais depuis les données du
+ * dépensier).
+ */
+type SpendCondition = "PubKey" | {
+    MultiSig: {
+        m: number;
+        pubkeys: string[];
+    };
+} | {
+    HashLock: {
+        hash_hex: string;
+    };
+};
 /** Output de transaction (UTXO) */
 interface TxOutput {
     /** Adresse du destinataire */
@@ -133,6 +39,26 @@ interface TxOutput {
     amount: string;
     /** Asset ID (undefined/null = PMS natif, "edenite" = token custom) */
     asset_id?: string;
+    /**
+     * Time-lock natif (protocole 2.1) : timestamp UNIX **millisecondes**
+     * avant lequel l'output est indépensable. Absent = dépensable
+     * immédiatement. Entre dans le message signé quand présent.
+     */
+    locked_until?: number;
+    /**
+     * Condition de déverrouillage (protocole 2.2). Absent = PubKey simple
+     * (binding pubkey↔adresse classique). Pour MultiSig, `address` DOIT être
+     * l'adresse canonique de la policy — voir [`multisigAddress`].
+     */
+    spend_condition?: SpendCondition;
+    /**
+     * Timestamp de création de l'UTXO (UNIX ms), **assigné par le moteur**
+     * au persist — base du calcul de demurrage (protocole 2.5).
+     * NE JAMAIS poser ce champ côté client : toute valeur fournie est
+     * écrasée par le serveur, et le poser modifie inutilement le message
+     * signé. Présent en LECTURE seulement (GET /v1/wallet/{addr}/utxos).
+     */
+    created_at?: number;
 }
 /** UTXO complet avec sa référence */
 interface Utxo extends TxOutput {
@@ -144,12 +70,31 @@ interface TxInput {
     /** Référence à l'UTXO dépensé */
     out: OutputRef;
 }
+/** Signature additionnelle d'un cosignataire MultiSig (protocole 2.2). */
+interface Cosigner {
+    /** Clé publique hex (membre du set MultiSig) */
+    pubkey_hex: string;
+    /** Signature DER base64 du MÊME message canonique que l'unlock principal */
+    signature_b64: string;
+}
 /** Unlock (signature pour un input) */
 interface Unlock {
     /** Clé publique hex */
     pubkey_hex: string;
     /** Signature base64 */
     signature_b64: string;
+    /**
+     * Cosignatures pour un input sous condition MultiSig : la paire
+     * principale compte comme première signature, les cosigners complètent
+     * jusqu'à M. Chaque signature porte sur le même message canonique.
+     * Les unlocks n'entrent PAS dans le message signé.
+     */
+    cosigners?: Cosigner[];
+    /**
+     * Préimage hex pour un input sous condition HashLock :
+     * `sha256(bytes(preimage_hex)) == hash_hex` de la condition.
+     */
+    preimage_hex?: string;
 }
 /** Transaction UTXO */
 interface TxUtxo {
@@ -168,8 +113,14 @@ type PayloadEnvelope = {
 } | {
     Encrypted: EncryptedPayload;
 };
-/** Payload en clair */
-type PlainPayload = {
+/**
+ * Payload en clair.
+ *
+ * Sérialisation serde externally-tagged : variant unit → string JSON
+ * (`"Genesis"`), variant avec données → objet à clé unique
+ * (`{"TxUtxo": {...}}`).
+ */
+type PlainPayload = "Genesis" | {
     Mint: MintPayload;
 } | {
     TxUtxo: TxUtxo;
@@ -312,6 +263,12 @@ interface TokenMetadata {
     creator: string;
     /** Clé publique autorisée à mint ce token */
     mint_authority: string;
+    /**
+     * Demurrage opt-in (protocole 2.5) : décote en basis points par JOUR
+     * PLEIN écoulé depuis `created_at` de chaque UTXO. Absent/0 = pas de
+     * demurrage. Voir [`effectiveValue`] pour le calcul côté client.
+     */
+    demurrage_bps_per_day?: number;
 }
 /** Mise à jour de configuration */
 type ConfigUpdate = {
@@ -335,6 +292,23 @@ type ConfigUpdate = {
         enabled: boolean;
     };
 };
+/**
+ * Dernier snapshot de preuve de réserves ancré (protocole 2.6).
+ * `GET /v1/reserves/latest` — le bloc DAG `block_id` est la preuve signée
+ * Coordinator ; `state_root` = SHA-256 de l'état UTXO complet.
+ */
+interface ReservesLatest {
+    /** ID du bloc ReserveSnapshot ancré dans le DAG */
+    block_id: string;
+    /** Racine d'état SHA-256 (64 hex chars) du set UTXO */
+    state_root: string;
+    /** Supply totale par asset : [asset_id | null (natif), montant] */
+    total_supply: Array<[string | null, string]>;
+    /** Nombre d'UTXOs couverts par le root */
+    utxo_count: number;
+    /** Horodatage du calcul (UNIX ms) */
+    computed_at_ms: number;
+}
 /** Bloc du DAG */
 interface Block {
     /** ID unique du bloc (hash) */
@@ -440,13 +414,24 @@ interface UtxoDetail {
 interface PrepareTxResponse {
     /** Transaction non-signée (unlocks vide) */
     unsigned_tx: TxUtxo;
-    /** Hash SHA256 du message à signer (hex) */
+    /** Hash SHA256 du message canonique à signer (hex) */
     tx_hash: string;
-    /** Frais calculés */
+    /** Frais de gas PMS calculés */
     fee: string;
+    /** Frais de transfert smart contract ("0" si aucun contrat actif) */
+    transfer_fee: string;
     /** Détail des UTXOs sélectionnés */
     inputs_detail: UtxoDetail[];
 }
+/** Réponse de POST /v1/wallet/tx/send */
+interface SendTxResponse {
+    /** ID du bloc forgé et signé par le serveur (single-writer) */
+    id: string;
+    /** Statut: "inserted" (201) ou "duplicate" (409) */
+    status: string;
+    /** Alias de `id` pour compatibilité avec l'ancien SubmitResponse */
+    block_id: string;
+}
 /** Réponse de getNft - informations complètes d'un NFT */
 interface NftResponse {
     /** Token ID du NFT */
@@ -522,7 +507,7 @@ interface PmsClientConfig {
     seedNodes?: string[];
     /** ID du réseau (défaut: "pms-mainnet") */
     networkId?: string;
-    /** Version du protocole (défaut: 1) */
+    /** Version du protocole P2P (défaut: 3 — dag-pms v0.10.0) */
     protocolVersion?: number;
     /** Timeout en ms (défaut: 30000) */
     timeout?: number;
@@ -655,6 +640,148 @@ interface NodePublicConfig extends RuntimeConfig {
     fee_recipient: string;
 }
 
+/**
+ * PmsWallet - Wallet pour le réseau PMS.
+ *
+ * Supporte:
+ * - Génération de wallet avec mnémonique 24 mots (BIP39)
+ * - Import depuis clé privée
+ * - Signature de messages
+ * - Export de la phrase mnémonique
+ *
+ * @example
+ * ```typescript
+ * // Générer un nouveau wallet
+ * const wallet = PmsWallet.generate();
+ * console.log(wallet.mnemonic); // 24 mots
+ *
+ * // Restaurer depuis mnemonic
+ * const wallet2 = PmsWallet.fromMnemonic("word1 word2 ...");
+ *
+ * // Signer un message
+ * const sig = await wallet.sign(messageBytes);
+ * ```
+ */
+
+/**
+ * Wallet PMS avec gestion des clés cryptographiques.
+ */
+declare class PmsWallet {
+    /** Clé privée secp256k1 (32 bytes) - pour signatures */
+    private readonly _privateKey;
+    /** Clé publique secp256k1 non compressée (65 bytes: 04 + x + y) */
+    private readonly _publicKey;
+    /** Clé privée X25519 (32 bytes) - pour chiffrement */
+    private readonly _x25519PrivateKey;
+    /** Clé publique X25519 (32 bytes) */
+    private readonly _x25519PublicKey;
+    /** Phrase mnémonique (24 mots) si générée/importée */
+    private readonly _mnemonic?;
+    /**
+     * Constructeur privé - utiliser les méthodes statiques.
+     */
+    private constructor();
+    /**
+     * Génère un nouveau wallet avec une phrase de 24 mots.
+     */
+    static generate(): PmsWallet;
+    /**
+     * Crée un wallet à partir d'une phrase mnémonique (12, 15, 18, 21 ou 24 mots).
+     * @throws Error si la phrase est invalide
+     */
+    static fromMnemonic(mnemonic: string): PmsWallet;
+    /**
+     * Crée un wallet à partir d'une clé privée hexadécimale.
+     */
+    static fromPrivateKey(privateKeyHex: string): PmsWallet;
+    /**
+     * Crée un wallet à partir d'une seed (32 bytes).
+     */
+    static fromSeed(seed: Uint8Array): PmsWallet;
+    /**
+     * Adresse du wallet (clé publique hex).
+     * Format: "04" + 64 bytes hex = 130 caractères
+     */
+    get address(): string;
+    /**
+     * Clé publique en bytes.
+     */
+    get publicKey(): Uint8Array;
+    /**
+     * Clé publique en hex.
+     */
+    get publicKeyHex(): string;
+    /**
+     * Phrase mnémonique (si disponible).
+     * @returns undefined si le wallet a été créé depuis une clé privée
+     */
+    get mnemonic(): string | undefined;
+    /**
+     * Clé publique X25519 en hex (pour chiffrement).
+     * Utiliser cette clé comme destinataire pour encryptPayload().
+     */
+    get x25519PublicKeyHex(): string;
+    /**
+     * Clé privée X25519 en hex (pour déchiffrement).
+     * ⚠️ Ne pas exposer cette clé publiquement !
+     */
+    get x25519PrivateKeyHex(): string;
+    /**
+     * Signe un message avec la clé privée.
+     * @param message - Message à signer (sera hashé avec SHA256)
+     * @returns Signature DER encodée en hex
+     */
+    sign(message: Uint8Array): string;
+    /**
+     * Signe un message déjà hashé.
+     * @param hash - Hash 32 bytes du message
+     * @returns Signature DER encodée en hex
+     */
+    signHash(hash: Uint8Array): string;
+    /**
+     * Exporte la clé privée en hex.
+     * ⚠️ À utiliser avec précaution !
+     */
+    exportPrivateKey(): string;
+    /**
+     * Vérifie une signature.
+     * @param message - Message original
+     * @param signature - Signature DER hex
+     * @param publicKeyHex - Clé publique hex du signataire
+     */
+    static verify(message: Uint8Array, signature: string, publicKeyHex: string): boolean;
+}
+/**
+ * Vérifie si une phrase mnémonique est valide.
+ */
+declare function isValidMnemonic(mnemonic: string): boolean;
+/**
+ * Construit l'`Unlock` d'un input pour les conditions de dépense du
+ * protocole v0.10.0 (MultiSig / HashLock).
+ *
+ * - 1 signataire, pas d'options → unlock classique (PubKey / binding C-1).
+ * - Plusieurs signataires (MultiSig M-of-N) : le premier devient la paire
+ *   principale, les suivants des `cosigners` — chacun signe le MÊME message
+ *   canonique (`txSigningMessage`). Le quorum compte les clés DISTINCTES
+ *   membres du set de la condition.
+ * - `preimageHex` (HashLock) : révèle le secret tel que
+ *   `sha256(bytes(preimage)) == hash_hex` de la condition.
+ *
+ * @param signers - Wallets signataires (>= 1 ; ordre indifférent pour le quorum)
+ * @param txHashHex - Hash hex retourné par `txSigningMessage(...)`
+ * @param opts - `preimageHex` pour un input HashLock
+ *
+ * @example
+ * ```typescript
+ * const txHash = txSigningMessage(networkId, tx.inputs, tx.outputs, tx.fee);
+ * // dépense d'un UTXO MultiSig 2-of-3 :
+ * tx.unlocks = tx.inputs.map(() => makeUnlock([alice, carol], txHash));
+ * ```
+ */
+declare function makeUnlock(signers: PmsWallet[], txHashHex: string, opts?: {
+    preimageHex?: string;
+}): Unlock;
+
 /**
  * PmsClient - Client HTTP pour interagir avec un nœud PMS.
  *
@@ -741,8 +868,19 @@ declare class PmsClient {
     getToken(assetId: string): Promise<TokenMetadata>;
     /**
      * Récupère les UTXOs d'une adresse.
+     *
+     * Depuis dag-pms v0.10.0, chaque UTXO expose aussi ses contraintes de
+     * dépense : `locked_until` (time-lock), `spend_condition`
+     * (MultiSig/HashLock) et `created_at` (base du demurrage). Utiliser
+     * [`spendableUtxos`] pour exclure les UTXOs encore verrouillés avant
+     * toute sélection de coins côté client.
      */
     getUtxos(address: string): Promise<Utxo[]>;
+    /**
+     * Dernier snapshot de preuve de réserves ancré (protocole 2.6,
+     * `GET /v1/reserves/latest`). 404 si aucun snapshot n'a encore été ancré.
+     */
+    getLatestReserves(): Promise<ReservesLatest>;
     /**
      * Crée un nouveau wallet côté serveur (custodial).
      * Le serveur génère le wallet et retourne toutes les clés + adresse Bech32.
@@ -957,18 +1095,45 @@ declare class PmsClient {
     private refreshNodeList;
     /**
      * Envoie des tokens à une adresse.
-     * Construit automatiquement la transaction, la signe et la soumet.
+     *
+     * Flux aligné sur dag-pms v0.9.0 (single-writer + vérification des
+     * signatures de transaction par l'engine) :
+     * 1. `POST /v1/tx/prepare` — le serveur sélectionne les UTXOs et calcule
+     *    les frais.
+     * 2. Vérification défensive côté client : l'output destinataire demandé
+     *    existe bien, et le `tx_hash` retourné correspond au message canonique
+     *    recalculé localement (`txSigningMessage`). On ne signe JAMAIS un hash
+     *    opaque non vérifié.
+     * 3. Le wallet signe la TRANSACTION (unlocks) — pas le bloc. C'est le
+     *    serveur qui forge et signe le bloc (single-writer enforcement).
+     * 4. `POST /v1/wallet/tx/send` avec la TX signée + les clés X25519 des
+     *    destinataires pour le chiffrement du payload.
+     *
+     * @param params.to - Adresse destinataire (Bech32m de préférence)
+     * @param params.amount - Montant décimal (ex: "10.0")
+     * @param params.wallet - Wallet signataire (propriétaire des UTXOs)
+     * @param params.assetId - Asset ID optionnel (undefined = PMS natif)
+     * @returns `{id, status, block_id}` — id du bloc forgé par le serveur
      */
     send(params: {
         to: string;
         amount: string;
         wallet: PmsWallet;
+        assetId?: string;
         memo?: string;
-    }): Promise<SubmitResponse>;
+    }): Promise<SendTxResponse>;
     /**
      * Transférer un NFT à un autre propriétaire.
      * Prend en charge le re-chiffrement des métadonnées via le coordinateur.
      *
+     * @deprecated Cette méthode soumet un WireBlock signé par la clé
+     * utilisateur via `/submit/block`. Depuis dag-pms v0.9.0, l'engine tourne
+     * en mode **single-writer** : tout bloc signé par une clé non-coordinateur
+     * est rejeté. Cette méthode ne fonctionne que sur un réseau SANS
+     * single-writer enforcement. Utilisez les flux server-side
+     * (`/v1/nft/transfer/prepare` + endpoints serveur) qui forgent et signent
+     * le bloc côté coordinateur.
+     *
      * @param params - Paramètres du transfert
      * @param params.tokenId - Identifiant du NFT
      * @param params.to - Adresse du nouveau propriétaire
@@ -991,6 +1156,13 @@ declare class PmsClient {
      * un remboursement est calculé selon la formule:
      * `(weight * size * density) / 10000` PMS
      *
+     * @deprecated Cette méthode poste un WireBlock signé par la clé
+     * utilisateur. Depuis dag-pms v0.9.0, l'engine tourne en mode
+     * **single-writer** : tout bloc signé par une clé non-coordinateur est
+     * rejeté. Cette méthode ne fonctionne que sur un réseau SANS single-writer
+     * enforcement. Le flux supporté est le burn server-side
+     * (`/v1/nft/burn-simple`), où le serveur forge et signe le bloc.
+     *
      * @param params - Paramètres du burn
      * @param params.tokenId - Identifiant du NFT à brûler
      * @param params.wallet - Wallet PMS du propriétaire (doit être l'owner actuel)
@@ -1015,6 +1187,13 @@ declare class PmsClient {
     /**
      * Brûle (détruit) plusieurs NFTs en une seule transaction.
      *
+     * @deprecated Cette méthode poste un WireBlock signé par la clé
+     * utilisateur. Depuis dag-pms v0.9.0, l'engine tourne en mode
+     * **single-writer** : tout bloc signé par une clé non-coordinateur est
+     * rejeté. Cette méthode ne fonctionne que sur un réseau SANS single-writer
+     * enforcement. Le flux supporté est le burn server-side
+     * (`/v1/nft/burn-simple`), où le serveur forge et signe le bloc.
+     *
      * @param params - Paramètres du batch burn
      * @param params.tokenIds - Liste des Identifiants des NFTs à brûler
      * @param params.wallet - Wallet PMS du propriétaire
@@ -1059,6 +1238,10 @@ declare class PmsClient {
     private fetchUrl;
 }
 
+/**
+ * Utilitaires cryptographiques pour le SDK PMS.
+ */
+
 /**
  * Convertit des bytes en hex.
  */
@@ -1067,6 +1250,36 @@ declare function toHex(bytes: Uint8Array): string;
  * Convertit un hex en bytes.
  */
 declare function fromHex(hex: string): Uint8Array;
+/**
+ * Message canonique de signature de transaction — DOIT matcher
+ * `Transaction::signing_message` du Rust (dag-pms,
+ * crates/pms-types-transaction/src/transaction.rs) :
+ * `hex(SHA256(JSON({network_id, inputs, outputs, fee})))`
+ * Ordre des clés et compacité identiques à serde_json.
+ *
+ * Le `network_id` est inclus dans le message pour empêcher le replay
+ * cross-chain (une TX signée pour le testnet ne valide pas sur mainnet).
+ *
+ * Les inputs/outputs sont re-canonicalisés défensivement :
+ * - `TxInput` → `{out: {txid, index}}` (ordre de clés serde).
+ * - `TxOutput` → `{address, amount[, asset_id][, locked_until]
+ *   [, spend_condition][, created_at]}` — l'ORDRE des clés est celui de la
+ *   struct Rust et chaque clé optionnelle est OMISE quand undefined/null
+ *   (équivalent serde `skip_serializing_if`), jamais sérialisée à `null`.
+ *   `created_at` est système : ne le posez jamais côté client (géré ici
+ *   uniquement par fidélité de hash si un serveur l'echo).
+ *
+ * La signature côté wallet : `wallet.sign(encodeUtf8(msgHex))` —
+ * `wallet.sign` fait SHA256(message) puis ECDSA, ce qui correspond
+ * exactement au verify Rust (k256 hash la hex-string du message).
+ *
+ * @param networkId - Network ID de la chaîne cible (ex: "pms-testnet-v1")
+ * @param inputs - Inputs de la transaction
+ * @param outputs - Outputs de la transaction
+ * @param fee - Frais (string décimale, ex: "0.1")
+ * @returns Hash hex (64 chars) du message canonique
+ */
+declare function txSigningMessage(networkId: string, inputs: TxInput[], outputs: TxOutput[], fee: string): string;
 /**
  * Parse un montant décimal en satoshis (8 décimales).
  */
@@ -1075,6 +1288,64 @@ declare function parseAmount(amount: string): bigint;
  * Formate des satoshis en montant décimal.
  */
 declare function formatAmount(sats: bigint): string;
+/** Millisecondes par jour — base du demurrage (protocole 2.5). */
+declare const DAY_MS = 86400000;
+/**
+ * Dérive l'adresse multisig CANONIQUE d'une policy M-of-N (protocole 2.2).
+ *
+ * DOIT matcher `multisig_address` du Rust
+ * (crates/pms-core/src/validations/conditions.rs) :
+ * `"msig1" + hex(SHA256("pms-multisig-v1" || m || n || pk_1 || … || pk_n)[..20])`
+ * où les pubkeys sont normalisées (trim, sans `0x`, lowercase) puis TRIÉES —
+ * ordre et casse de déclaration indifférents.
+ *
+ * Tout output sous condition MultiSig DOIT porter cette adresse, sinon le
+ * moteur rejette la création (`InvalidSpendCondition`).
+ *
+ * @param m - Quorum requis (1..=N)
+ * @param pubkeys - Clés publiques secp256k1 hex des membres (N <= 16)
+ */
+declare function multisigAddress(m: number, pubkeys: string[]): string;
+/**
+ * Hash SHA-256 hex d'un préimage HashLock (protocole 2.2).
+ * À poser dans `SpendCondition.HashLock.hash_hex` à la création de l'output ;
+ * le dépensier fournira `hex(preimage)` dans `Unlock.preimage_hex`.
+ *
+ * @param preimage - Le secret, en bytes ou string UTF-8
+ */
+declare function hashlockHash(preimage: Uint8Array | string): string;
+/**
+ * Valeur effective d'un UTXO d'un asset à demurrage (protocole 2.5),
+ * **plancher au satoshi** (8 décimales).
+ *
+ * Formule moteur (Rust `effective_value`, Decimal exact) :
+ * `effective = amount − amount × bps × jours_pleins / 10_000` (plancher 0),
+ * `jours_pleins = floor((now − created_at) / 24h)`.
+ *
+ * La conservation moteur est `sum(outputs) <= sum(effective_inputs)` :
+ * arrondir VERS LE BAS au satoshi est donc toujours sûr (le résidu
+ * sub-satoshi est brûlé avec la décote). Retourne le montant maximal
+ * dépensable, en string décimale 8 dp.
+ *
+ * - `createdAtMs` undefined (UTXO pré-v0.10.0) → valeur nominale intacte.
+ * - `bpsPerDay` 0/undefined → valeur nominale intacte.
+ *
+ * @param amount - Montant nominal (string décimale)
+ * @param createdAtMs - `created_at` de l'UTXO (UNIX ms), tel que lu de l'API
+ * @param nowMs - Horloge courante (UNIX ms)
+ * @param bpsPerDay - `TokenMetadata.demurrage_bps_per_day` de l'asset
+ */
+declare function effectiveValue(amount: string, createdAtMs: number | undefined, nowMs: number, bpsPerDay: number | undefined): string;
+/**
+ * Filtre les UTXOs dépensables MAINTENANT : exclut ceux dont le time-lock
+ * (`locked_until`, protocole 2.1) est encore dans le futur. Le moteur
+ * rejetterait leur dépense (`OutputTimeLocked`) — à appliquer avant toute
+ * sélection de coins côté client.
+ *
+ * @param utxos - UTXOs tels que retournés par `GET /v1/wallet/{addr}/utxos`
+ * @param nowMs - Horloge courante (défaut: Date.now())
+ */
+declare function spendableUtxos<T extends Utxo>(utxos: T[], nowMs?: number): T[];
 
 /**
  * Fonctions de chiffrement pour le SDK PMS.
@@ -1105,4 +1376,4 @@ declare function formatAmount(sats: bigint): string;
  */
 declare function decryptPayload(encrypted: EncryptedPayload, recipientPrivateKeyHex: string): string;
 
-export { type ActivityDirection, type ActivityItem, type ActivityOptions, type ActivityResp, type ActivityType, type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type CubeAttributes, type HistoryItem, type LedgerInfo, type ListLedgersOptions, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type RuntimeConfig, type StreamActivityOptions, type SubmitResponse, type SupplyInfo, type TokenMetadata, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, formatAmount, fromHex, isValidMnemonic, parseAmount, toHex };
+export { type ActivityDirection, type ActivityItem, type ActivityOptions, type ActivityResp, type ActivityType, type BalanceInfo, type Block, type BurnNftResponse, type CoordinatorInfoResponse, type Cosigner, type CubeAttributes, DAY_MS, type HistoryItem, type LedgerInfo, type ListLedgersOptions, type MintCubeResponse, type NftMetadata, type NftResponse, PmsClient, type PmsClientConfig, PmsWallet, type PrepareTxRequest, type PrepareTxResponse, type ReservesLatest, type RuntimeConfig, type SendTxResponse, type SpendCondition, type StreamActivityOptions, type SubmitResponse, type SupplyInfo, type TokenMetadata, type TxInput, type TxOutput, type TxUtxo, type Unlock, type Utxo, type UtxoDetail, type WalletHistoryResp, type WalletResponse, decryptPayload, effectiveValue, formatAmount, fromHex, hashlockHash, isValidMnemonic, makeUnlock, multisigAddress, parseAmount, spendableUtxos, toHex, txSigningMessage };