@btc-vision/transaction 1.5.3 → 1.6.0

package/src/epoch/ChallengeSolution.ts

@@ -0,0 +1,196 @@
+import { stringToBuffer } from '../utils/StringToBuffer.js';
+import {
+    IChallengeSolution,
+    IChallengeSubmission,
+    IChallengeVerification,
+    RawChallenge,
+    RawChallengeSubmission,
+    RawChallengeVerification,
+} from './interfaces/IChallengeSolution.js';
+import { Address } from '../keypair/Address.js';
+import { EpochValidator } from './validator/EpochValidator.js';
+import { BinaryWriter } from '../buffer/BinaryWriter.js';
+import { MessageSigner } from '../keypair/MessageSigner.js';
+
+export class ChallengeVerification implements IChallengeVerification {
+    public readonly epochHash: Buffer;
+    public readonly epochRoot: Buffer;
+    public readonly targetHash: Buffer;
+    public readonly targetChecksum: Buffer;
+    public readonly startBlock: bigint;
+    public readonly endBlock: bigint;
+    public readonly proofs: readonly Buffer[];
+
+    constructor(data: RawChallengeVerification) {
+        this.epochHash = stringToBuffer(data.epochHash);
+        this.epochRoot = stringToBuffer(data.epochRoot);
+        this.targetHash = stringToBuffer(data.targetHash);
+        this.targetChecksum = stringToBuffer(data.targetChecksum);
+        this.startBlock = BigInt(data.startBlock);
+        this.endBlock = BigInt(data.endBlock);
+        this.proofs = Object.freeze(data.proofs.map((proof) => stringToBuffer(proof)));
+    }
+}
+
+export class ChallengeSubmission implements IChallengeSubmission {
+    public readonly publicKey: Address;
+    public readonly solution: Buffer;
+    public readonly graffiti: Buffer | undefined;
+    public readonly signature: Buffer;
+
+    constructor(
+        data: RawChallengeSubmission,
+        public readonly epochNumber: bigint,
+    ) {
+        this.publicKey = Address.fromString(data.publicKey);
+        this.solution = stringToBuffer(data.solution);
+        this.graffiti = data.graffiti ? stringToBuffer(data.graffiti) : undefined;
+        this.signature = stringToBuffer(data.signature);
+    }
+
+    public verifySignature(): boolean {
+        const signatureDataWriter = new BinaryWriter();
+        signatureDataWriter.writeAddress(this.publicKey);
+        signatureDataWriter.writeU64(this.epochNumber);
+        signatureDataWriter.writeBytes(this.solution);
+
+        if (this.graffiti) {
+            signatureDataWriter.writeBytes(this.graffiti);
+        }
+
+        const buffer = signatureDataWriter.getBuffer();
+        return MessageSigner.verifySignature(this.publicKey, buffer, this.signature);
+    }
+}
+
+export class ChallengeSolution implements IChallengeSolution {
+    public readonly epochNumber: bigint;
+    public readonly publicKey: Address;
+    public readonly solution: Buffer;
+    public readonly salt: Buffer;
+    public readonly graffiti: Buffer;
+    public readonly difficulty: number;
+    public readonly verification: ChallengeVerification;
+
+    private readonly submission?: ChallengeSubmission;
+
+    constructor(data: RawChallenge) {
+        this.epochNumber = BigInt(data.epochNumber);
+        this.publicKey = Address.fromString(data.publicKey);
+        this.solution = stringToBuffer(data.solution);
+        this.salt = stringToBuffer(data.salt);
+        this.graffiti = stringToBuffer(data.graffiti);
+        this.difficulty = data.difficulty;
+        this.verification = new ChallengeVerification(data.verification);
+        this.submission = data.submission
+            ? new ChallengeSubmission(data.submission, this.epochNumber + 2n)
+            : data.submission;
+    }
+
+    /**
+     * Static method to validate from raw data directly
+     */
+    public static async validateRaw(data: RawChallenge): Promise<boolean> {
+        return EpochValidator.validateEpochWinner(data);
+    }
+
+    public verifySubmissionSignature(): boolean {
+        if (!this.submission) {
+            throw new Error('No submission provided in request.');
+        }
+
+        return this.submission.verifySignature();
+    }
+
+    public getSubmission(): ChallengeSubmission | undefined {
+        if (!this.submission) {
+            return;
+        }
+
+        if (!this.verifySubmissionSignature()) {
+            throw new Error('Invalid submission signature.');
+        }
+
+        return this.submission;
+    }
+
+    /**
+     * Verify this preimage
+     * @returns {Promise<boolean>} True if the preimage is valid
+     */
+    public async verify(): Promise<boolean> {
+        return EpochValidator.validatePreimage(this);
+    }
+
+    /**
+     * Get the preimage buffer (alias for solution)
+     * @returns {Buffer} The solution/preimage as a buffer
+     */
+    public toBuffer(): Buffer {
+        return this.solution;
+    }
+
+    /**
+     * Get the solution as a hex string
+     * @returns {string} The solution as a hex string with 0x prefix
+     */
+    public toHex(): string {
+        return '0x' + this.solution.toString('hex');
+    }
+
+    /**
+     * Convert to raw format for serialization
+     */
+    public toRaw(): RawChallenge {
+        return {
+            epochNumber: this.epochNumber.toString(),
+            publicKey: this.publicKey.toHex(),
+            solution: this.toHex(),
+            salt: '0x' + this.salt.toString('hex'),
+            graffiti: '0x' + this.graffiti.toString('hex'),
+            difficulty: this.difficulty,
+            verification: {
+                epochHash: '0x' + this.verification.epochHash.toString('hex'),
+                epochRoot: '0x' + this.verification.epochRoot.toString('hex'),
+                targetHash: '0x' + this.verification.targetHash.toString('hex'),
+                targetChecksum: '0x' + this.verification.targetChecksum.toString('hex'),
+                startBlock: this.verification.startBlock.toString(),
+                endBlock: this.verification.endBlock.toString(),
+                proofs: this.verification.proofs.map((p) => '0x' + p.toString('hex')),
+            },
+        };
+    }
+
+    /**
+     * Calculate the expected solution hash for this preimage
+     * @returns {Promise<Buffer>} The calculated solution hash
+     */
+    public async calculateSolution(): Promise<Buffer> {
+        return EpochValidator.calculateSolution(
+            this.verification.targetChecksum,
+            this.publicKey.toBuffer(),
+            this.salt,
+        );
+    }
+
+    /**
+     * Check if the preimage meets a specific difficulty requirement
+     * @param {number} minDifficulty The minimum difficulty required
+     * @returns {Promise<{valid: boolean; difficulty: number}>} Validation result
+     */
+    public checkDifficulty(minDifficulty: number): { valid: boolean; difficulty: number } {
+        return EpochValidator.checkDifficulty(
+            this.solution,
+            this.verification.targetHash,
+            minDifficulty,
+        );
+    }
+
+    /**
+     * Get the mining target block for this epoch
+     * @returns {bigint | null} The target block number or null if epoch 0
+     */
+    public getMiningTargetBlock(): bigint | null {
+        return EpochValidator.getMiningTargetBlock(this.epochNumber);
+    }
+}

