@hardkas/toolkit 0.11.2-alpha → 0.11.6-alpha

package/src/dag/index.ts

@@ -1,73 +0,0 @@
-import { LocalDagStore } from './store.js';
-import { DAGTopology } from './topology.js';
-import { ConsensusView } from './consensus.js';
-import { DagBlock, DagNeighborhood, DagStatistics } from './types.js';
-
-export * from './types.js';
-
-export class DagApi {
-    private store: LocalDagStore;
-    private topology: DAGTopology;
-    private consensus: ConsensusView;
-
-    constructor() {
-        this.store = new LocalDagStore();
-        this.topology = new DAGTopology(this.store);
-        this.consensus = new ConsensusView(this.store, this.topology);
-    }
-
-    public async ingestBlocks(blocks: DagBlock[]): Promise<void> {
-        this.store.ingest(blocks);
-    }
-
-    public async snapshot(): Promise<DagBlock[]> {
-        return this.store.getAllBlocks();
-    }
-
-    public async restore(blocks: DagBlock[]): Promise<void> {
-        this.store.clear();
-        this.store.ingest(blocks);
-    }
-
-    public async reload(): Promise<void> {
-        this.consensus.clearCache();
-    }
-
-    // Topology
-    public async block(hash: string): Promise<DagBlock> {
-        return this.topology.block(hash);
-    }
-
-    public async parents(hash: string): Promise<DagBlock[]> {
-        return this.topology.parents(hash);
-    }
-
-    public async children(hash: string): Promise<DagBlock[]> {
-        return this.topology.children(hash);
-    }
-
-    public async reachability(fromHash: string, toHash: string): Promise<boolean> {
-        return this.topology.reachability(fromHash, toHash);
-    }
-
-    public async neighborhood(hash: string, opts: { depth?: number } = {}): Promise<DagNeighborhood> {
-        return this.topology.neighborhood(hash, opts);
-    }
-
-    // Consensus
-    public async blueScore(hash: string): Promise<number> {
-        return this.consensus.blueScore(hash);
-    }
-
-    public async confirmations(hash: string): Promise<number> {
-        return this.consensus.confirmations(hash);
-    }
-
-    public async trace(txid: string): Promise<{ txid: string, status: string, foundIn: string[] }> {
-        return this.consensus.trace(txid);
-    }
-
-    public async statistics(): Promise<DagStatistics> {
-        return this.consensus.statistics();
-    }
-}

package/src/dag/store.ts

@@ -1,40 +0,0 @@
-import { DagBlock } from './types.js';
-
-export class LocalDagStore {
-    private blocks = new Map<string, DagBlock>();
-    
-    // Reverse index to avoid O(N) children scans
-    private childrenIndex = new Map<string, Set<string>>();
-
-    public ingest(blocksToIngest: DagBlock[]): void {
-        for (const block of blocksToIngest) {
-            this.blocks.set(block.hash, block);
-
-            // Update children index
-            for (const parent of block.parents) {
-                if (!this.childrenIndex.has(parent)) {
-                    this.childrenIndex.set(parent, new Set());
-                }
-                this.childrenIndex.get(parent)!.add(block.hash);
-            }
-        }
-    }
-
-    public getBlock(hash: string): DagBlock | undefined {
-        return this.blocks.get(hash);
-    }
-
-    public getChildrenHashes(hash: string): string[] {
-        const children = this.childrenIndex.get(hash);
-        return children ? Array.from(children) : [];
-    }
-
-    public getAllBlocks(): DagBlock[] {
-        return Array.from(this.blocks.values());
-    }
-
-    public clear(): void {
-        this.blocks.clear();
-        this.childrenIndex.clear();
-    }
-}

package/src/dag/topology.ts

