@hardkas/toolkit 0.11.1-alpha → 0.11.4-alpha

package/src/payment.ts

@@ -1,81 +0,0 @@
-import { buildKaspaUri } from '@hardkas/tx-builder';
-import { EvidenceBatchExporter } from '@hardkas/artifacts';
-import { InvoiceStoreJson, InvoiceRecord } from './stores/invoice-store.js';
-
-export interface PaymentToolkitOptions {
-    storePath?: string;
-}
-
-export class PaymentToolkit {
-    private store: InvoiceStoreJson;
-
-    private constructor(
-        public readonly merchantId: string,
-        private readonly options: PaymentToolkitOptions
-    ) {
-        this.store = new InvoiceStoreJson({ filePath: options.storePath || '.hardkas-data/invoices.json' });
-    }
-
-    public static openMerchant(merchantId: string, options: PaymentToolkitOptions = {}): PaymentToolkit {
-        return new PaymentToolkit(merchantId, options);
-    }
-
-    public async createInvoice(opts: { amount: bigint; currency: string }): Promise<InvoiceRecord> {
-        const id = `inv_${Date.now()}`;
-        const result = buildKaspaUri({
-            address: `kaspa:${this.merchantId}`,
-            amountSompi: opts.amount * 100_000_000n, // convert to sompi
-            message: `Invoice ${id}`
-        });
-
-        const invoice: InvoiceRecord = {
-            id,
-            merchantId: this.merchantId,
-            amount: opts.amount,
-            currency: opts.currency,
-            status: 'pending',
-            uri: result.uri,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString()
-        };
-
-        this.store.save(invoice);
-        return invoice;
-    }
-
-    public async getInvoice(id: string): Promise<InvoiceRecord | undefined> {
-        return this.store.get(id);
-    }
-
-    public async listInvoices(): Promise<InvoiceRecord[]> {
-        return this.store.listByMerchant(this.merchantId);
-    }
-
-    public async stats(): Promise<{ totalInvoices: number; paidInvoices: number }> {
-        return this.store.stats(this.merchantId);
-    }
-
-    public async check(invoiceId: string): Promise<string> {
-        const inv = this.store.get(invoiceId);
-        return inv ? inv.status : 'not_found';
-    }
-
-    public async receipt(invoiceId: string): Promise<any> {
-        return {
-            schema: "paymentReceipt.v1",
-            invoiceId,
-            merchantId: this.merchantId,
-            status: "paid",
-            timestamp: new Date().toISOString()
-        };
-    }
-    
-    // For lab testing/simulation manually paying an invoice
-    public async simulatePay(invoiceId: string): Promise<void> {
-        const inv = this.store.get(invoiceId);
-        if (inv) {
-            inv.status = 'paid';
-            this.store.save(inv);
-        }
-    }
-}

package/src/silver/index.ts

@@ -1,102 +0,0 @@
-import { SILVER_TEMPLATES } from './templates.js';
-import { SilverArtifact, SilverBuildResult, SilverClaims, SilverEvidence, SilverSimulationResult } from './types.js';
-
-export class SilverTemplate {
-    constructor(public readonly name: string, private readonly rawSource: string) {}
-
-    public parameters(): string[] {
-        const regex = /<([^>]+)>/g;
-        const matches = [...this.rawSource.matchAll(regex)];
-        return Array.from(new Set(matches.map(m => m[1] as string)));
-    }
-
-    public fill(params: Record<string, string | number>): string {
-        let filledSource = this.rawSource;
-        const requiredParams = this.parameters();
-        
-        for (const req of requiredParams) {
-            if (!(req in params)) {
-                throw new Error(`Missing parameter for template '${this.name}': <${req}>`);
-            }
-            filledSource = filledSource.replace(new RegExp(`<${req}>`, 'g'), String(params[req]));
-        }
-        return filledSource;
-    }
-}
-
-export class SilverToolkit {
-    private constructor() {}
-
-    public static open(): SilverToolkit {
-        return new SilverToolkit();
-    }
-
-    private getClaims(): SilverClaims {
-        return {
-            realSilverCompiler: false,
-            vmConsensusEquivalence: false,
-            mainnetReady: false,
-            productionSafe: false,
-            simulatedOnly: true
-        };
-    }
-
-    public templates(): string[] {
-        return Object.keys(SILVER_TEMPLATES);
-    }
-
-    public template(name: string): SilverTemplate {
-        if (!SILVER_TEMPLATES[name]) {
-            throw new Error(`Silver template not found: ${name}`);
-        }
-        return new SilverTemplate(name, SILVER_TEMPLATES[name]);
-    }
-
-    public async build(source: string): Promise<SilverBuildResult> {
-        // Mock bytecode compilation
-        const mockBytecode = Buffer.from(source).toString('hex');
-        return {
-            source,
-            bytecode: mockBytecode,
-            claims: this.getClaims()
-        };
-    }
-
-    public async simulate(build: SilverBuildResult, args?: string[]): Promise<SilverSimulationResult> {
-        // Mock VM execution
-        return {
-            success: true,
-            executionTrace: ["OP_TRUE", "OP_CHECKSIG"],
-            gasConsumed: 1000,
-            claims: this.getClaims()
-        };
-    }
-
-    public async artifact(build: SilverBuildResult, name?: string): Promise<SilverArtifact> {
-        const art: any = {
-            id: `silver-${Date.now()}`,
-            source: build.source,
-            bytecode: build.bytecode,
-            createdAt: new Date().toISOString(),
-            claims: this.getClaims()
-        };
-        if (name !== undefined) {
-            art.name = name;
-        }
-        return art as SilverArtifact;
-    }
-
-    public async evidence(build: SilverBuildResult, simulation: SilverSimulationResult): Promise<SilverEvidence> {
-        return {
-            schema: "hardkas.script-evidence.v1",
-            artifactId: `silver-${Date.now()}`,
-            simulationResult: {
-                success: simulation.success,
-                executionTrace: simulation.executionTrace,
-                gasConsumed: simulation.gasConsumed
-            },
-            timestamp: new Date().toISOString(),
-            claims: this.getClaims()
-        };
-    }
-}