package/src/epoch/interfaces/IChallengeSolution.ts

@@ -0,0 +1,56 @@
+import { Address } from '../../keypair/Address.js';
+
+export interface IChallengeVerification {
+    readonly epochHash: Buffer;
+    readonly epochRoot: Buffer;
+    readonly targetHash: Buffer;
+    readonly targetChecksum: Buffer;
+    readonly startBlock: bigint;
+    readonly endBlock: bigint;
+    readonly proofs: readonly Buffer[];
+}
+
+export interface IChallengeSolution {
+    readonly epochNumber: bigint;
+    readonly publicKey: Address;
+    readonly solution: Buffer;
+    readonly salt: Buffer;
+    readonly graffiti: Buffer;
+    readonly difficulty: number;
+    readonly verification: IChallengeVerification;
+}
+
+export interface RawChallengeVerification {
+    readonly epochHash: string;
+    readonly epochRoot: string;
+    readonly targetHash: string;
+    readonly targetChecksum: string;
+    readonly startBlock: string;
+    readonly endBlock: string;
+    readonly proofs: readonly string[];
+}
+
+export interface RawChallengeSubmission {
+    readonly publicKey: string;
+    readonly solution: string;
+    readonly graffiti?: string;
+    readonly signature: string;
+}
+
+export interface IChallengeSubmission {
+    readonly publicKey: Address;
+    readonly solution: Buffer;
+    readonly graffiti?: Buffer;
+    readonly signature: Buffer;
+}
+
+export interface RawChallenge {
+    readonly epochNumber: string;
+    readonly publicKey: string;
+    readonly solution: string;
+    readonly salt: string;
+    readonly graffiti: string;
+    readonly difficulty: number;
+    readonly verification: RawChallengeVerification;
+    readonly submission?: RawChallengeSubmission;
+}