@@ -1,108 +0,0 @@
-import { LocalDagStore } from './store.js';
-import { DagBlock, DagNeighborhood } from './types.js';
-
-export class DAGTopology {
-    constructor(private store: LocalDagStore) {}
-
-    public async block(hash: string): Promise<DagBlock> {
-        const b = this.store.getBlock(hash);
-        if (!b) throw new Error(`Block not found: ${hash}`);
-        return b;
-    }
-
-    public async parents(hash: string): Promise<DagBlock[]> {
-        const b = await this.block(hash);
-        return b.parents.map(p => this.store.getBlock(p)).filter(Boolean) as DagBlock[];
-    }
-
-    public async children(hash: string): Promise<DagBlock[]> {
-        // Fast lookup via index instead of O(N) scan
-        const childrenHashes = this.store.getChildrenHashes(hash);
-        return childrenHashes.map(c => this.store.getBlock(c)).filter(Boolean) as DagBlock[];
-    }
-
-    public async reachability(fromHash: string, toHash: string): Promise<boolean> {
-        if (fromHash === toHash) return true;
-        
-        const toBlock = this.store.getBlock(toHash);
-        if (!toBlock) return false;
-
-        // DFS for reachability
-        const visited = new Set<string>();
-        const stack = [toHash];
-
-        while (stack.length > 0) {
-            const current = stack.pop()!;
-            if (current === fromHash) return true;
-            if (visited.has(current)) continue;
-            visited.add(current);
-
-            const b = this.store.getBlock(current);
-            if (b) {
-                for (const p of b.parents) {
-                    stack.push(p);
-                }
-            }
-        }
-
-        return false;
-    }
-
-    public async neighborhood(hash: string, opts: { depth?: number } = {}): Promise<DagNeighborhood> {
-        const maxDepth = opts.depth || 1;
-        const baseBlock = await this.block(hash);
-
-        const ancestors = new Map<string, DagBlock>();
-        const descendants = new Map<string, DagBlock>();
-
-        // BFS for Ancestors
-        let aQueue = [{ hash, currentDepth: 0 }];
-        let aVisited = new Set<string>([hash]);
-        
-        while (aQueue.length > 0) {
-            const { hash: curr, currentDepth } = aQueue.shift()!;
-            if (currentDepth >= maxDepth) continue;
-
-            const b = this.store.getBlock(curr);
-            if (!b) continue;
-
-            for (const p of b.parents) {
-                if (!aVisited.has(p)) {
-                    aVisited.add(p);
-                    const parentBlock = this.store.getBlock(p);
-                    if (parentBlock) {
-                        ancestors.set(p, parentBlock);
-                        aQueue.push({ hash: p, currentDepth: currentDepth + 1 });
-                    }
-                }
-            }
-        }
-
-        // BFS for Descendants
-        let dQueue = [{ hash, currentDepth: 0 }];
-        let dVisited = new Set<string>([hash]);
-
-        while (dQueue.length > 0) {
-            const { hash: curr, currentDepth } = dQueue.shift()!;
-            if (currentDepth >= maxDepth) continue;
-
-            const children = this.store.getChildrenHashes(curr);
-            for (const c of children) {
-                if (!dVisited.has(c)) {
-                    dVisited.add(c);
-                    const childBlock = this.store.getBlock(c);
-                    if (childBlock) {
-                        descendants.set(c, childBlock);
-                        dQueue.push({ hash: c, currentDepth: currentDepth + 1 });
-                    }
-                }
-            }
-        }
-
-        return {
-            hash,
-            ancestors: Array.from(ancestors.values()),
-            descendants: Array.from(descendants.values())
-        };
-    }
-}

package/src/dag/types.ts

@@ -1,20 +0,0 @@
-export interface DagBlock {
-    hash: string;
-    parents: string[];
-    blueScore?: number;
-    transactions?: { id: string, payload?: any }[];
-    // Other fields can be appended as needed by the consumer
-    [key: string]: any;
-}
-
-export interface DagNeighborhood {
-    hash: string;
-    ancestors: DagBlock[];
-    descendants: DagBlock[];
-}
-
-export interface DagStatistics {
-    totalBlocks: number;
-    totalTips: number;
-    highestBlueScore: number;
-}

package/src/index.ts

@@ -1,10 +0,0 @@
-export * from './wallet.js';
-export * from './payment.js';
-export * from './stores/invoice-store.js';
-export * from './indexer.js';
-export * from './jobs.js';
-export * from './utxos.js';
-export * from './dag/index.js';
-export * from './snapshot/index.js';
-export * from './silver/index.js';
-export * from './silver/types.js';

package/src/indexer.ts