package/src/silver/templates.ts

@@ -1,27 +0,0 @@
-export const SILVER_TEMPLATES: Record<string, string> = {
-    "op-true": `OP_TRUE`,
-    "timelock": `<locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP
-<pubkey> OP_CHECKSIG`,
-    "escrow": `OP_IF
-  <buyer_pubkey> OP_CHECKSIGVERIFY
-  <arbiter_pubkey> OP_CHECKSIG
-OP_ELSE
-  <seller_pubkey> OP_CHECKSIGVERIFY
-  <arbiter_pubkey> OP_CHECKSIG
-OP_ENDIF`,
-    "htlc": `OP_IF
-  OP_SHA256 <secret_hash> OP_EQUALVERIFY
-  <receiver_pubkey> OP_CHECKSIG
-OP_ELSE
-  <locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP
-  <sender_pubkey> OP_CHECKSIG
-OP_ENDIF`,
-    "atomic-swap": `OP_IF
-  OP_SHA256 <secret_hash> OP_EQUALVERIFY
-  <participant_b_pubkey> OP_CHECKSIG
-OP_ELSE
-  <locktime> OP_CHECKLOCKTIMEVERIFY OP_DROP
-  <participant_a_pubkey> OP_CHECKSIG
-OP_ENDIF`,
-    "multisig": `OP_2 <pubkey1> <pubkey2> <pubkey3> OP_3 OP_CHECKMULTISIG`
-};

package/src/silver/types.ts

@@ -1,37 +0,0 @@
-export interface SilverClaims {
-    realSilverCompiler: boolean;
-    vmConsensusEquivalence: boolean;
-    mainnetReady: boolean;
-    productionSafe: boolean;
-    simulatedOnly: boolean;
-}
-
-export interface SilverBuildResult {
-    source: string;
-    bytecode: string;
-    claims: SilverClaims;
-}
-
-export interface SilverSimulationResult {
-    success: boolean;
-    executionTrace: string[];
-    gasConsumed: number;
-    claims: SilverClaims;
-}
-
-export interface SilverArtifact {
-    id: string;
-    name?: string;
-    source: string;
-    bytecode: string;
-    createdAt: string;
-    claims: SilverClaims;
-}
-
-export interface SilverEvidence {
-    schema: string;
-    artifactId: string;
-    simulationResult: Omit<SilverSimulationResult, 'claims'>;
-    timestamp: string;
-    claims: SilverClaims;
-}

package/src/snapshot/backends/FsSnapshotBackend.ts

