import { Address } from "../../address/index.js"; import { Bytes, bytesConcat, bytesFrom, BytesLike } from "../../bytes/index.js"; import { Epoch, Script, ScriptLike, Since, SinceLike, Transaction, TransactionLike, WitnessArgs, WitnessArgsLike, } from "../../ckb/index.js"; import { CellDepInfo, CellDepInfoLike, Client, KnownScript, ScriptInfo, ScriptInfoLike, } from "../../client/index.js"; import { codec, Entity } from "../../codec/index.js"; import { HASH_CKB_SHORT_LENGTH, hashCkbShort } from "../../hasher/index.js"; import { Hex, hexFrom, HexLike } from "../../hex/index.js"; import { numFrom, NumLike, numToBytes } from "../../num/index.js"; import { apply, reduceAsync } from "../../utils/index.js"; import { SignerMultisig, SignerSignType, SignerType } from "../signer/index.js"; import { recoverMessageSecp256k1, SECP256K1_SIGNATURE_LENGTH, } from "./secp256k1Signing.js"; function sinceSatisfiesConstraint(inputSinceLike: NumLike, since: Since) { const inputSince = Since.from(inputSinceLike); if ( inputSince.relative !== since.relative || inputSince.metric !== since.metric ) { return false; } if (since.metric === "epoch") { return Epoch.from(inputSince.value).ge(since.value); } return inputSince.value >= since.value; } export type MultisigCkbWitnessLike = ( | { publicKeyHashes: HexLike[]; publicKeys?: undefined | null; } | { publicKeyHashes?: undefined | null; publicKeys: HexLike[]; } ) & { threshold: NumLike; mustMatch?: NumLike | null; signatures?: HexLike[] | null; }; /** * A class representing multisig information, holding information ingredients and containing utilities. * @public */ @codec({ encode: (encodable: MultisigCkbWitness) => { const { publicKeyHashes, threshold, mustMatch, signatures } = MultisigCkbWitness.from(encodable); if ( signatures.some((s) => s.length !== SECP256K1_SIGNATURE_LENGTH * 2 + 2) ) { throw Error("MultisigCkbWitness: invalid signature length"); } if ( publicKeyHashes.some((s) => s.length !== HASH_CKB_SHORT_LENGTH * 2 + 2) ) { throw Error("MultisigCkbWitness: invalid public key hash length"); } return bytesConcat( "0x00", numToBytes(mustMatch ?? 0), numToBytes(threshold), numToBytes(publicKeyHashes.length), ...publicKeyHashes, ...signatures, ); }, decode: (raw: Bytes) => { if (raw.length < 4) { throw Error("MultisigCkbWitness: data length too short"); } const [ _reserved, mustMatch, threshold, publicKeyHashesLength, ...rawKeyAndSignatures ] = raw; if ( rawKeyAndSignatures.length < publicKeyHashesLength * HASH_CKB_SHORT_LENGTH ) { throw Error("MultisigCkbWitness: invalid public key hashes length"); } const signatures = rawKeyAndSignatures.slice( publicKeyHashesLength * HASH_CKB_SHORT_LENGTH, ); return MultisigCkbWitness.from({ publicKeyHashes: Array.from(new Array(publicKeyHashesLength), (_, i) => hexFrom( rawKeyAndSignatures.slice( i * HASH_CKB_SHORT_LENGTH, (i + 1) * HASH_CKB_SHORT_LENGTH, ), ), ), threshold: numFrom(threshold), mustMatch: numFrom(mustMatch), signatures: Array.from( new Array(Math.floor(signatures.length / SECP256K1_SIGNATURE_LENGTH)), (_, i) => hexFrom( signatures.slice( i * SECP256K1_SIGNATURE_LENGTH, (i + 1) * SECP256K1_SIGNATURE_LENGTH, ), ), ), }); }, }) export class MultisigCkbWitness extends Entity.Base< MultisigCkbWitnessLike, MultisigCkbWitness >() { /** * @param publicKeyHashes - The public key hashes. * @param threshold - The threshold. * @param mustMatch - The number of signatures that must match. * @param signatures - The signatures. */ constructor( public publicKeyHashes: Hex[], public threshold: number, public mustMatch: number, public signatures: Hex[], ) { super(); const keysLength = publicKeyHashes.length; if (threshold <= 0 || threshold > keysLength) { throw new Error( "threshold should be in range from 1 to public keys length", ); } if (mustMatch < 0 || mustMatch > Math.min(keysLength, threshold)) { throw new Error( "mustMatch should be in range from 0 to min(public keys length, threshold)", ); } if (keysLength > 255) { throw new Error("public keys length should be less than 256"); } } /** * Create a MultisigCkbWitness from a MultisigCkbWitnessLike. * * @param witness - The witness like object. * @returns The MultisigCkbWitness. */ static from(witness: MultisigCkbWitnessLike): MultisigCkbWitness { const publicKeyHashes = (() => { if (witness.publicKeyHashes) { return witness.publicKeyHashes; } return witness.publicKeys.map((k) => hashCkbShort(k)); })(); return new MultisigCkbWitness( publicKeyHashes.map(hexFrom), Number(numFrom(witness.threshold)), Number(numFrom(witness.mustMatch ?? 0)), witness.signatures?.map(hexFrom) ?? [], ); } /** * Get the threshold of flexible signatures. */ get flexibleThreshold() { return this.threshold - this.mustMatch; } /** * Get the script args of the multisig script. * * @param since - The since value. * @returns The script args. */ scriptArgs(since?: SinceLike | null): Bytes { const hash = hashCkbShort( MultisigCkbWitness.from({ ...this, signatures: [] }).toBytes(), ); if (since != null) { return bytesConcat(hash, Since.from(since).toBytes()); } return bytesFrom(hash); } /** * Check if the multisig info is equal to another. * * @param otherLike - The other multisig info. * @returns True if the multisig info is equal, false otherwise. */ eqInfo(otherLike: MultisigCkbWitnessLike): boolean { const other = MultisigCkbWitness.from(otherLike); return ( this.publicKeyHashes.length === other.publicKeyHashes.length && this.publicKeyHashes.every((h, i) => h === other.publicKeyHashes[i]) && this.threshold === other.threshold && this.mustMatch === other.mustMatch ); } /** * Generate valid public key hashes and their signatures from the witness. * This method filters out invalid signatures, duplicate signatures, and signatures not in the multisig script. * * @param message - The message signed. * @returns A generator of public key hashes, signatures, and whether the signature is required. */ *generatePublicKeyHashesFromSignatures(message: BytesLike): Generator<{ pubkeyHash: Hex; signature: Hex; isRequired: boolean; }> { const publicKeyHashesFromSignature = new Set(); for (const signature of this.signatures.filter( (sig) => sig !== SignerMultisigCkbReadonly.EmptySignature, )) { const pubkey = (() => { try { return recoverMessageSecp256k1(message, signature); } catch (_) { // Ignore invalid signature return; } })(); if (pubkey === undefined) { continue; } const pubkeyHash = hashCkbShort(pubkey); if (publicKeyHashesFromSignature.has(pubkeyHash)) { continue; } const index = this.publicKeyHashes.indexOf(pubkeyHash); if (index === -1) { continue; } publicKeyHashesFromSignature.add(pubkeyHash); const isRequired = index < this.mustMatch; yield { pubkeyHash, signature, isRequired, }; } } /** * Calculate the number of matched signatures in the witness. * * @param message - The message signed. * @returns The number of required and flexible signatures. */ calcMatchedSignaturesCount(message: BytesLike): { required: number; flexible: number; } { let required = 0; let flexible = 0; for (const { isRequired } of this.generatePublicKeyHashesFromSignatures( message, )) { if (isRequired) { required += 1; } else { flexible += 1; } } return { required, flexible }; } } /** * A class extending Signer that provides access to a CKB multisig script. * This class does not support signing operations. * @public */ export class SignerMultisigCkbReadonly extends SignerMultisig { static EmptySignature = hexFrom("00".repeat(SECP256K1_SIGNATURE_LENGTH)); get type(): SignerType { return SignerType.CKB; } get signType(): SignerSignType { return SignerSignType.Unknown; } public readonly multisigInfo: MultisigCkbWitness; public readonly since?: Since; public readonly scriptInfos: Promise< { script: Script; cellDeps: CellDepInfo[]; }[] >; /** * Creates an instance of SignerMultisigCkbReadonly. * * @param client - The client instance. * @param multisigInfoLike - The multisig information. * @param options - The options. */ constructor( client: Client, multisigInfoLike: MultisigCkbWitnessLike, options?: { since?: SinceLike | null; scriptInfos?: (KnownScript | ScriptInfoLike)[] | null; } | null, ) { super(client); this.multisigInfo = MultisigCkbWitness.from(multisigInfoLike); this.since = apply(Since.from, options?.since); const args = this.multisigInfo.scriptArgs(this.since); this.scriptInfos = Promise.all( ( options?.scriptInfos ?? [ KnownScript.Secp256k1MultisigV2, KnownScript.Secp256k1MultisigV2Beta, KnownScript.Secp256k1Multisig, ] ).map(async (v) => { if (typeof v !== "string") { return ScriptInfo.from(v); } try { return await client.getKnownScript(v); } catch (_) { return undefined; } }), ).then((infos) => infos .filter((s) => s !== undefined) .map((i) => ({ script: Script.from({ ...i, args }), cellDeps: i.cellDeps, })), ); } /** * Get the number of members in the multisig script. * * @returns The number of members. */ async getMemberCount() { return this.multisigInfo.publicKeyHashes.length; } /** * Get the threshold of the multisig script. * * @returns The threshold. */ async getMemberThreshold() { return this.multisigInfo.threshold; } /** * Get the count of required member of the multisig script. * * @returns The must match count. */ async getMemberRequiredCount() { return this.multisigInfo.mustMatch; } async connect(): Promise {} async isConnected(): Promise { return true; } async getInternalAddress(): Promise { return this.getRecommendedAddress(); } async getAddressObjs(): Promise { return (await this.scriptInfos).map(({ script }) => Address.fromScript(script, this.client), ); } /** * Decode the witness args at a specific index. * * @param txLike - The transaction. * @param index - The index of the witness args. * @returns The decoded MultisigCkbWitness. */ decodeWitnessArgsAt( txLike: TransactionLike, index: number, ): MultisigCkbWitness | undefined { const tx = Transaction.from(txLike); return this.decodeWitnessArgs(tx.getWitnessArgs(index)); } /** * Decode the witness args. * * @param witnessLike - The witness args like object. * @returns The decoded MultisigCkbWitness. */ decodeWitnessArgs( witnessLike?: WitnessArgsLike | null, ): MultisigCkbWitness | undefined { if (!witnessLike) { return; } const witness = WitnessArgs.from(witnessLike); if (witness.lock == null) { return; } try { const decoded = MultisigCkbWitness.decode(witness.lock); if (decoded.eqInfo(this.multisigInfo)) { return decoded; } } catch (_) { // Returns undefined for invalid data } } /** * Prepare the witness args at a specific index. * * @param txLike - The transaction. * @param index - The index of the witness args. * @param transformer - The transformer function. * @returns The prepared transaction. */ async prepareWitnessArgsAt( txLike: TransactionLike, index: number, transformer?: | (( witness: MultisigCkbWitness, witnessArgs: WitnessArgs, ) => | MultisigCkbWitnessLike | undefined | null | void | Promise) | null, ): Promise { const tx = Transaction.from(txLike); const witnessArgs = tx.getWitnessArgs(index) ?? WitnessArgs.from({}); const multisigWitness = this.decodeWitnessArgs(witnessArgs) ?? this.multisigInfo.clone(); const transformed = MultisigCkbWitness.from( (await transformer?.(multisigWitness, witnessArgs)) ?? multisigWitness, ); transformed.signatures = transformed.signatures.slice( 0, this.multisigInfo.threshold, ); transformed.signatures.push( ...Array.from( new Array(this.multisigInfo.threshold - transformed.signatures.length), () => SignerMultisigCkbReadonly.EmptySignature, ), ); witnessArgs.lock = transformed.toHex(); tx.setWitnessArgs(index, witnessArgs); return tx; } /** * Prepare multisig witness, if the existence of multisig witness is detected, nothing happens * * @param txLike - The transaction to prepare. * @param scriptLike - The script to prepare. * @returns A promise that resolves to the prepared transaction */ async prepareTransactionOneScript( txLike: TransactionLike, scriptLike: ScriptLike, cellDeps: CellDepInfoLike[], ) { const tx = Transaction.from(txLike); const script = Script.from(scriptLike); const position = await tx.findInputIndexByLock(script, this.client); if (position === undefined) { return tx; } if (this.since) { const since = this.since.toNum(); for (const input of tx.inputs) { const { cellOutput } = await input.getCell(this.client); if ( script.eq(cellOutput.lock) && !sinceSatisfiesConstraint(input.since, this.since) ) { input.since = since; } } } await tx.addCellDepInfos(this.client, cellDeps); return this.prepareWitnessArgsAt(tx, position); } /** * Prepare transaction for multisig witness and adding related cell deps * * @param txLike - The transaction to prepare. * @returns A promise that resolves to the prepared transaction */ async prepareTransaction(txLike: TransactionLike): Promise { return await reduceAsync( await this.scriptInfos, (tx, { script, cellDeps }) => this.prepareTransactionOneScript(tx, script, cellDeps), Transaction.from(txLike), ); } /** * Get the number of valid signatures for matching multisig inputs in the transaction. * * @remarks * Returns `undefined` when the transaction has no inputs locked by any multisig address * supported by this signer. This method only counts signatures for matching multisig inputs * and does not imply that the transaction should be signed by this multisig. * * @param txLike - The transaction. * @returns The matched multisig signature count, or `undefined` when the transaction is unrelated to any multisig address supported by this signer. */ async getSignaturesCount( txLike: TransactionLike, ): Promise { const tx = Transaction.from(txLike); let minSignaturesCount = undefined; for (const { script } of await this.scriptInfos) { const info = await this.getSignInfo(tx, script); if (info === undefined) { continue; } const multisigWitness = this.decodeWitnessArgsAt(tx, info.position); if (!multisigWitness) { minSignaturesCount = 0; continue; } const { required, flexible } = multisigWitness.calcMatchedSignaturesCount( info.message, ); minSignaturesCount = Math.min( minSignaturesCount ?? 256, required + Math.min(flexible, this.multisigInfo.flexibleThreshold), ); } return minSignaturesCount; } /** * Check if related multisig inputs in the transaction need more signatures. * * @remarks * Returns `false` when the transaction has no inputs locked by any multisig address * supported by this signer. * A `false` result therefore means either the related multisig inputs are already fulfilled, * or the transaction is unrelated to all multisig addresses supported by this signer. * * @param txLike - The transaction to check. * @returns A promise that resolves to `true` when related multisig inputs still need signatures, and `false` otherwise. */ async needMoreSignatures(txLike: TransactionLike): Promise { const count = await this.getSignaturesCount(txLike); if (count == null) { return false; } return count < (await this.getMemberThreshold()); } /** * Get the sign info for a script. * * @param txLike - The transaction. * @param script - The script. * @returns The sign info. */ async getSignInfo( txLike: TransactionLike, script: ScriptLike, ): Promise<{ message: Hex; position: number } | undefined> { const tx = Transaction.from(txLike); const position = await tx.findInputIndexByLock(script, this.client); if (position == null) { return; } // === Replace the witness with a dummy one === const witness = tx.getWitnessArgs(position) ?? WitnessArgs.from({}); witness.lock = MultisigCkbWitness.from({ ...this.multisigInfo, signatures: Array.from( new Array(this.multisigInfo.threshold), () => SignerMultisigCkbReadonly.EmptySignature, ), }).toHex(); const clonedTx = tx.clone(); clonedTx.setWitnessArgs(position, witness); // === Replace the witness with a dummy one === return clonedTx.getSignHashInfo(script, this.client); } /** * Aggregate transactions. * * @param txs - The transactions to aggregate. * @returns The aggregated transaction. */ async aggregateTransactions(txs: TransactionLike[]): Promise { if (txs.length === 0) { throw Error("No transaction to aggregate"); } let res = Transaction.from(txs[0]); for (const { script } of await this.scriptInfos) { const info = await this.getSignInfo(res, script); if (info === undefined) { continue; } const signatures = new Map(); let requiredCount = 0; for (const txLike of txs) { const tx = Transaction.from(txLike); const multisigWitness = this.decodeWitnessArgsAt(tx, info.position); if (!multisigWitness) { continue; } for (const { pubkeyHash, signature, isRequired, } of multisigWitness.generatePublicKeyHashesFromSignatures( info.message, )) { if (signatures.has(pubkeyHash)) { continue; } if (isRequired) { // A required public key requiredCount += 1; } else if ( signatures.size - requiredCount >= this.multisigInfo.flexibleThreshold ) { // Not a required public key, and we have too many optional public key continue; } signatures.set(pubkeyHash, signature); if (signatures.size >= this.multisigInfo.threshold) { break; } } if (signatures.size >= this.multisigInfo.threshold) { break; } } res = await this.prepareWitnessArgsAt(res, info.position, (witness) => { witness.signatures = Array.from(signatures.values()); }); } return res; } }