@@ -1,134 +0,0 @@
-import { EventSubscriber, BackendPlugin } from '@hardkas/core';
-import { ProjectionStoreJson } from '@hardkas/query-store';
-import { ArtifactIndexStoreJson } from '@hardkas/artifacts';
-import { DagApi } from './dag/index.js';
-import { SnapshotParticipant } from './snapshot/types.js';
-
-export interface IndexerBackendPlugin extends BackendPlugin {
-    balance?(address: string): Promise<bigint>;
-    history?(address: string): Promise<unknown[]>;
-    utxos?(address: string): Promise<unknown[]>;
-}
-
-export interface IndexerToolkitOptions {
-    dataDir?: string;
-    backend?: IndexerBackendPlugin;
-}
-
-export type WatchHandler = (evt: any) => Promise<void> | void;
-
-export class IndexerToolkit implements SnapshotParticipant {
-    private subscriber: EventSubscriber;
-    private projection?: ProjectionStoreJson;
-    private artifactIndex?: ArtifactIndexStoreJson;
-    public readonly dag: DagApi;
-    public readonly backend?: IndexerBackendPlugin | undefined;
-
-    private constructor(private readonly options: IndexerToolkitOptions) {
-        this.subscriber = new EventSubscriber();
-        this.backend = options.backend;
-        
-        if (!this.backend || !this.backend.capabilities.externalState) {
-            this.projection = new ProjectionStoreJson({ 
-                dirPath: options.dataDir ? `${options.dataDir}/projections` : '.hardkas/indexer/projections',
-                namespace: 'indexer'
-            });
-            this.artifactIndex = new ArtifactIndexStoreJson({
-                filePath: options.dataDir ? `${options.dataDir}/artifacts.json` : '.hardkas/indexer/artifacts.json'
-            });
-        }
-        
-        this.dag = new DagApi();
-    }
-
-    public static open(options: IndexerToolkitOptions = {}): IndexerToolkit {
-        return new IndexerToolkit(options);
-    }
-
-    public async connect(): Promise<void> {
-        if (this.backend?.connect) {
-            await this.backend.connect();
-        }
-    }
-
-    public async watch(address: string | string[], handler?: WatchHandler): Promise<void> {
-        const addresses = Array.isArray(address) ? address : [address];
-        // Polling wrapper as per V1 rules.
-        this.subscriber.subscribe({
-            source: {}, // mock source for facade
-            type: "payment",
-            intervalMs: 1000,
-            watchedAddresses: addresses,
-            handler: async (evt) => {
-                // Internally updates projections if address is involved
-                if (handler) {
-                    await handler(evt);
-                }
-            }
-        });
-    }
-
-    public async balance(address: string): Promise<bigint> {
-        if (this.backend?.balance) {
-            return this.backend.balance(address);
-        }
-        const balances = this.projection?.get('balances') || {};
-        return BigInt(balances[address] || 0);
-    }
-
-    public async history(address: string): Promise<any[]> {
-        if (this.backend?.history) {
-            return this.backend.history(address);
-        }
-        const history = this.projection?.get('history') || {};
-        return history[address] || [];
-    }
-
-    public async findReceipts(opts: { tags: string[] }): Promise<any[]> {
-        if (!this.artifactIndex) return [];
-        return this.artifactIndex.find(opts);
-    }
-
-    public async ingestArtifact(artifact: any): Promise<void> {
-        if (!this.artifactIndex) return;
-        this.artifactIndex.index({
-            hash: artifact.id || 'mock_hash',
-            schema: artifact.schema || 'unknown.v1',
-            timestamp: new Date().toISOString(),
-            filePath: `/mock/path/${artifact.id}.json`,
-            tags: artifact.tags || []
-        });
-    }
-
-    public async snapshot(): Promise<any> {
-        if (this.backend && !this.backend.capabilities.snapshots && this.backend.capabilities.externalState) {
-            return {
-                backend: this.backend.name,
-                externalState: true,
-                snapshots: false,
-                dag: await this.dag.snapshot()
-            };
-        }
-        return {
-            projection: this.projection?.getAll() || {},
-            artifactIndex: this.artifactIndex?.getAll() || [],
-            dag: await this.dag.snapshot()
-        };
-    }
-
-    public async restore(state: any): Promise<void> {
-        if (state.externalState) {
-            // Cannot restore local state over an external backend. Just restore DAG.
-            if (state.dag) await this.dag.restore(state.dag);
-            return;
-        }
-        if (state.projection && this.projection) this.projection.setAll(state.projection);
-        if (state.artifactIndex && this.artifactIndex) this.artifactIndex.setAll(state.artifactIndex);
-        if (state.dag) await this.dag.restore(state.dag);
-    }
-
-    public async reload(): Promise<void> {
-        await this.dag.reload();
-        // Projection and artifactIndex read synchronously from memory in this version
-    }
-}

package/src/jobs.ts