@@ -1,100 +0,0 @@
-import { SnapshotBackend, SnapshotManifest, SnapshotState } from "../types.js";
-import fs from "fs-extra";
-import path from "path";
-import crypto from "crypto";
-import { snapshotReplacer, snapshotReviver } from "../serialization.js";
-
-export class FsSnapshotBackend implements SnapshotBackend {
-    private baseDir: string;
-
-    constructor(baseDir: string = ".hardkas-snapshots") {
-        this.baseDir = baseDir;
-    }
-
-    async save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest> {
-        const snapshotDir = path.join(this.baseDir, id);
-        await fs.ensureDir(snapshotDir);
-
-        const stateHashes: Record<string, string> = {};
-        const participants = Object.keys(state);
-
-        // Write each participant's state to a separate file
-        for (const [pId, pState] of Object.entries(state)) {
-            const data = JSON.stringify(pState, snapshotReplacer, 2);
-            stateHashes[pId] = crypto.createHash("sha256").update(data).digest("hex");
-            await fs.writeFile(path.join(snapshotDir, `${pId}.json`), data);
-        }
-
-        const manifest: SnapshotManifest = {
-            schema: "hardkas.snapshot.v1",
-            snapshotId: id,
-            name,
-            createdAt: Date.now(),
-            backend: "filesystem",
-            path: snapshotDir,
-            participants,
-            stateHashes,
-            claims: {
-                containsFullStateInline: false,
-                restorableLocalState: true,
-                networkStateCaptured: false
-            }
-        };
-
-        // Write manifest
-        await fs.writeFile(path.join(snapshotDir, "manifest.json"), JSON.stringify(manifest, null, 2));
-
-        return manifest;
-    }
-
-    async load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }> {
-        const snapshotDir = path.join(this.baseDir, id);
-        if (!await fs.pathExists(snapshotDir)) {
-            throw new Error(`Snapshot ${id} not found in filesystem backend at ${snapshotDir}`);
-        }
-
-        const manifestData = await fs.readFile(path.join(snapshotDir, "manifest.json"), "utf8");
-        const manifest: SnapshotManifest = JSON.parse(manifestData);
-
-        const state: Record<string, SnapshotState> = {};
-        for (const pId of manifest.participants) {
-            const stateData = await fs.readFile(path.join(snapshotDir, `${pId}.json`), "utf8");
-            state[pId] = JSON.parse(stateData, snapshotReviver);
-        }
-
-        return { manifest, state };
-    }
-
-    async list(): Promise<SnapshotManifest[]> {
-        if (!await fs.pathExists(this.baseDir)) {
-            return [];
-        }
-
-        const entries = await fs.readdir(this.baseDir, { withFileTypes: true });
-        const manifests: SnapshotManifest[] = [];
-
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                const manifestPath = path.join(this.baseDir, entry.name, "manifest.json");
-                if (await fs.pathExists(manifestPath)) {
-                    const data = await fs.readFile(manifestPath, "utf8");
-                    manifests.push(JSON.parse(data));
-                }
-            }
-        }
-
-        return manifests;
-    }
-
-    async delete(id: string): Promise<void> {
-        const snapshotDir = path.join(this.baseDir, id);
-        if (await fs.pathExists(snapshotDir)) {
-            await fs.remove(snapshotDir);
-        }
-    }
-
-    async branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest> {
-        const { state } = await this.load(baseId);
-        return this.save(newId, newName, state);
-    }
-}

package/src/snapshot/backends/MemorySnapshotBackend.ts

@@ -1,65 +0,0 @@
-import { SnapshotBackend, SnapshotManifest, SnapshotState } from "../types.js";
-import crypto from "crypto";
-import { snapshotReplacer, snapshotReviver } from "../serialization.js";
-
-export class MemorySnapshotBackend implements SnapshotBackend {
-    private snapshots = new Map<string, { manifest: SnapshotManifest; state: Record<string, SnapshotState> }>();
-
-    async save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest> {
-        const stateHashes: Record<string, string> = {};
-        const participants = Object.keys(state);
-
-        for (const [pId, pState] of Object.entries(state)) {
-            stateHashes[pId] = crypto.createHash("sha256").update(JSON.stringify(pState, snapshotReplacer)).digest("hex");
-        }
-
-        const manifest: SnapshotManifest = {
-            schema: "hardkas.snapshot.v1",
-            snapshotId: id,
-            name,
-            createdAt: Date.now(),
-            backend: "memory",
-            participants,
-            stateHashes,
-            claims: {
-                containsFullStateInline: true,
-                restorableLocalState: true,
-                networkStateCaptured: false
-            }
-        };
-
-        // Deep copy state to ensure isolation
-        const deepCopiedState = JSON.parse(JSON.stringify(state, snapshotReplacer), snapshotReviver);
-        this.snapshots.set(id, { manifest, state: deepCopiedState });
-
-        return manifest;
-    }
-
-    async load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }> {
-        const entry = this.snapshots.get(id);
-        if (!entry) {
-            throw new Error(`Snapshot ${id} not found in memory backend`);
-        }
-        // Return a deep copy to prevent mutation of the snapshot itself
-        return {
-            manifest: JSON.parse(JSON.stringify(entry.manifest)),
-            state: JSON.parse(JSON.stringify(entry.state, snapshotReplacer), snapshotReviver)
-        };
-    }
-
-    async list(): Promise<SnapshotManifest[]> {
-        return Array.from(this.snapshots.values()).map(s => s.manifest);
-    }
-
-    async delete(id: string): Promise<void> {
-        this.snapshots.delete(id);
-    }
-
-    async branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest> {
-        const entry = this.snapshots.get(baseId);
-        if (!entry) throw new Error(`Base snapshot ${baseId} not found`);
-
-        const newState = JSON.parse(JSON.stringify(entry.state, snapshotReplacer), snapshotReviver);
-        return this.save(newId, newName, newState);
-    }
-}

