@btc-vision/transaction 1.5.4 → 1.6.1

package/build/transaction/builders/InteractionTransaction.js

@@ -13,7 +13,7 @@ export class InteractionTransaction extends SharedInteractionTransaction {
         if (this.contractSecret.length !== 32) {
             throw new Error('Invalid contract secret length. Expected 32 bytes.');
         }
-        this.compiledTargetScript = this.calldataGenerator.compile(this.calldata, this.contractSecret, this.preimage, this.priorityFee, this.generateFeatures(parameters));
+        this.compiledTargetScript = this.calldataGenerator.compile(this.calldata, this.contractSecret, this.challenge, this.priorityFee, this.generateFeatures(parameters));
         this.scriptTree = this.getScriptTree();
         this.internalInit();
     }
@@ -25,6 +25,13 @@ export class InteractionTransaction extends SharedInteractionTransaction {
                 data: parameters.loadedStorage,
             });
         }
+        const submission = parameters.challenge.getSubmission();
+        if (submission) {
+            features.push({
+                opcode: Features.EPOCH_SUBMISSION,
+                data: submission,
+            });
+        }
         return features;
     }
 }

package/build/transaction/builders/SharedInteractionTransaction.d.ts

@@ -4,7 +4,8 @@ import { TransactionBuilder } from './TransactionBuilder.js';
 import { TransactionType } from '../enums/TransactionType.js';
 import { CalldataGenerator } from '../../generators/builders/CalldataGenerator.js';
 import { SharedInteractionParameters } from '../interfaces/ITransactionParameters.js';
