@caatinga/core 3.1.2 → 3.3.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { C as CaatingaArtifacts, c as ContractArtifact, d as CaatingaErrorCodeValue, a as CaatingaError } from './artifact.schema-D4r8dyYK.cjs';
-export { e as CaatingaArtifactsSchema, b as CaatingaErrorCode, f as formatCaatingaError, t as toCaatingaError } from './artifact.schema-D4r8dyYK.cjs';
+import { C as CaatingaArtifacts, c as ContractArtifact, A as ArtifactSupersedeReason, d as CaatingaArtifactsV2, e as CaatingaErrorCodeValue, a as CaatingaError } from './artifact.schema-CIDkTrL3.cjs';
+export { g as CURRENT_ARTIFACTS_SCHEMA_VERSION, h as CaatingaArtifactsSchema, b as CaatingaErrorCode, f as formatCaatingaError, t as toCaatingaError } from './artifact.schema-CIDkTrL3.cjs';
 import { z } from 'zod';
 
 declare const CAATINGA_CORE_VERSION: string;
@@ -76,14 +76,14 @@ declare const CaatingaConfigSchema: z.ZodObject<{
         networkPassphrase: string;
     }>>;
     frontend: z.ZodOptional<z.ZodObject<{
-        framework: z.ZodDefault<z.ZodEnum<["vite-react", "next", "astro"]>>;
+        framework: z.ZodDefault<z.ZodLiteral<"vite-react">>;
         bindingsOutput: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         bindingsOutput: string;
     }, {
         bindingsOutput: string;
-        framework?: "vite-react" | "next" | "astro" | undefined;
+        framework?: "vite-react" | undefined;
     }>>;
     zk: z.ZodOptional<z.ZodObject<{
         circuits: z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -131,7 +131,7 @@ declare const CaatingaConfigSchema: z.ZodObject<{
         networkPassphrase: string;
     }>;
     frontend?: {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         bindingsOutput: string;
     } | undefined;
     zk?: {
@@ -157,7 +157,7 @@ declare const CaatingaConfigSchema: z.ZodObject<{
     defaultNetwork?: string | undefined;
     frontend?: {
         bindingsOutput: string;
-        framework?: "vite-react" | "next" | "astro" | undefined;
+        framework?: "vite-react" | undefined;
     } | undefined;
     zk?: {
         circuits: Record<string, {
@@ -188,10 +188,106 @@ type CreateInitialArtifactsOptions = {
 };
 declare function createInitialArtifacts(project: string, options?: CreateInitialArtifactsOptions): CaatingaArtifacts;
 
-declare function updateArtifact(artifacts: CaatingaArtifacts, networkName: string, contractName: string, contractArtifact: ContractArtifact, networkExtras?: {
+type UpdateArtifactOptions = {
     dependencyGraph?: Record<string, string[]>;
+    supersedeReason?: ArtifactSupersedeReason;
+};
+declare function updateArtifact(artifacts: CaatingaArtifacts, networkName: string, contractName: string, contractArtifact: ContractArtifact, options?: UpdateArtifactOptions): CaatingaArtifacts;
+declare function restoreArtifactFromHistory(input: {
+    artifacts: CaatingaArtifacts;
+    networkName: string;
+    contractName: string;
+    contractId: string;
 }): CaatingaArtifacts;
 
+type MigrateArtifactsResult = {
+    artifacts: CaatingaArtifactsV2;
+    migrated: boolean;
+};
+declare function migrateArtifactsToV2(artifacts: CaatingaArtifacts): MigrateArtifactsResult;
+
+declare function migrateArtifactsFile(cwd?: string): Promise<{
+    path: string;
+    migrated: boolean;
+    artifacts: {
+        project: string;
+        networks: Record<string, {
+            contracts: Record<string, {
+                contractId: string;
+                wasmHash: string;
+                deployedAt: string;
+                sourcePath: string;
+                wasmPath: string;
+                dependencies: string[];
+                resolvedDeployArgs: Record<string, string | number | boolean>;
+                history?: {
+                    contractId: string;
+                    wasmHash: string;
+                    deployedAt: string;
+                    supersededAt: string;
+                    reason?: "upgrade" | "rollback" | "force-redeploy" | undefined;
+                }[] | undefined;
+            }>;
+            dependencyGraph: Record<string, string[]>;
+        }>;
+        version: 2;
+    };
+}>;
+
+declare function rollbackContractArtifact(input: {
+    networkName: string;
+    contractName: string;
+    contractId: string;
+    cwd?: string;
+}): Promise<{
+    path: string;
+    artifacts: {
+        project: string;
+        networks: Record<string, {
+            contracts: Record<string, {
+                contractId: string;
+                wasmHash: string;
+                deployedAt: string;
+                sourcePath: string;
+                wasmPath: string;
+                dependencies: string[];
+                resolvedDeployArgs: Record<string, string | number | boolean>;
+                history?: {
+                    contractId: string;
+                    wasmHash: string;
+                    deployedAt: string;
+                    supersededAt: string;
+                    reason?: "upgrade" | "rollback" | "force-redeploy" | undefined;
+                }[] | undefined;
+            }>;
+            dependencyGraph: Record<string, string[]>;
+        }>;
+        version: 1;
+    } | {
+        project: string;
+        networks: Record<string, {
+            contracts: Record<string, {
+                contractId: string;
+                wasmHash: string;
+                deployedAt: string;
+                sourcePath: string;
+                wasmPath: string;
+                dependencies: string[];
+                resolvedDeployArgs: Record<string, string | number | boolean>;
+                history?: {
+                    contractId: string;
+                    wasmHash: string;
+                    deployedAt: string;
+                    supersededAt: string;
+                    reason?: "upgrade" | "rollback" | "force-redeploy" | undefined;
+                }[] | undefined;
+            }>;
+            dependencyGraph: Record<string, string[]>;
+        }>;
+        version: 2;
+    };
+}>;
+
 declare const BINDING_MARKER_FILENAME = ".caatinga-bindings.json";
 declare const BindingMarkerSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -325,9 +421,42 @@ type CheckStellarCliVersionOptions = {
     features?: readonly string[];
     lastTestedVersion?: string;
     onWarning?: (warning: CompatibilityWarning) => void;
+    /** When false, skip live capability probes (used in unit tests). Default true. */
+    probeFeatures?: boolean;
 };
 declare function checkStellarCliVersion(input?: CheckStellarCliVersionOptions): Promise<CompatibilityReport>;
 
+declare const STELLAR_SDK_MIN_VERSION = "16.0.1";
+declare const STELLAR_SDK_LAST_TESTED_VERSION = "16.0.1";
+
+type SdkCompatibilityStatus = "supported" | "untested" | "unsupported";
+type SdkCompatibilityWarningCode = "STELLAR_SDK_UNTESTED_VERSION" | "STELLAR_SDK_VERSION_PARSE_FAILED";
+type SdkCompatibilityWarning = {
+    code: SdkCompatibilityWarningCode;
+    message: string;
+    remediation?: string;
+};
+type SdkCompatibilityReport = {
+    version: string;
+    status: SdkCompatibilityStatus;
+    minVersion: string;
+    lastTestedVersion: string;
+    warnings: SdkCompatibilityWarning[];
+};
+type EvaluateStellarSdkCompatibilityInput = {
+    version: string;
+    lastTestedVersion?: string;
+};
+declare function evaluateStellarSdkCompatibility(input: EvaluateStellarSdkCompatibilityInput): SdkCompatibilityReport;
+declare function parseStellarSdkVersion(raw: string): string;
+
+type CheckStellarSdkVersionOptions = {
+    cwd?: string;
+    lastTestedVersion?: string;
+    onWarning?: (warning: SdkCompatibilityWarning) => void;
+};
+declare function checkStellarSdkVersion(input?: CheckStellarSdkVersionOptions): Promise<SdkCompatibilityReport>;
+
 declare function validateSourceShape(source: string): CaatingaError | undefined;
 
 type ResolvedContract = {
@@ -369,9 +498,17 @@ type DeployContractOptions = {
     source?: string;
     cwd?: string;
     force?: boolean;
+    upgrade?: boolean;
     checkStaleWasm?: boolean;
     resolvedDeployArgs?: Record<string, DeployArgValue>;
     dependencies?: string[];
+    onTransientDeployRetry?: (info: {
+        attempt: number;
+        maxAttempts: number;
+        delayMs: number;
+    }) => void;
+    /** Override retry backoff delays (primarily for tests). */
+    deployRetryDelaysMs?: readonly number[];
 };
 declare function deployContract(options: DeployContractOptions): Promise<{
     contract: {
@@ -429,8 +566,10 @@ declare function deployContractGraph(options: {
     cwd?: string;
     includeDependencies: boolean;
     force: boolean;
+    upgrade?: boolean;
     checkStaleWasm?: boolean;
     verifyDeps?: boolean;
+    onTransientDeployRetry?: DeployContractOptions["onTransientDeployRetry"];
 }): Promise<DeployContractGraphResult>;
 
 declare function buildDependencyGraph(contracts: Record<string, ContractConfig>): Record<string, string[]>;
@@ -512,6 +651,53 @@ declare function readContract(options: ReadContractOptions): Promise<{
     result: string;
 }>;
 
+type DeployCostEstimate = {
+    contractName: string;
+    network: string;
+    wasmPath: string;
+    inclusionFeeStroops: number;
+    resourceFeeStroops?: number;
+    totalFeeStroops: number;
+    advisory: string;
+    rawOutput?: string;
+};
+type EstimateDeployCostOptions = {
+    config: CaatingaConfig;
+    contractName: string;
+    networkName?: string;
+    source?: string;
+    cwd?: string;
+};
+declare function estimateDeployCost(options: EstimateDeployCostOptions): Promise<DeployCostEstimate>;
+
+type ContractInspectResult = {
+    contractName: string;
+    network: string;
+    artifact: {
+        contractId: string;
+        wasmHash: string;
+        deployedAt: string;
+        historyCount: number;
+    };
+    onChain: {
+        reachable: boolean;
+        detail?: string;
+    };
+    localWasm: {
+        path: string;
+        hash?: string;
+        matchesArtifact: boolean;
+    };
+    dependencies: string[];
+};
+type InspectContractOptions = {
+    config: CaatingaConfig;
+    contractName: string;
+    networkName?: string;
+    cwd?: string;
+};
+declare function inspectContract(options: InspectContractOptions): Promise<ContractInspectResult>;
+
 type CreateProjectFromTemplateOptions = {
     projectName: string;
     targetDir: string;
@@ -526,7 +712,7 @@ declare function createProjectFromTemplate(options: CreateProjectFromTemplateOpt
             default?: string | undefined;
         };
         frontend: {
-            framework: "vite-react" | "next" | "astro";
+            framework: "vite-react";
             packageManager: "npm" | "pnpm" | "yarn" | "bun";
         };
         version: string;
@@ -536,8 +722,8 @@ declare function createProjectFromTemplate(options: CreateProjectFromTemplateOpt
             templateVersion: number;
         };
         files: {
-            config: string;
             artifacts: string;
+            config: string;
         };
         description?: string | undefined;
     };
@@ -577,13 +763,13 @@ declare const TemplateManifestSchema: z.ZodObject<{
         templateVersion: number;
     }>;
     frontend: z.ZodObject<{
-        framework: z.ZodEnum<["vite-react", "next", "astro"]>;
+        framework: z.ZodLiteral<"vite-react">;
         packageManager: z.ZodDefault<z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>>;
     }, "strip", z.ZodTypeAny, {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         packageManager: "npm" | "pnpm" | "yarn" | "bun";
     }, {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         packageManager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     }>;
     contracts: z.ZodObject<{
@@ -600,11 +786,11 @@ declare const TemplateManifestSchema: z.ZodObject<{
         config: z.ZodDefault<z.ZodString>;
         artifacts: z.ZodDefault<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
-        config: string;
         artifacts: string;
+        config: string;
     }, {
-        config?: string | undefined;
         artifacts?: string | undefined;
+        config?: string | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
     contracts: {
@@ -612,7 +798,7 @@ declare const TemplateManifestSchema: z.ZodObject<{
         default?: string | undefined;
     };
     frontend: {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         packageManager: "npm" | "pnpm" | "yarn" | "bun";
     };
     version: string;
@@ -622,8 +808,8 @@ declare const TemplateManifestSchema: z.ZodObject<{
         templateVersion: number;
     };
     files: {
-        config: string;
         artifacts: string;
+        config: string;
     };
     description?: string | undefined;
 }, {
@@ -632,7 +818,7 @@ declare const TemplateManifestSchema: z.ZodObject<{
         default?: string | undefined;
     };
     frontend: {
-        framework: "vite-react" | "next" | "astro";
+        framework: "vite-react";
         packageManager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     };
     version: string;
@@ -642,8 +828,8 @@ declare const TemplateManifestSchema: z.ZodObject<{
         templateVersion: number;
     };
     files: {
-        config?: string | undefined;
         artifacts?: string | undefined;
+        config?: string | undefined;
     };
     description?: string | undefined;
 }>;
@@ -651,4 +837,4 @@ type TemplateManifest = z.infer<typeof TemplateManifestSchema>;
 
 declare function isTransientTestnetSmokeFailure(logText: string): boolean;
 
-export { BINDING_MARKER_FILENAME, type BindingFreshness, type BindingFreshnessStatus, type BindingMarker, BindingMarkerSchema, type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CollectProjectStatusOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type ContractStatusEntry, type CreateInitialArtifactsOptions, type CreateMinimalProjectOptions, type CreateProjectFromTemplateOptions, type CreateZkProjectOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type EvaluateBindingFreshnessOptions, type EvaluateStellarCliCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type NetworkStatus, type ProjectStatus, READ_CALL_FAILURE_REGEX, type ReadContractOptions, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, buildReadCallHint, checkBinary, checkStellarCliVersion, collectProjectStatus, createInitialArtifacts, createMinimalProject, createProjectFromTemplate, createZkProject, defineConfig, deployContract, deployContractGraph, evaluateBindingFreshness, evaluateBindingsFreshness, evaluateStellarCliCompatibility, generateBindings, generateBindingsGraph, invokeContract, isCargoBinMissingFromPath, isReadCallFailure, isTransientTestnetSmokeFailure, loadConfig, parseContractId, parseInvokeTarget, parseStellarCliVersion, readArtifacts, readBindingMarker, readContract, resolveContract, resolveDefaultContractName, resolveDeployArgs, resolveDeployOrder, resolveNetwork, resolveSubprocessEnv, runCommand, updateArtifact, validateSourceShape, writeArtifacts, writeBindingMarker };
+export { BINDING_MARKER_FILENAME, type BindingFreshness, type BindingFreshnessStatus, type BindingMarker, BindingMarkerSchema, type BuildContractOptions, CAATINGA_CORE_VERSION, CaatingaArtifacts, type CaatingaConfig, CaatingaConfigSchema, CaatingaError, type CheckStellarCliVersionOptions, type CheckStellarSdkVersionOptions, type CollectProjectStatusOptions, type CompatibilityReport, type CompatibilityStatus, type CompatibilityWarning, type CompatibilityWarningCode, ContractArtifact, type ContractConfig, type ContractInspectResult, type ContractStatusEntry, type CreateInitialArtifactsOptions, type CreateMinimalProjectOptions, type CreateProjectFromTemplateOptions, type CreateZkProjectOptions, type DeployArgValue, type DeployContractGraphResult, type DeployContractOptions, type DeployCostEstimate, type EstimateDeployCostOptions, type EvaluateBindingFreshnessOptions, type EvaluateStellarCliCompatibilityInput, type EvaluateStellarSdkCompatibilityInput, type GenerateBindingsGraphResult, type GenerateBindingsOptions, type InspectContractOptions, type InvokeContractOptions, type InvokeTarget, type LoadConfigOptions, type NetworkConfig, type NetworkStatus, type ProjectStatus, READ_CALL_FAILURE_REGEX, type ReadContractOptions, type ResolvedContract, type ResolvedNetwork, type RunCommandResult, STELLAR_CLI_LAST_TESTED_VERSION, STELLAR_CLI_MIN_VERSION, STELLAR_SDK_LAST_TESTED_VERSION, STELLAR_SDK_MIN_VERSION, type SdkCompatibilityReport, type SdkCompatibilityStatus, type SdkCompatibilityWarning, type SdkCompatibilityWarningCode, type SkippedContract, type TemplateManifest, TemplateManifestSchema, WELL_KNOWN_NETWORKS, buildContract, buildDependencyGraph, buildReadCallHint, checkBinary, checkStellarCliVersion, checkStellarSdkVersion, collectProjectStatus, createInitialArtifacts, createMinimalProject, createProjectFromTemplate, createZkProject, defineConfig, deployContract, deployContractGraph, estimateDeployCost, evaluateBindingFreshness, evaluateBindingsFreshness, evaluateStellarCliCompatibility, evaluateStellarSdkCompatibility, generateBindings, generateBindingsGraph, inspectContract, invokeContract, isCargoBinMissingFromPath, isReadCallFailure, isTransientTestnetSmokeFailure, loadConfig, migrateArtifactsFile, migrateArtifactsToV2, parseContractId, parseInvokeTarget, parseStellarCliVersion, parseStellarSdkVersion, readArtifacts, readBindingMarker, readContract, resolveContract, resolveDefaultContractName, resolveDeployArgs, resolveDeployOrder, resolveNetwork, resolveSubprocessEnv, restoreArtifactFromHistory, rollbackContractArtifact, runCommand, updateArtifact, validateSourceShape, writeArtifacts, writeBindingMarker };