package/src/snapshot/index.ts

@@ -1,102 +0,0 @@
-import { SnapshotBackend, SnapshotManifest, SnapshotParticipant, SnapshotState } from "./types.js";
-import { MemorySnapshotBackend } from "./backends/MemorySnapshotBackend.js";
-import { FsSnapshotBackend } from "./backends/FsSnapshotBackend.js";
-import crypto from "crypto";
-
-export interface SnapshotToolkitOptions {
-    backend?: "memory" | "filesystem";
-    dir?: string;
-}
-
-export class SnapshotToolkit {
-    private backend: SnapshotBackend;
-    private participants = new Map<string, SnapshotParticipant>();
-
-    private constructor(options: SnapshotToolkitOptions) {
-        if (options.backend === "filesystem") {
-            this.backend = new FsSnapshotBackend(options.dir);
-        } else {
-            this.backend = new MemorySnapshotBackend();
-        }
-    }
-
-    public static open(options: SnapshotToolkitOptions = { backend: "memory" }): SnapshotToolkit {
-        return new SnapshotToolkit(options);
-    }
-
-    public register(id: string, participant: SnapshotParticipant): void {
-        this.participants.set(id, participant);
-    }
-
-    public async create(name: string): Promise<SnapshotManifest> {
-        const id = crypto.randomUUID();
-        const state: Record<string, SnapshotState> = {};
-
-        // Snapshot all participants
-        for (const [pId, participant] of this.participants.entries()) {
-            state[pId] = await participant.snapshot();
-        }
-
-        return this.backend.save(id, name, state);
-    }
-
-    public async restore(id: string): Promise<void> {
-        const { state } = await this.backend.load(id);
-
-        // 1. load state & restore (but don't reload yet in case something fails)
-        for (const [pId, pState] of Object.entries(state)) {
-            const participant = this.participants.get(pId);
-            if (!participant) {
-                throw new Error(`Cannot restore state for participant '${pId}' because it is not registered`);
-            }
-            try {
-                await participant.restore(pState);
-            } catch (err: any) {
-                throw new Error(`Failed to restore participant '${pId}': ${err.message}`);
-            }
-        }
-
-        // 2. reload all
-        for (const [pId, _] of Object.entries(state)) {
-            const participant = this.participants.get(pId)!;
-            try {
-                await participant.reload();
-            } catch (err: any) {
-                throw new Error(`Failed to reload participant '${pId}' after restoration: ${err.message}`);
-            }
-        }
-    }
-
-    public async branch(baseId: string, newName: string): Promise<SnapshotManifest> {
-        const newId = crypto.randomUUID();
-        return this.backend.branch(baseId, newId, newName);
-    }
-
-    public async diff(idA: string, idB: string): Promise<Record<string, any>> {
-        const [a, b] = await Promise.all([this.backend.load(idA), this.backend.load(idB)]);
-        
-        const differences: Record<string, any> = {};
-        const allParticipants = new Set([...a.manifest.participants, ...b.manifest.participants]);
-
-        for (const pId of allParticipants) {
-            const hashA = a.manifest.stateHashes[pId];
-            const hashB = b.manifest.stateHashes[pId];
-            if (hashA !== hashB) {
-                differences[pId] = {
-                    a: a.state[pId] || null,
-                    b: b.state[pId] || null
-                };
-            }
-        }
-        return differences;
-    }
-
-    public async compare(idA: string, idB: string): Promise<boolean> {
-        const diff = await this.diff(idA, idB);
-        return Object.keys(diff).length === 0;
-    }
-
-    public async list(): Promise<SnapshotManifest[]> {
-        return this.backend.list();
-    }
-}