-import { IMineableReward } from '../mineable/ChallengeGenerator.js';
+import { ITimeLockOutput } from '../mineable/TimelockGenerator.js';
+import { ChallengeSolution } from '../../epoch/ChallengeSolution.js';
 export declare abstract class SharedInteractionTransaction<T extends TransactionType> extends TransactionBuilder<T> {
     static readonly MAXIMUM_CALLDATA_SIZE: number;
     readonly randomBytes: Buffer;
@@ -12,8 +13,8 @@ export declare abstract class SharedInteractionTransaction<T extends Transaction
     protected leftOverFundsScriptRedeem: P2TRPayment | null;
     protected abstract readonly compiledTargetScript: Buffer;
     protected abstract readonly scriptTree: Taptree;
-    protected readonly preimage: Buffer;
-    protected readonly rewardChallenge: IMineableReward;
+    protected readonly challenge: ChallengeSolution;
+    protected readonly epochChallenge: ITimeLockOutput;
     protected calldataGenerator: CalldataGenerator;
     protected readonly calldata: Buffer;
     protected abstract readonly contractSecret: Buffer;
@@ -22,7 +23,7 @@ export declare abstract class SharedInteractionTransaction<T extends Transaction
     protected constructor(parameters: SharedInteractionParameters);
     getContractSecret(): Buffer;
     getRndBytes(): Buffer;
-    getPreimage(): Buffer;
+    getPreimage(): ChallengeSolution;
     protected scriptSignerXOnlyPubKey(): Buffer;
     protected generateKeyPairFromSeed(): ECPairInterface;
     protected buildTransaction(): Promise<void>;

package/build/transaction/builders/SharedInteractionTransaction.js

@@ -4,7 +4,7 @@ import { CalldataGenerator } from '../../generators/builders/CalldataGenerator.j
 import { Compressor } from '../../bytecode/Compressor.js';
 import { EcKeyPair } from '../../keypair/EcKeyPair.js';
 import { BitcoinUtils } from '../../utils/BitcoinUtils.js';
-import { ChallengeGenerator } from '../mineable/ChallengeGenerator.js';
+import { TimeLockGenerator } from '../mineable/TimelockGenerator.js';
 export class SharedInteractionTransaction extends TransactionBuilder {
     constructor(parameters) {
         super(parameters);
@@ -28,12 +28,12 @@ export class SharedInteractionTransaction extends TransactionBuilder {
         if (!parameters.calldata) {
             throw new Error('Calldata is required');
         }
-        if (!parameters.preimage) {
-            throw new Error('Preimage is required');
+        if (!parameters.challenge) {
+            throw new Error('Challenge solution is required');
         }
-        this.preimage = parameters.preimage;
+        this.challenge = parameters.challenge;
         this.disableAutoRefund = parameters.disableAutoRefund || false;
-        this.rewardChallenge = ChallengeGenerator.generateMineableReward(this.preimage, this.network);
+        this.epochChallenge = TimeLockGenerator.generateTimeLockAddress(this.challenge.publicKey.originalPublicKeyBuffer(), this.network);
         this.calldata = Compressor.compress(parameters.calldata);
         this.randomBytes = parameters.randomBytes || BitcoinUtils.rndBytes();
         this.scriptSigner = this.generateKeyPairFromSeed();
@@ -46,7 +46,7 @@ export class SharedInteractionTransaction extends TransactionBuilder {
         return this.randomBytes;
     }
     getPreimage() {
-        return this.preimage;
+        return this.challenge;
     }
     scriptSignerXOnlyPubKey() {
         return toXOnly(Buffer.from(this.scriptSigner.publicKey));
@@ -196,7 +196,7 @@ export class SharedInteractionTransaction extends TransactionBuilder {
             amountSpent - MINIMUM_AMOUNT_CA > MINIMUM_AMOUNT_REWARD) {
             this.addOutput({
                 value: Number(amountSpent - amountToCA),
-                address: this.rewardChallenge.address,
+                address: this.epochChallenge.address,
             });
         }
         const amount = this.addOptionalOutputsAndGetAmount();

package/build/transaction/builders/TransactionBuilder.d.ts

@@ -33,9 +33,11 @@ export declare abstract class TransactionBuilder<T extends TransactionType> exte
     protected from: string;
     protected _maximumFeeRate: number;
     protected isPubKeyDestination: boolean;
+    protected note?: Buffer;
     protected constructor(parameters: ITransactionParameters);
     static getFrom(from: string | undefined, keypair: ECPairInterface | Signer, network: Network): string;
     static witnessStackToScriptWitness(witness: Buffer[]): Buffer;
+    addOPReturn(buffer: Buffer): void;
     getFundingTransactionParameters(): Promise<IFundingTransactionParameters>;
     setDestinationAddress(address: string): void;
     setMaximumFeeRate(feeRate: number): void;

package/build/transaction/builders/TransactionBuilder.js

@@ -28,6 +28,14 @@ export class TransactionBuilder extends TweakedTransaction {
         this.utxos = parameters.utxos;
         this.optionalInputs = parameters.optionalInputs || [];
         this.to = parameters.to || undefined;
+        if (parameters.note) {
+            if (typeof parameters.note === 'string') {
+                this.note = Buffer.from(parameters.note, 'utf8');
+            }
+            else {
+                this.note = parameters.note;
+            }
+        }
         this.isPubKeyDestination = this.to
             ? AddressVerificator.isValidPublicKey(this.to, this.network)
             : false;
@@ -67,6 +75,13 @@ export class TransactionBuilder extends TweakedTransaction {
         writeVector(witness);
         return buffer;
     }
+    addOPReturn(buffer) {
+        const compileScript = script.compile([opcodes.OP_RETURN, buffer]);
+        this.addOutput({
+            value: 0,
+            script: compileScript,
+        });
+    }
     async getFundingTransactionParameters() {
         if (!this.estimatedFees) {
             this.estimatedFees = await this.estimateTransactionFees();
@@ -141,9 +156,19 @@ export class TransactionBuilder extends TweakedTransaction {
         this.inputs.push(input);
     }
     addOutput(output) {
-        if (output.value === 0)
-            return;
-        if (output.value < TransactionBuilder.MINIMUM_DUST) {
+        if (output.value === 0) {
+            const script = output;
+            if (!script.script || script.script.length === 0) {
+                throw new Error('Output value is 0 and no script provided');
+            }
+            if (script.script.length < 2) {
+                throw new Error('Output script is too short');
+            }
+            if (script.script[0] !== opcodes.OP_RETURN) {
+                throw new Error('Output script must start with OP_RETURN when value is 0');
+            }
+        }
+        else if (output.value < TransactionBuilder.MINIMUM_DUST) {
             throw new Error(`Output value is less than the minimum dust ${output.value} < ${TransactionBuilder.MINIMUM_DUST}`);
         }
         this.outputs.push(output);
@@ -203,6 +228,9 @@ export class TransactionBuilder extends TweakedTransaction {
         return total;
     }
     async addRefundOutput(amountSpent) {
+        if (this.note) {
+            this.addOPReturn(this.note);
+        }
         const sendBackAmount = this.totalInputAmount - amountSpent;
         if (sendBackAmount >= TransactionBuilder.MINIMUM_DUST) {
             if (AddressVerificator.isValidP2TRAddress(this.from, this.network)) {

package/build/transaction/interfaces/ITransactionParameters.d.ts

@@ -2,6 +2,7 @@ import { UTXO } from '../../utxo/interfaces/IUTXO.js';
 import { ITweakedTransactionData } from '../shared/TweakedTransaction.js';
 import { ChainId } from '../../network/ChainId.js';
 import { PsbtOutputExtended } from '@btc-vision/bitcoin';
+import { ChallengeSolution } from '../../epoch/ChallengeSolution.js';
 export interface LoadedStorage {
     [key: string]: string[];
 }
@@ -15,6 +16,7 @@ export interface ITransactionParameters extends ITweakedTransactionData {
     optionalOutputs?: PsbtOutputExtended[];
     chainId?: ChainId;
     noSignatures?: boolean;
+    readonly note?: string | Buffer;
     readonly feeRate: number;
     readonly priorityFee: bigint;
     readonly gasSatFee: bigint;
@@ -23,14 +25,10 @@ export interface IFundingTransactionParameters extends ITransactionParameters {
     amount: bigint;
     splitInputsInto?: number;
 }
-export interface IChallengeSolutionTransactionParameters extends ITransactionParameters {
-    amount: bigint;
-    readonly challengeSolution: Buffer;
-}
 export interface SharedInteractionParameters extends ITransactionParameters {
     calldata?: Buffer;
     disableAutoRefund?: boolean;
-    readonly preimage: Buffer;
+    readonly challenge: ChallengeSolution;
     readonly randomBytes?: Buffer;
     readonly loadedStorage?: LoadedStorage;
 }
@@ -43,5 +41,5 @@ export interface IDeploymentParameters extends Omit<ITransactionParameters, 'to'
     readonly bytecode: Buffer;
     readonly calldata?: Buffer;
     readonly randomBytes?: Buffer;
-    readonly preimage: Buffer;
+    readonly challenge: ChallengeSolution;
 }

package/build/transaction/mineable/TimelockGenerator.d.ts

@@ -0,0 +1,9 @@
+import { Network } from '@btc-vision/bitcoin';
+export interface ITimeLockOutput {
+    address: string;
+    witnessScript: Buffer;
+}
+export declare class TimeLockGenerator {
+    private static readonly CSV_BLOCKS;
+    static generateTimeLockAddress(publicKey: Buffer, network?: Network, csvBlocks?: number): ITimeLockOutput;
+}

package/build/transaction/mineable/TimelockGenerator.js

@@ -0,0 +1,24 @@
+import bitcoin, { networks, opcodes, script } from '@btc-vision/bitcoin';
+export class TimeLockGenerator {
+    static generateTimeLockAddress(publicKey, network = networks.bitcoin, csvBlocks = TimeLockGenerator.CSV_BLOCKS) {
+        const witnessScript = script.compile([
+            script.number.encode(csvBlocks),
+            opcodes.OP_CHECKSEQUENCEVERIFY,
+            opcodes.OP_DROP,
+            publicKey,
+            opcodes.OP_CHECKSIG,
+        ]);
+        const p2wsh = bitcoin.payments.p2wsh({
+            redeem: { output: witnessScript },
+            network,
+        });
+        if (!p2wsh.address) {
+            throw new Error('Failed to generate P2WSH address');
+        }
+        return {
+            address: p2wsh.address,
+            witnessScript: witnessScript,
+        };
+    }
+}
+TimeLockGenerator.CSV_BLOCKS = 75;

package/build/utils/StringToBuffer.d.ts

@@ -0,0 +1 @@
+export declare function stringToBuffer(str: string): Buffer;

package/build/utils/StringToBuffer.js

@@ -0,0 +1,3 @@
+export function stringToBuffer(str) {
+    return Buffer.from(str.replace('0x', ''), 'hex');
+}

package/build/utxo/OPNetLimitedProvider.d.ts

@@ -7,9 +7,6 @@ export interface WalletUTXOs {
     readonly pending: RawUTXOResponse[];
     readonly spentTransactions: RawUTXOResponse[];
 }
-export interface PreimageData {
-    readonly preimage: Buffer;
-}
 export declare class OPNetLimitedProvider {
     private readonly opnetAPIUrl;
     private readonly utxoPath;
@@ -18,7 +15,6 @@ export declare class OPNetLimitedProvider {
     fetchUTXO(settings: FetchUTXOParams): Promise<UTXO[]>;
     fetchUTXOMultiAddr(settings: FetchUTXOParamsMultiAddress): Promise<UTXO[]>;
     broadcastTransaction(transaction: string, psbt: boolean): Promise<BroadcastResponse | undefined>;
-    getPreimage(): Promise<PreimageData | undefined>;
     splitUTXOs(wallet: Wallet, network: Network, splitInputsInto: number, amountPerUTXO: bigint): Promise<BroadcastResponse | {
         error: string;
     }>;

package/build/utxo/OPNetLimitedProvider.js

@@ -103,13 +103,6 @@ export class OPNetLimitedProvider {
         }
         return result;
     }
-    async getPreimage() {
-        const result = await this.rpcMethod('btc_preimage', []);
-        if (!result) {
-            return;
-        }
-        return result;
-    }
     async splitUTXOs(wallet, network, splitInputsInto, amountPerUTXO) {
         const utxoSetting = {
             addresses: [wallet.p2wpkh, wallet.p2tr],

package/build/verification/TapscriptVerificator.d.ts

@@ -1,11 +1,14 @@
 import { Network, Taptree } from '@btc-vision/bitcoin';
+import { ChallengeSolution } from '../epoch/ChallengeSolution.js';
+import { Feature, Features } from '../generators/Features.js';
 export interface ContractAddressVerificationParams {
     readonly deployerPubKey: Buffer;
     readonly contractSaltPubKey: Buffer;
     readonly originalSalt: Buffer;
     readonly bytecode: Buffer;
-    readonly preimage: Buffer;
+    readonly challenge: ChallengeSolution;
     readonly priorityFee: bigint;
+    readonly features: Feature<Features>[];
     readonly calldata?: Buffer;
     readonly network?: Network;
 }

package/build/verification/TapscriptVerificator.js

@@ -5,7 +5,7 @@ export class TapscriptVerificator {
     static getContractAddress(params) {
         const network = params.network || networks.bitcoin;
         const scriptBuilder = new DeploymentGenerator(params.deployerPubKey, toXOnly(params.contractSaltPubKey), network);
-        const compiledTargetScript = scriptBuilder.compile(params.bytecode, params.originalSalt, params.preimage, params.priorityFee, params.calldata);
+        const compiledTargetScript = scriptBuilder.compile(params.bytecode, params.originalSalt, params.challenge, params.priorityFee, params.calldata, params.features);
         const scriptTree = [
             {
                 output: compiledTargetScript,
@@ -21,7 +21,7 @@ export class TapscriptVerificator {
     static verifyControlBlock(params, controlBlock) {
         const network = params.network || networks.bitcoin;
         const scriptBuilder = new DeploymentGenerator(params.deployerPubKey, toXOnly(params.contractSaltPubKey), network);
-        const compiledTargetScript = scriptBuilder.compile(params.bytecode, params.originalSalt, params.preimage, params.priorityFee, params.calldata);
+        const compiledTargetScript = scriptBuilder.compile(params.bytecode, params.originalSalt, params.challenge, params.priorityFee, params.calldata, params.features);
         const scriptTree = [
             {
                 output: compiledTargetScript,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@btc-vision/transaction",
     "type": "module",
-    "version": "1.5.4",
+    "version": "1.6.1",
     "author": "BlobMaster41",
     "description": "OPNet transaction library allows you to create and sign transactions for the OPNet network.",
     "engines": {
@@ -64,39 +64,39 @@
         "docs": "typedoc --out docs --exclude 'src/tests/*.ts' --tsconfig tsconfig.json --readme README.md --name OPNet --plugin typedoc-material-theme --themeColor '#cb9820' --exclude src/tests/test.ts --exclude src/index.ts src"
     },
     "devDependencies": {
-        "@babel/core": "^7.27.4",
+        "@babel/core": "^7.28.0",
         "@babel/plugin-proposal-class-properties": "^7.18.6",
-        "@babel/plugin-transform-runtime": "^7.27.4",
-        "@babel/preset-env": "^7.27.2",
+        "@babel/plugin-transform-runtime": "^7.28.0",
+        "@babel/preset-env": "^7.28.0",
         "@babel/preset-flow": "^7.27.1",
         "@babel/preset-react": "^7.27.1",
         "@babel/preset-typescript": "^7.27.1",
-        "@types/node": "^22.15.29",
+        "@types/node": "^24.1.0",
         "@types/sha.js": "^2.4.4",
-        "eslint": "^9.28.0",
+        "eslint": "^9.32.0",
         "gulp": "^5.0.1",
         "gulp-cached": "^1.1.1",
         "gulp-typescript": "^6.0.0-alpha.1",
         "https-browserify": "^1.0.0",
         "os-browserify": "^0.3.0",
-        "prettier": "^3.5.3",
+        "prettier": "^3.6.2",
         "stream-browserify": "^3.0.0",
         "stream-http": "^3.2.0",
-        "typedoc": "^0.28.5",
-        "typescript-eslint": "^8.33.0",
+        "typedoc": "^0.28.7",
+        "typescript-eslint": "^8.38.0",
         "webpack-cli": "^6.0.1"
     },
     "dependencies": {
-        "@babel/plugin-proposal-object-rest-spread": "^7.20.7",
+        "@babel/plugin-proposal-object-rest-spread": "^7.21.4-esm",
         "@bitcoinerlab/secp256k1": "^1.2.0",
         "@btc-vision/bitcoin": "^6.4.6",
         "@btc-vision/bitcoin-rpc": "^1.0.2",
         "@btc-vision/logger": "^1.0.6",
-        "@eslint/js": "^9.28.0",
-        "@noble/secp256k1": "^2.2.3",
+        "@eslint/js": "^9.32.0",
+        "@noble/secp256k1": "^2.3.0",
         "assert": "^2.1.0",
         "babel-loader": "^10.0.0",
-        "babel-plugin-transform-import-meta": "^2.3.2",
+        "babel-plugin-transform-import-meta": "^2.3.3",
         "babel-preset-react": "^6.24.1",
         "babelify": "^10.0.0",
         "bech32": "^2.0.0",
@@ -109,10 +109,10 @@
         "gulp-eslint-new": "^2.4.0",
         "gulp-logger-new": "^1.0.1",
         "process": "^0.11.10",
-        "sha.js": "^2.4.11",
+        "sha.js": "^2.4.12",
         "ts-loader": "^9.5.2",
         "ts-node": "^10.9.2",
         "typescript": "^5.8.3",
-        "webpack": "^5.99.9"
+        "webpack": "^5.100.2"
     }
 }

package/src/_version.ts

@@ -1 +1 @@
-export const version = '1.5.3';
+export const version = '1.6.1';

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 challenge
+     * @returns {Promise<boolean>} True if the challenge is valid
+     */
+    public async verify(): Promise<boolean> {
+        return EpochValidator.validateChallengeSolution(this);
+    }
+
+    /**
+     * Get the preimage challenge
+     * @returns {Buffer} The solution/challenge 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 challenge
+     * @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 challenge 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;
+}