@hardkas/sdk 0.8.14-alpha → 0.8.16-alpha

package/dist/index.js

@@ -201,6 +201,16 @@ var HardkasTx = class {
       feeRateSompiPerMass: options.feeRate ?? 1n
     });
     const isSimulated = activeNetwork === "simulated" || this.sdk.config.config.networks?.[activeNetwork]?.kind === "simulated";
+    let resolvedAssumptionLevel = options.assumption;
+    if (!resolvedAssumptionLevel) {
+      if (isSimulated) {
+        resolvedAssumptionLevel = "local-simulated";
+      } else if (activeNetwork === "simnet") {
+        resolvedAssumptionLevel = "local-rpc";
+      } else {
+        resolvedAssumptionLevel = activeNetwork;
+      }
+    }
     const basePlan = createTxPlanArtifact({
       networkId: activeNetwork,
       mode: isSimulated ? "simulated" : "real",
@@ -215,7 +225,11 @@ var HardkasTx = class {
       },
       amountSompi,
       plan: builderPlan,
-      ctx: options.workflowId ? { ...systemRuntimeContext, workflowId: options.workflowId } : systemRuntimeContext
+      ctx: {
+        ...systemRuntimeContext,
+        ...options.workflowId ? { workflowId: options.workflowId } : {},
+        assumptionLevel: resolvedAssumptionLevel
+      }
     });
     if (options.policy || options.policies) {
       const inputPolicies = options.policies || (options.policy ? [options.policy] : []);
@@ -254,11 +268,12 @@ var HardkasTx = class {
     basePlan.contentHash = newHash;
     if (basePlan.lineage) {
       basePlan.lineage.lineageId = newHash;
-      basePlan.lineage.parentArtifactId = newHash;
+      basePlan.lineage.parentArtifactId = "";
       basePlan.lineage.rootArtifactId = newHash;
       const finalHash = calculateContentHash2(basePlan, CURRENT_HASH_VERSION2);
       basePlan.contentHash = finalHash;
       basePlan.lineage.artifactId = finalHash;
+      basePlan.planId = `plan-${finalHash.slice(0, 16)}`;
     }
     this.sdk.artifacts.cacheArtifact(basePlan);
     if (basePlan.policyRefs && basePlan.policyRefs.length > 0) {
@@ -509,7 +524,14 @@ var HardkasTx = class {
    */
   async simulate(target, options = {}) {
     if (typeof target === "object" && target !== null && target.contentHash) {
-      await this.sdk.artifacts.verify(target, { throwOnInvalid: true, strict: true, enforceMetadata: false });
+      try {
+        await this.sdk.artifacts.verify(target, { throwOnInvalid: true, strict: true, enforceMetadata: false });
+      } catch (e) {
+        if (e.message.includes("PARENT_MISSING")) {
+          throw new Error("parent_plan_unresolved: Missing context plan for simulation.");
+        }
+        throw e;
+      }
     }
     const persist = options.persist ?? true;
     if (typeof target === "object" && target !== null) {
@@ -628,6 +650,12 @@ var HardkasTx = class {
       confirmedAt: simResult.receipt.createdAt,
       rpcUrl: "simulated://local",
       tracePath,
+      ...planArtifact.workflowId ? { workflowId: planArtifact.workflowId } : {},
+      ...planArtifact.assumptionLevel ? { assumptionLevel: planArtifact.assumptionLevel } : {},
+      ...planArtifact.policyRefs ? { policyRefs: planArtifact.policyRefs } : {},
+      ...planArtifact.networkProfileRef ? { networkProfileRef: planArtifact.networkProfileRef } : {},
+      ...planArtifact.assumptionRef ? { assumptionRef: planArtifact.assumptionRef } : {},
+      sourceSignedId: signedId !== "unknown" ? signedId : void 0,
       lineage: {
         artifactId: "",
         // To be computed
@@ -700,7 +728,14 @@ var HardkasTx = class {
    */
   async send(signedArtifact, urlOrOptions) {
     if (typeof signedArtifact === "object" && signedArtifact !== null && signedArtifact.contentHash) {
-      await this.sdk.artifacts.verify(signedArtifact, { throwOnInvalid: true, strict: true, enforceMetadata: false });
+      try {
+        await this.sdk.artifacts.verify(signedArtifact, { throwOnInvalid: true, strict: true, enforceMetadata: false });
+      } catch (e) {
+        if (e.message.includes("PARENT_MISSING")) {
+          throw new Error("parent_plan_unresolved: Missing context plan for simulation.");
+        }
+        throw e;
+      }
     }
     const verification = verifySignedTxSemantics(signedArtifact);
     if (!verification.ok) {
@@ -783,6 +818,11 @@ var HardkasTx = class {
       submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
       ...url ? { rpcUrl: url } : {},
       ...signedArtifact.workflowId ? { workflowId: signedArtifact.workflowId } : {},
+      ...signedArtifact.assumptionLevel ? { assumptionLevel: signedArtifact.assumptionLevel } : {},
+      ...signedArtifact.policyRefs ? { policyRefs: signedArtifact.policyRefs } : {},
+      ...signedArtifact.networkProfileRef ? { networkProfileRef: signedArtifact.networkProfileRef } : {},
+      ...signedArtifact.assumptionRef ? { assumptionRef: signedArtifact.assumptionRef } : {},
+      sourceSignedId: signedArtifact.contentHash || signedArtifact.signedId,
       tracePath: void 0,
       lineage: createLineageTransition(signedArtifact, "hardkas.txReceipt")
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardkas/sdk",
-  "version": "0.8.14-alpha",
+  "version": "0.8.16-alpha",
   "type": "module",
   "files": [
     "dist",
@@ -23,22 +23,23 @@
     }
   },
   "dependencies": {
-    "@hardkas/accounts": "0.8.14-alpha",
-    "@hardkas/artifacts": "0.8.14-alpha",
-    "@hardkas/config": "0.8.14-alpha",
-    "@hardkas/l2": "0.8.14-alpha",
-    "@hardkas/kaspa-rpc": "0.8.14-alpha",
-    "@hardkas/localnet": "0.8.14-alpha",
-    "@hardkas/core": "0.8.14-alpha",
-    "@hardkas/tx-builder": "0.8.14-alpha",
-    "@hardkas/wallet-adapter": "0.8.14-alpha",
-    "@hardkas/query": "0.8.14-alpha",
-    "@hardkas/simulator": "0.8.14-alpha",
-    "@hardkas/query-store": "0.8.14-alpha"
+    "@kaspa/core-lib": "^1.6.5",
+    "@hardkas/accounts": "0.8.16-alpha",
+    "@hardkas/config": "0.8.16-alpha",
+    "@hardkas/artifacts": "0.8.16-alpha",
+    "@hardkas/core": "0.8.16-alpha",
+    "@hardkas/kaspa-rpc": "0.8.16-alpha",
+    "@hardkas/l2": "0.8.16-alpha",
+    "@hardkas/localnet": "0.8.16-alpha",
+    "@hardkas/query-store": "0.8.16-alpha",
+    "@hardkas/query": "0.8.16-alpha",
+    "@hardkas/tx-builder": "0.8.16-alpha",
+    "@hardkas/simulator": "0.8.16-alpha",
+    "@hardkas/wallet-adapter": "0.8.16-alpha"
   },
   "devDependencies": {
-    "tsup": "^8.3.5",
     "@types/node": "^20.12.7",
+    "tsup": "^8.3.5",
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   },

package/dist/client.d.ts

@@ -1,84 +0,0 @@
-interface HardkasClientOptions {
-    baseUrl?: string;
-    network?: string;
-}
-interface ClientEnvelope<T> {
-    ok: boolean;
-    data?: T;
-    error?: {
-        code: string;
-        message: string;
-    };
-    warnings: string[];
-    meta: {
-        workspace: string;
-        network: string;
-        mode?: string;
-    };
-}
-declare function createHardkasClient(options?: HardkasClientOptions): {
-    accounts: {
-        list: () => Promise<ClientEnvelope<any[]>>;
-    };
-    tx: {
-        plan: (params: {
-            from: string;
-            to: string;
-            amountSompi: string;
-            feeRate?: string;
-        }) => Promise<ClientEnvelope<any>>;
-        sign: (params: {
-            planId: string;
-            account: string;
-        }) => Promise<ClientEnvelope<any>>;
-        send: (params: {
-            signedTxId?: string;
-            from?: string;
-            to?: string;
-            amountSompi?: string;
-            feeRate?: string;
-            allowDevAutoSign?: boolean;
-        }) => Promise<ClientEnvelope<any>>;
-        receipt: (id: string) => Promise<ClientEnvelope<any>>;
-    };
-    artifacts: {
-        explain: (id: string) => Promise<ClientEnvelope<any>>;
-        replay: (id: string) => Promise<ClientEnvelope<any>>;
-        watch: (callback: (artifact: any) => void, options?: {
-            type?: string;
-            lineage?: boolean;
-            replay?: boolean;
-            transport?: "sse" | "poll";
-            intervalMs?: number;
-        }) => () => void;
-    };
-    workflow: {
-        transfer: (params: {
-            from: string;
-            to: string;
-            amountSompi: string;
-            feeRate?: string;
-            allowDevAutoSign?: boolean;
-        }) => Promise<ClientEnvelope<any>>;
-    };
-    localnet: {
-        status: () => Promise<ClientEnvelope<any>>;
-    };
-    dev: {
-        status: () => Promise<ClientEnvelope<any>>;
-    };
-    session: {
-        start: () => Promise<ClientEnvelope<any>>;
-        snapshot: () => Promise<ClientEnvelope<any>>;
-        replay: (options?: {
-            untilArtifact?: string;
-            strict?: boolean;
-        }) => Promise<ClientEnvelope<any>>;
-        diffReplay: (artifactId: string) => Promise<ClientEnvelope<any>>;
-        timeTravel: (artifactId: string) => Promise<ClientEnvelope<any>>;
-        export: () => Promise<ClientEnvelope<any>>;
-        import: (data: any, force?: boolean) => Promise<ClientEnvelope<any>>;
-    };
-};
-
-export { type ClientEnvelope, type HardkasClientOptions, createHardkasClient };

package/dist/index.d.ts

@@ -1,431 +0,0 @@
-import * as _hardkas_config from '@hardkas/config';
-import { LoadedHardkasConfig } from '@hardkas/config';
-export { defineHardkasConfig } from '@hardkas/config';
-import { TxPlanArtifact, SignedTxArtifact, TxReceiptArtifact, HardkasArtifactBase, WorkflowArtifact, ExternalHardkasSigner } from '@hardkas/artifacts';
-export { ARTIFACT_SCHEMAS, HARDKAS_VERSION, SignedTxArtifact, TxPlanArtifact, TxReceiptArtifact, TxTraceArtifact, createTxPlanArtifact, writeArtifact } from '@hardkas/artifacts';
-import { KaspaRpcClient } from '@hardkas/kaspa-rpc';
-import { EventEnvelope, NetworkId } from '@hardkas/core';
-export { ArtifactId, HardkasError, KaspaAddress, LineageId, NetworkId, SOMPI_PER_KAS, TxId, formatSompi, parseKasToSompi } from '@hardkas/core';
-import { HardkasAccount } from '@hardkas/accounts';
-export { signTxPlanArtifact } from '@hardkas/accounts';
-import { L2NetworkProfile } from '@hardkas/l2';
-export { buildPaymentPlan } from '@hardkas/tx-builder';
-export { ClientEnvelope, HardkasClientOptions, createHardkasClient } from './client.js';
-
-/**
- * HardKAS Accounts Module
- * @alpha
- */
-declare class HardkasAccounts {
-    private sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Resolves an account by name or address.
-     */
-    resolve(nameOrAddress: string): Promise<HardkasAccount>;
-    /**
-     * Fetches the balance for an account.
-     */
-    getBalance(accountNameOrAddress: string): Promise<{
-        sompi: bigint;
-        formatted: string;
-    }>;
-    /**
-     * Alias for getBalance.
-     */
-    balance(accountNameOrAddress: string): Promise<{
-        sompi: bigint;
-        formatted: string;
-    }>;
-    /**
-     * Lists all configured account names.
-     */
-    list(): Promise<string[]>;
-    /**
-     * Funds an account from another account (defaults to 'default' account).
-     */
-    fund(accountNameOrAddress: string, options?: {
-        from?: string;
-        amount?: string | bigint;
-    }): Promise<any>;
-}
-
-/**
- * HardKAS Transaction Module
- * @alpha
- */
-declare class HardkasTx {
-    private sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Plans a transaction.
-     */
-    plan(options: {
-        from: string | HardkasAccount;
-        to: string | HardkasAccount;
-        amount: string | number | bigint;
-        feeRate?: bigint;
-        workflowId?: string;
-        policy?: string;
-        networkProfile?: string;
-        assumption?: string;
-    }): Promise<TxPlanArtifact>;
-    /**
-     * Signs a transaction plan.
-     */
-    sign(plan: TxPlanArtifact | SignedTxArtifact, account?: HardkasAccount | string, options?: {
-        append?: boolean;
-        threshold?: number;
-        requiredSigners?: string[];
-    }): Promise<SignedTxArtifact>;
-    /**
-     * Simulates a transaction on the local state without broadcasting to a real Kaspa node.
-     * Modifies the local deterministic state and outputs receipt/trace artifacts.
-     */
-    simulate(target: string | Partial<TxPlanArtifact> | SignedTxArtifact, options?: {
-        persist?: boolean;
-    }): Promise<{
-        receipt: TxReceiptArtifact;
-        receiptPath?: string;
-        tracePath?: string;
-    }>;
-    /**
-     * Sends a signed transaction to the real RPC network.
-     */
-    send(signedArtifact: SignedTxArtifact, urlOrOptions?: string | {
-        persist?: boolean;
-    }): Promise<{
-        receipt: TxReceiptArtifact;
-        receiptPath?: string;
-        artifactId?: string;
-        mode?: string;
-        simulated?: boolean;
-        submitted?: boolean;
-        txId?: string;
-    }>;
-    /**
-     * Explicitly appends a signature to a partially signed transaction.
-     */
-    appendSignature(plan: SignedTxArtifact, account?: HardkasAccount | string): Promise<SignedTxArtifact>;
-    /**
-     * Fetches the current status of a transaction by ID.
-     */
-    status(txId: string): Promise<any>;
-}
-
-/**
- * HardKAS L2 Module
- * @alpha
- */
-declare class HardkasL2 {
-    /**
-     * Lists all available L2 network profiles.
-     */
-    listProfiles(): readonly L2NetworkProfile[];
-    /**
-     * Gets a specific L2 network profile by name.
-     */
-    getProfile(name: string): L2NetworkProfile | null;
-}
-
-/**
- * HardKAS Operational Query Module
- *
- * Note: readEvents, correlate, and correlation types were removed from
- * @hardkas/query. These will be re-implemented when the query API stabilizes.
- * @alpha
- */
-declare class HardkasQuery {
-    private sdk;
-    private _engine;
-    constructor(sdk: Hardkas);
-    /**
-     * Internal lazy-loaded query engine.
-     */
-    private getEngine;
-    /**
-     * Synchronizes the query store with the filesystem artifacts.
-     */
-    sync(options?: {
-        force?: boolean;
-    }): Promise<any>;
-    /**
-     * Fetches events from the query store.
-     */
-    events(filter?: {
-        domain?: string;
-        kind?: string;
-        correlationId?: string;
-        artifactId?: string;
-    }): Promise<readonly EventEnvelope[]>;
-}
-
-/**
- * HardKAS Localnet Simulation Module
- */
-declare class HardkasLocalnet {
-    private sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Status check for the localnet simulation.
-     */
-    isAlive(): Promise<boolean>;
-    /**
-     * Future: control localnet process/container from here.
-     */
-    start(): Promise<void>;
-    /**
-     * Resets the localnet state (simulated or node).
-     */
-    reset(): Promise<void>;
-}
-
-interface ReplayVerifyOptions {
-    path?: string;
-    workflowId?: string;
-}
-interface ReplayVerifyResult {
-    passed: boolean;
-    artifactsScanned: number;
-    lineage: "valid" | "invalid";
-    determinism: "verified" | "failed";
-    contamination: "clean" | "contaminated";
-    report: any;
-    error?: string;
-}
-declare class HardkasReplay {
-    private sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Verifies the deterministic artifact lineage of a transaction replay
-     * against the mathematically reconstructed localnet state.
-     */
-    verify(targetOrOptions?: string | {
-        schema?: string;
-        artifactId?: string;
-    } | ReplayVerifyOptions, options?: ReplayVerifyOptions): Promise<ReplayVerifyResult>;
-}
-
-/**
- * HardKAS Lineage Module
- * @alpha
- */
-declare class HardkasLineage {
-    private sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Traces the lineage of an artifact, identifying ancestors and descendants.
-     */
-    trace(target: string | {
-        artifactId?: string;
-        contentHash?: string;
-    }, options?: {
-        direction?: "ancestors" | "descendants";
-    }): Promise<any>;
-}
-
-/**
- * Deterministic Workspace Abstraction.
- * Encapsulates all filesystem boundary interactions and isolates paths
- * from the global process.cwd(), ensuring agent/script replayability.
- */
-declare class HardkasWorkspace {
-    readonly root: string;
-    constructor(cwd: string);
-    get hardkasDir(): string;
-    get artifactsDir(): string;
-    get localnetStatePath(): string;
-    get keystoreDir(): string;
-    /**
-     * Safely resolves a path relative to the workspace root.
-     */
-    resolvePath(...segments: string[]): string;
-    /**
-     * Safely builds a relative path from the workspace root to the target.
-     */
-    relativeFromRoot(absolutePath: string): string;
-    /**
-     * Ensures the core .hardkas directory exists.
-     */
-    ensureHardkasDir(): void;
-}
-
-interface WriteArtifactOptions {
-    /**
-     * Explicitly override the canonical artifacts directory.
-     * By default, it writes to sdk.workspace.artifactsDir.
-     */
-    outputDir?: string;
-    /**
-     * Explicitly override the default filename.
-     * By default, it generates `${schema}-${contentHash}.json`
-     */
-    fileName?: string;
-    /**
-     * If true, verifies integrity and schema but does not touch the filesystem.
-     * Useful for Agent planning or previews.
-     */
-    dryRun?: boolean;
-    /** Telemetry for Event Sourcing */
-    workflowId?: string;
-    correlationId?: string;
-    networkId?: string;
-}
-interface WriteArtifactResult {
-    absolutePath?: string;
-    dryRun: boolean;
-    contentHash: string;
-}
-/**
- * Deterministic Artifact I/O boundary.
- */
-declare class HardkasArtifactsManager {
-    private workspace;
-    private cache;
-    constructor(workspace: HardkasWorkspace);
-    /**
-     * Caches an in-memory artifact.
-     */
-    cacheArtifact(artifact: any): void;
-    /**
-     * Writes a valid artifact to disk (canonical or custom path).
-     */
-    write(artifact: HardkasArtifactBase, options?: WriteArtifactOptions): Promise<WriteArtifactResult>;
-    /**
-     * Retrieves an artifact from the in-memory cache.
-     */
-    getCached(id: string): any;
-    /**
-     * Reads an artifact by path or ID/hash from the workspace.
-     */
-    read(id: string, options?: {
-        expectedSchema?: string;
-    }): Promise<any>;
-    /**
-     * Alias for read().
-     */
-    get(id: string, options?: {
-        expectedSchema?: string;
-    }): Promise<any>;
-    /**
-     * Lists all artifacts in the workspace.
-     */
-    list(): Promise<any[]>;
-    /**
-     * Cryptographically verifies the determinism and integrity of an artifact.
-     * Throws an error with details if corruption or mismatch is found.
-     */
-    verify(target: any, options?: {
-        throwOnInvalid?: boolean;
-        strict?: boolean;
-        enforceMetadata?: boolean;
-    }): Promise<any>;
-    /**
-     * Migrates a legacy artifact to v4 using a migration receipt.
-     */
-    migrate(target: any, migrationId: string): Promise<{
-        migrated: any;
-        receipt: any;
-    }>;
-}
-
-interface WorkflowRunOptions {
-    steps: Array<{
-        type: string;
-        [key: string]: any;
-    }>;
-    dryRun?: boolean;
-}
-declare class HardkasWorkflow {
-    private readonly sdk;
-    constructor(sdk: Hardkas);
-    /**
-     * Executes a sequence of declarative steps and returns a definitive WorkflowArtifact.
-     */
-    run(options: WorkflowRunOptions): Promise<WorkflowArtifact>;
-}
-
-interface TaskArgs {
-    [key: string]: string | boolean | undefined;
-}
-interface TaskContext {
-    hardkas: Hardkas;
-    args: TaskArgs;
-}
-type TaskAction = (ctx: TaskContext) => Promise<void>;
-/**
- * Defines a new HardKAS task.
- * Used in hardkas.config.ts to extend CLI functionality.
- */
-declare const defineTask: {
-    (name: string, action: TaskAction): void;
-    (name: string, description: string, action: TaskAction): void;
-};
-
-interface HardkasOptions {
-    cwd?: string;
-    configPath?: string;
-    mode?: "developer" | "agent";
-    network?: string;
-    autoBootstrap?: boolean;
-    signer?: ExternalHardkasSigner;
-    logger?: {
-        info: (msg: string) => void;
-        warn: (msg: string) => void;
-        error: (msg: string) => void;
-        debug: (msg: string) => void;
-        [key: string]: any;
-    };
-    policy?: {
-        allowNetwork?: boolean;
-        allowMainnet?: boolean;
-        allowExternalWallet?: boolean;
-        requireDryRun?: boolean;
-    };
-}
-/**
- * HardKAS SDK - Main Entry Point
- *
- * Provides a high-level facade for interacting with the Kaspa ecosystem.
- * Acts as a DI container and coordinator.
- */
-declare class Hardkas {
-    readonly config: LoadedHardkasConfig;
-    readonly workspace: HardkasWorkspace;
-    readonly artifacts: HardkasArtifactsManager;
-    readonly accounts: HardkasAccounts;
-    readonly tx: HardkasTx;
-    readonly l2: HardkasL2;
-    readonly query: HardkasQuery;
-    readonly localnet: HardkasLocalnet;
-    readonly replay: HardkasReplay;
-    readonly lineage: HardkasLineage;
-    readonly workflow: HardkasWorkflow;
-    readonly signer?: ExternalHardkasSigner | undefined;
-    readonly mode: "developer" | "agent";
-    readonly policy: Required<NonNullable<HardkasOptions["policy"]>>;
-    readonly rpc: KaspaRpcClient;
-    private constructor();
-    private resolveRpcUrl;
-    /**
-     * Opens a HardKAS project in the given directory.
-     */
-    static open(dirOrOptions?: string | HardkasOptions): Promise<Hardkas>;
-    /**
-     * Alias for open(). Used in most examples.
-     */
-    static create(dirOrOptions?: string | HardkasOptions): Promise<Hardkas>;
-    /**
-     * Current active network name.
-     */
-    get network(): NetworkId;
-    get sdkConfig(): _hardkas_config.HardkasConfig;
-    get cwd(): string;
-    /**
-     * Validates an action against the active security policy.
-     * Throws HardkasError if the policy is violated.
-     */
-    enforcePolicy(action: "network" | "mainnet" | "external-wallet" | "mutation", context?: string): void;
-}
-
-export { Hardkas, HardkasAccounts, HardkasArtifactsManager, HardkasL2, HardkasLineage, HardkasLocalnet, type HardkasOptions, HardkasQuery, HardkasReplay, HardkasTx, HardkasWorkspace, type TaskArgs, type TaskContext, defineTask };