@@ -1,63 +0,0 @@
-import { JobRunner, JobStoreJson, JobHandler, JobRecord, JobStore } from '@hardkas/jobs';
-import { SnapshotParticipant, SnapshotState } from './snapshot/types.js';
-
-export interface JobsToolkitOptions {
-    storePath?: string;
-    storage?: any; // e.g. SqliteStorage
-}
-
-export class JobsToolkit implements SnapshotParticipant {
-    private runner: JobRunner;
-    private store: JobStore;
-
-    private constructor(options: JobsToolkitOptions) {
-        if (options.storage) {
-            this.store = options.storage.createJobStore();
-        } else {
-            this.store = new JobStoreJson({ filePath: options.storePath || '.hardkas-data/jobs.json' });
-        }
-        this.runner = new JobRunner({ store: this.store });
-    }
-
-    public static open(options: JobsToolkitOptions = {}): JobsToolkit {
-        return new JobsToolkit(options);
-    }
-
-    public registerHandler(type: string, handler: JobHandler): void {
-        this.runner.registerHandler(type, handler);
-    }
-
-    public async enqueue(type: string, args?: any): Promise<string> {
-        return this.runner.enqueue(type, args);
-    }
-
-    public async resumePendingJobs(): Promise<void> {
-        return this.runner.resumePendingJobs();
-    }
-
-    public async getJob(id: string): Promise<JobRecord | undefined> {
-        return this.runner.getJob(id);
-    }
-
-    public async snapshot(): Promise<SnapshotState> {
-        return this.store.getAll();
-    }
-
-    public resetAll() {
-        // Not all stores support this, but if we really need it, we should add clear() to JobStore.
-        // For now, it's a test utility.
-        if ('setAll' in this.store) {
-            (this.store as any).setAll({});
-        }
-    }
-
-    public async restore(state: SnapshotState): Promise<void> {
-        this.store.setAll(state as Record<string, JobRecord>);
-    }
-
-    public async reload(): Promise<void> {
-        // Runner reads from store on each operation natively in current design,
-        // but if it had internal queues/caches, we'd clear them here.
-        // E.g., this.runner.clearCache();
-    }
-}

package/src/payment.ts

@@ -1,100 +0,0 @@
-import { buildKaspaUri } from '@hardkas/tx-builder';
-import { EvidenceBatchExporter } from '@hardkas/artifacts';
-import { InvoiceStoreJson, InvoiceRecord, InvoiceStore } from './stores/invoice-store.js';
-
-export interface PaymentToolkitOptions {
-    storePath?: string;
-    storage?: any;
-}
-
-export class PaymentToolkit {
-    private store: InvoiceStore;
-
-    private constructor(
-        public readonly merchantId: string,
-        private readonly options: PaymentToolkitOptions
-    ) {
-        if (options.storage) {
-            this.store = options.storage.createInvoiceStore();
-        } else {
-            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; amountSompi?: bigint; currency?: string }): Promise<InvoiceRecord> {
-        if (opts.amount === undefined && opts.amountSompi === undefined) {
-            throw new Error("Must provide either amount or amountSompi");
-        }
-
-        const sompi = opts.amountSompi ?? (opts.amount! * 100_000_000n);
-        const kas = opts.amount ?? (opts.amountSompi! / 100_000_000n);
-        const curr = opts.currency ?? 'KAS';
-
-        const id = `inv_${Date.now()}`;
-        const result = buildKaspaUri({
-            address: `kaspa:${this.merchantId}`,
-            amountSompi: sompi,
-            message: `Invoice ${id}`
-        });
-
-        const invoice: InvoiceRecord = {
-            id,
-            merchantId: this.merchantId,
-            amount: kas,
-            currency: curr,
-            status: 'pending',
-            uri: result.uri,
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString()
-        };
-
-        await this.store.save(invoice);
-        return invoice;
-    }
-
-    public async getInvoice(id: string): Promise<InvoiceRecord | undefined> {
-        return await this.store.get(id);
-    }
-
-    public async listInvoices(): Promise<InvoiceRecord[]> {
-        return await this.store.listByMerchant(this.merchantId);
-    }
-
-    public async stats(): Promise<{ totalInvoices: number; paidInvoices: number }> {
-        return await this.store.stats(this.merchantId);
-    }
-
-    public async check(invoiceId: string): Promise<string> {
-        const inv = await this.store.get(invoiceId);
-        return inv ? inv.status : 'not_found';
-    }
-
-    public async receipt(invoiceId: string): Promise<any> {
-        const inv = await this.store.get(invoiceId);
-        if (!inv) throw new Error("Invoice not found");
-        if (inv.status !== "paid") throw new Error("Invoice is not paid");
-
-        return {
-            schema: "paymentReceipt.v1",
-            invoiceId,
-            merchantId: this.merchantId,
-            status: "paid",
-            timestamp: new Date().toISOString(),
-            amount: inv.amount,
-            currency: inv.currency
-        };
-    }
-    
-    // For lab testing/simulation manually paying an invoice
-    public async simulatePay(invoiceId: string): Promise<void> {
-        const inv = await this.store.get(invoiceId);
-        if (inv) {
-            inv.status = 'paid';
-            await 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`
-};