package/src/epoch/validator/EpochValidator.ts

@@ -0,0 +1,180 @@
+import { IChallengeSolution, RawChallenge } from '../interfaces/IChallengeSolution.js';
+import { ChallengeSolution } from '../ChallengeSolution.js';
+
+export class EpochValidator {
+    private static readonly BLOCKS_PER_EPOCH: bigint = 5n;
+    private static readonly GRAFFITI_LENGTH: number = 16;
+
+    /**
+     * Convert Buffer to Uint8Array
+     */
+    public static bufferToUint8Array(buffer: Buffer): Uint8Array {
+        return new Uint8Array(buffer);
+    }
+
+    /**
+     * Convert Uint8Array to Buffer
+     */
+    public static uint8ArrayToBuffer(array: Uint8Array): Buffer {
+        return Buffer.from(array);
+    }
+
+    /**
+     * Calculate SHA-1 hash
+     */
+    public static async sha1(data: Uint8Array): Promise<Uint8Array> {
+        const hashBuffer = await crypto.subtle.digest('SHA-1', data);
+        return new Uint8Array(hashBuffer);
+    }
+
+    /**
+     * Calculate mining preimage
+     */
+    public static calculatePreimage(checksumRoot: Buffer, publicKey: Buffer, salt: Buffer): Buffer {
+        // Ensure all are 32 bytes
+        if (checksumRoot.length !== 32 || publicKey.length !== 32 || salt.length !== 32) {
+            throw new Error('All inputs must be 32 bytes');
+        }
+
+        const preimage = Buffer.alloc(32);
+        for (let i = 0; i < 32; i++) {
+            preimage[i] = checksumRoot[i] ^ publicKey[i] ^ salt[i];
+        }
+
+        return preimage;
+    }
+
+    /**
+     * Count matching bits between two hashes
+     */
+    public static countMatchingBits(hash1: Buffer, hash2: Buffer): number {
+        let matchingBits = 0;
+        if (hash1.length !== hash2.length) {
+            throw new Error('Hashes must be of the same length');
+        }
+
+        const minLength = Math.min(hash1.length, hash2.length);
+        for (let i = 0; i < minLength; i++) {
+            const byte1 = hash1[i];
+            const byte2 = hash2[i];
+
+            if (byte1 === byte2) {
+                matchingBits += 8;
+            } else {
+                // Check individual bits
+                for (let bit = 7; bit >= 0; bit--) {
+                    if (((byte1 >> bit) & 1) === ((byte2 >> bit) & 1)) {
+                        matchingBits++;
+                    } else {
+                        return matchingBits;
+                    }
+                }
+            }
+        }
+
+        return matchingBits;
+    }
+
+    /**
+     * Verify an epoch solution using IPreimage
+     */
+    public static async verifySolution(
+        preimage: IChallengeSolution,
+        log: boolean = false,
+    ): Promise<boolean> {
+        try {
+            const verification = preimage.verification;
+            const calculatedPreimage = this.calculatePreimage(
+                verification.targetChecksum,
+                preimage.publicKey.toBuffer(),
+                preimage.salt,
+            );
+
+            const computedSolution = await this.sha1(this.bufferToUint8Array(calculatedPreimage));
+            const computedSolutionBuffer = this.uint8ArrayToBuffer(computedSolution);
+
+            if (!computedSolutionBuffer.equals(preimage.solution)) {
+                return false;
+            }
+
+            const matchingBits = this.countMatchingBits(
+                computedSolutionBuffer,
+                verification.targetHash,
+            );
+
+            if (matchingBits !== preimage.difficulty) {
+                return false;
+            }
+
+            const expectedStartBlock = preimage.epochNumber * this.BLOCKS_PER_EPOCH;
+            const expectedEndBlock = expectedStartBlock + this.BLOCKS_PER_EPOCH - 1n;
+
+            return !(
+                verification.startBlock !== expectedStartBlock ||
+                verification.endBlock !== expectedEndBlock
+            );
+        } catch (error) {
+            if (log) console.error('Verification error:', error);
+            return false;
+        }
+    }
+
+    /**
+     * Get the mining target block for an epoch
+     */
+    public static getMiningTargetBlock(epochNumber: bigint): bigint | null {
+        if (epochNumber === 0n) {
+            return null; // Epoch 0 cannot be mined
+        }
+
+        // Last block of previous epoch
+        return epochNumber * this.BLOCKS_PER_EPOCH - 1n;
+    }
+
+    /**
+     * Validate epoch winner from raw data
+     */
+    public static async validateEpochWinner(epochData: RawChallenge): Promise<boolean> {
+        const preimage = new ChallengeSolution(epochData);
+        return await this.verifySolution(preimage);
+    }
+
+    /**
+     * Validate epoch winner from Preimage instance
+     */
+    public static async validatePreimage(preimage: IChallengeSolution): Promise<boolean> {
+        return await this.verifySolution(preimage);
+    }
+
+    /**
+     * Calculate solution hash from preimage components
+     * @param targetChecksum The target checksum (32 bytes)
+     * @param publicKey The public key buffer (32 bytes)
+     * @param salt The salt buffer (32 bytes)
+     * @returns The SHA-1 hash of the preimage
+     */
+    public static async calculateSolution(
+        targetChecksum: Buffer,
+        publicKey: Buffer,
+        salt: Buffer,
+    ): Promise<Buffer> {
+        const preimage = this.calculatePreimage(targetChecksum, publicKey, salt);
+        const hash = await this.sha1(this.bufferToUint8Array(preimage));
+        return this.uint8ArrayToBuffer(hash);
+    }
+
+    /**
+     * Check if a solution meets the minimum difficulty requirement
+     */
+    public static checkDifficulty(
+        solution: Buffer,
+        targetHash: Buffer,
+        minDifficulty: number,
+    ): { valid: boolean; difficulty: number } {
+        const difficulty = this.countMatchingBits(solution, targetHash);
+        return {
+            valid: difficulty >= minDifficulty,
+            difficulty,
+        };
+    }
+}