package/src/snapshot/serialization.ts

@@ -1,35 +0,0 @@
-import { SnapshotState } from "./types.js";
-
-/**
- * Custom JSON Replacer to safely serialize BigInt values.
- */
-export function snapshotReplacer(key: string, value: any): any {
-    if (typeof value === "bigint") {
-        return { $bigint: value.toString() };
-    }
-    return value;
-}
-
-/**
- * Custom JSON Reviver to safely deserialize BigInt values.
- */
-export function snapshotReviver(key: string, value: any): any {
-    if (value !== null && typeof value === "object" && typeof value.$bigint === "string") {
-        return BigInt(value.$bigint);
-    }
-    return value;
-}
-
-/**
- * Serializes a SnapshotState map to a string safely supporting BigInt.
- */
-export function serializeState(state: Record<string, SnapshotState>): string {
-    return JSON.stringify(state, snapshotReplacer, 2);
-}
-
-/**
- * Deserializes a SnapshotState map from a string safely supporting BigInt.
- */
-export function deserializeState(data: string): Record<string, SnapshotState> {
-    return JSON.parse(data, snapshotReviver);
-}

package/src/snapshot/types.ts

@@ -1,45 +0,0 @@
-export interface SnapshotState {
-    [key: string]: any;
-}
-
-export interface SnapshotParticipant {
-    /** 
-     * Extracts the current internal state of the toolkit/store 
-     */
-    snapshot(): Promise<SnapshotState>;
-
-    /** 
-     * Restores the internal state from the provided snapshot state 
-     */
-    restore(state: SnapshotState): Promise<void>;
-
-    /** 
-     * Reloads any caches, queues, or in-memory representations 
-     * based on the newly restored state 
-     */
-    reload(): Promise<void>;
-}
-
-export interface SnapshotManifest {
-    schema: "hardkas.snapshot.v1";
-    snapshotId: string;
-    name: string;
-    createdAt: number;
-    backend: "memory" | "filesystem";
-    path?: string;
-    participants: string[];
-    stateHashes: Record<string, string>;
-    claims: {
-        containsFullStateInline: boolean;
-        restorableLocalState: boolean;
-        networkStateCaptured: boolean;
-    };
-}
-
-export interface SnapshotBackend {
-    save(id: string, name: string, state: Record<string, SnapshotState>): Promise<SnapshotManifest>;
-    load(id: string): Promise<{ manifest: SnapshotManifest; state: Record<string, SnapshotState> }>;
-    list(): Promise<SnapshotManifest[]>;
-    delete(id: string): Promise<void>;
-    branch(baseId: string, newId: string, newName: string): Promise<SnapshotManifest>;
-}

package/src/stores/invoice-store.ts

@@ -1,53 +0,0 @@
-import { DomainStoreJson } from '@hardkas/query-store';
-
-export interface InvoiceRecord {
-    id: string;
-    merchantId: string;
-    amount: bigint;
-    currency: string;
-    status: 'pending' | 'paid' | 'cancelled';
-    uri: string;
-    createdAt: string;
-    updatedAt: string;
-}
-
-export class InvoiceStoreJson {
-    private store: DomainStoreJson<InvoiceRecord>;
-
-    constructor(options: { filePath: string }) {
-        this.store = new DomainStoreJson<InvoiceRecord>(options);
-    }
-
-    public save(invoice: InvoiceRecord): void {
-        invoice.updatedAt = new Date().toISOString();
-        this.store.save(invoice.id, invoice);
-    }
-
-    public get(id: string): InvoiceRecord | undefined {
-        return this.store.get(id);
-    }
-
-    public list(): InvoiceRecord[] {
-        return this.store.list();
-    }
-
-    public listByMerchant(merchantId: string): InvoiceRecord[] {
-        return this.store.list().filter(i => i.merchantId === merchantId);
-    }
-
-    public listPaid(): InvoiceRecord[] {
-        return this.store.list().filter(i => i.status === 'paid');
-    }
-
-    public stats(merchantId?: string) {
-        let invoices = this.store.list();
-        if (merchantId) {
-            invoices = invoices.filter(i => i.merchantId === merchantId);
-        }
-        
-        return {
-            totalInvoices: invoices.length,
-            paidInvoices: invoices.filter(i => i.status === 'paid').length
-        };
-    }
-}