package/src/generators/Features.ts

@@ -1,7 +1,9 @@
 import { LoadedStorage } from '../transaction/interfaces/ITransactionParameters.js';
+import { ChallengeSubmission } from '../epoch/ChallengeSolution.js';
 
 export enum Features {
     ACCESS_LIST = 1,
+    EPOCH_SUBMISSION = 2,
 }
 
 export interface Feature<T extends Features> {
@@ -12,3 +14,7 @@ export interface Feature<T extends Features> {
 export interface AccessListFeature extends Feature<Features.ACCESS_LIST> {
     data: LoadedStorage;
 }
+
+export interface EpochSubmissionFeature extends Feature<Features.EPOCH_SUBMISSION> {
+    data: ChallengeSubmission;
+}

package/src/generators/Generator.ts

@@ -1,6 +1,6 @@
 import { Network, networks, toXOnly } from '@btc-vision/bitcoin';
 import { BinaryWriter } from '../buffer/BinaryWriter.js';
-import { AccessListFeature, Feature, Features } from './Features.js';
+import { AccessListFeature, EpochSubmissionFeature, Feature, Features } from './Features.js';
 import { Address } from '../keypair/Address.js';
 import { Compressor } from '../bytecode/Compressor.js';
 
@@ -107,10 +107,16 @@ export abstract class Generator {
 
     protected encodeFeature(feature: Feature<Features>): Buffer[][] {
         switch (feature.opcode) {
-            case Features.ACCESS_LIST:
+            case Features.ACCESS_LIST: {
                 return this.splitBufferIntoChunks(
                     this.encodeAccessListFeature(feature as AccessListFeature),
                 );
+            }
+            case Features.EPOCH_SUBMISSION: {
+                return this.splitBufferIntoChunks(
+                    this.encodeChallengeSubmission(feature as EpochSubmissionFeature),
+                );
+            }
             default:
                 throw new Error(`Unknown feature type: ${feature.opcode}`);
         }
@@ -141,4 +147,20 @@ export abstract class Generator {
 
         return Compressor.compress(Buffer.from(writer.getBuffer()));
     }
+
+    private encodeChallengeSubmission(feature: EpochSubmissionFeature): Buffer {
+        if ('verifySignature' in feature.data && !feature.data.verifySignature()) {
+            throw new Error('Invalid signature in challenge submission feature');
+        }
+
+        const writer = new BinaryWriter();
+        writer.writeBytes(feature.data.publicKey.originalPublicKeyBuffer());
+        writer.writeBytes(feature.data.solution);
+
+        if (feature.data.graffiti) {
+            writer.writeBytesWithLength(feature.data.graffiti);
+        }
+
+        return Buffer.from(writer.getBuffer());
+    }
 }

package/src/generators/builders/CalldataGenerator.ts

@@ -4,6 +4,7 @@ import { Compressor } from '../../bytecode/Compressor.js';
 import { EcKeyPair } from '../../keypair/EcKeyPair.js';
 import { Feature, Features } from '../Features.js';
 import { Generator } from '../Generator.js';
+import { ChallengeSolution } from '../../epoch/ChallengeSolution.js';
 
 /**
  * Class to generate bitcoin script for interaction transactions
@@ -56,7 +57,7 @@ export class CalldataGenerator extends Generator {
      * Compile an interaction bitcoin script
      * @param {Buffer} calldata - The calldata to use
      * @param {Buffer} contractSecret - The contract secret
-     * @param preimage
+     * @param {ChallengeSolution} challenge
      * @param maxPriority - Amount of satoshis to spend max on priority fee
      * @param {Feature<Features>[]} features - The features to use
      * @returns {Buffer} - The compiled script
@@ -65,7 +66,7 @@ export class CalldataGenerator extends Generator {
     public compile(
         calldata: Buffer,
         contractSecret: Buffer,
-        preimage: Buffer,
+        challenge: ChallengeSolution,
         maxPriority: bigint,
         features: Feature<Features>[] = [],
     ): Buffer {
@@ -89,7 +90,10 @@ export class CalldataGenerator extends Generator {
             opcodes.OP_TOALTSTACK,
 
             // CHALLENGE PREIMAGE FOR REWARD,
-            preimage,
+            challenge.publicKey.originalPublicKeyBuffer(),
+            opcodes.OP_TOALTSTACK,
+
+            challenge.solution,
             opcodes.OP_TOALTSTACK,
 
             this.xSenderPubKey,

package/src/generators/builders/DeploymentGenerator.ts

@@ -1,6 +1,7 @@
 import { crypto, Network, networks, opcodes, script } from '@btc-vision/bitcoin';
 import { Generator } from '../Generator.js';
 import { Feature, Features } from '../Features.js';
+import { ChallengeSolution } from '../../epoch/ChallengeSolution.js';
 
 export const OPNET_DEPLOYMENT_VERSION = 0x00;
 export const versionBuffer = Buffer.from([OPNET_DEPLOYMENT_VERSION]);
@@ -18,19 +19,28 @@ export class DeploymentGenerator extends Generator {
      * Compile a bitcoin script representing a contract deployment
      * @param {Buffer} contractBytecode - The contract bytecode
      * @param {Buffer} contractSalt - The contract salt
-     * @param {Buffer} preimage - The preimage for reward
+     * @param {ChallengeSolution} preimage - The preimage for reward
      * @param {bigint} maxPriority - The maximum priority for the contract
      * @param {Buffer} [calldata] - The calldata to be passed to the contract
+     * @param {Feature<Features>[]} [features] - Optional features to include in the script
      * @returns {Buffer} - The compiled script
      */
     public compile(
         contractBytecode: Buffer,
         contractSalt: Buffer,
-        preimage: Buffer,
+        preimage: ChallengeSolution,
         maxPriority: bigint,
         calldata?: Buffer,
+        features?: Feature<Features>[],
     ): Buffer {
-        const asm = this.getAsm(contractBytecode, contractSalt, preimage, maxPriority, calldata);
+        const asm = this.getAsm(
+            contractBytecode,
+            contractSalt,
+            preimage,
+            maxPriority,
+            calldata,
+            features,
+        );
         const compiled = script.compile(asm);
 
         /**
@@ -47,7 +57,7 @@ export class DeploymentGenerator extends Generator {
     private getAsm(
         contractBytecode: Buffer,
         contractSalt: Buffer,
-        preimage: Buffer,
+        preimage: ChallengeSolution,
         maxPriority: bigint,
         calldata?: Buffer,
         features?: Feature<Features>[],
@@ -55,7 +65,6 @@ export class DeploymentGenerator extends Generator {
         if (!this.contractSaltPubKey) throw new Error('Contract salt public key not set');
 
         const dataChunks: Buffer[][] = this.splitBufferIntoChunks(contractBytecode);
-
         const calldataChunks: Buffer[][] = calldata ? this.splitBufferIntoChunks(calldata) : [];
 
         const featuresList: Features[] = [];
@@ -76,7 +85,10 @@ export class DeploymentGenerator extends Generator {
             opcodes.OP_TOALTSTACK,
 
             // CHALLENGE PREIMAGE FOR REWARD,
-            preimage,
+            preimage.publicKey.originalPublicKeyBuffer(),
+            opcodes.OP_TOALTSTACK,
+
+            preimage.solution,
             opcodes.OP_TOALTSTACK,
 
             this.xSenderPubKey,

package/src/keypair/Address.ts

@@ -5,6 +5,7 @@ import { AddressVerificator } from './AddressVerificator.js';
 import { EcKeyPair } from './EcKeyPair.js';
 import { ContractAddress } from '../transaction/ContractAddress.js';
 import { BitcoinUtils } from '../utils/BitcoinUtils.js';
+import { ITimeLockOutput, TimeLockGenerator } from '../transaction/mineable/TimelockGenerator.js';
 
 /**
  * Objects of type "Address" are the representation of tweaked public keys. They can be converted to different address formats.
@@ -317,6 +318,39 @@ export class Address extends Uint8Array {
         throw new Error('Public key not set');
     }
 
+    /**
+     * Generate a P2WSH address with CSV (CheckSequenceVerify) timelock
+     * The resulting address can only be spent after the specified number of blocks
+     * have passed since the UTXO was created.
+     *
+     * @param {bigint | number | string} duration - The number of blocks that must pass before spending (1-65535)
+     * @param {Network} network - The Bitcoin network to use
+     * @returns {ITimeLockOutput} The timelocked address and its witness script
+     * @throws {Error} If the block number is out of range or public key is not available
+     */
+    public toCSV(duration: bigint | number | string, network: Network): ITimeLockOutput {
+        const n = Number(duration);
+
+        // First, let's validate the block number to ensure it's within the valid range
+        // CSV uses sequence numbers, which have special encoding for block-based locks
+        if (n < 1 || n > 65535) {
+            throw new Error('CSV block number must be between 1 and 65535');
+        }
+
+        // We need the original public key in compressed format for the script
+        // Your class stores this in #originalPublicKey when a key is set
+        if (!this.#originalPublicKey) {
+            throw new Error('Cannot create CSV address: public key not set');
+        }
+
+        // Convert the public key to Buffer format that TimeLockGenerator expects
+        const publicKeyBuffer = Buffer.from(this.#originalPublicKey);
+
+        // Now we can use your TimeLockGenerator to create the timelocked address
+        // Converting bigint to number is safe here because we've already validated the range
+        return TimeLockGenerator.generateTimeLockAddress(publicKeyBuffer, network, n);
+    }
+
     /**
      * Get an opnet address encoded in bech32m format.
      * @param network