diff --git a/docs/errors.md b/docs/errors.md index 8c274934..2deffdc7 100644 --- a/docs/errors.md +++ b/docs/errors.md @@ -102,6 +102,10 @@ error-code table because they are not errors. ## ZK +| `CAATINGA_ZK_VK_REQUIRED` | A zero-knowledge operation requires a verification key. | The requested ZK operation was started without a verification key artifact. | Provide the verification key generated for the circuit and retry. | Fail CI and verify the circuit artifacts are complete. | Public code; adding a new code is minor, removal/rename/meaning change is major. | +| `CAATINGA_ZK_INVOKE_FAILED` | A zero-knowledge contract invocation failed. | The verifier invocation was rejected or returned an invocation error. | Inspect the contract and invocation arguments, then retry with valid proof inputs. | Fail CI and inspect verifier invocation diagnostics. | Public code; adding a new code is minor, removal/rename/meaning change is major. | +| `CAATINGA_ZK_DOWNLOAD_FAILED` | A required zero-knowledge artifact could not be downloaded. | The artifact host was unavailable or the download failed. | Check network access and artifact availability, then retry. | Fail CI and verify artifact hosting. | Public code; adding a new code is minor, removal/rename/meaning change is major. | +| `CAATINGA_ZK_UNSUPPORTED_PLATFORM` | A zero-knowledge operation is unavailable on the current platform. | The requested ZK tool or artifact has no supported build for the current operating system or architecture. | Run the operation on a supported platform or provide a compatible tool build. | Fail CI on unsupported release targets. | Public code; adding a new code is minor, removal/rename/meaning change is major. | | Code | Meaning | Common cause | User action | CI/release action | Versioning note | | ---------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CAATINGA_ZK_VERIFICATION_FAILED` | On-chain ZK proof verification returned `false`. | The submitted proof does not match the verification key or public signals. | Regenerate the proof with correct inputs (`ctg zk prove`) and retry. Inspect `public.json` to confirm the expected public signals. | Fail CI and verify circuit inputs and proof artifacts are consistent. | Public code; adding a new code is minor, removal/rename/meaning change is major. | diff --git a/packages/core/src/errors/CaatingaError.ts b/packages/core/src/errors/CaatingaError.ts index bbb24e2e..0a119f9f 100644 --- a/packages/core/src/errors/CaatingaError.ts +++ b/packages/core/src/errors/CaatingaError.ts @@ -17,6 +17,10 @@ export class CaatingaError extends Error { const ZK_ERROR_CODE_MAP: Record = { ZK_VERIFY_FAILED: CaatingaErrorCode.ZK_VERIFICATION_FAILED, ZK_DEV_CEREMONY_BLOCKED: CaatingaErrorCode.ZK_DEV_CEREMONY_BLOCKED, + ZK_VK_REQUIRED: CaatingaErrorCode.ZK_VK_REQUIRED, + ZK_INVOKE_FAILED: CaatingaErrorCode.ZK_INVOKE_FAILED, + ZK_DOWNLOAD_FAILED: CaatingaErrorCode.ZK_DOWNLOAD_FAILED, + ZK_UNSUPPORTED_PLATFORM: CaatingaErrorCode.ZK_UNSUPPORTED_PLATFORM, }; export function toCaatingaError(error: unknown): CaatingaError { diff --git a/packages/core/src/errors/CaatingaErrorCode.ts b/packages/core/src/errors/CaatingaErrorCode.ts index 5bdb5184..6ae15142 100644 --- a/packages/core/src/errors/CaatingaErrorCode.ts +++ b/packages/core/src/errors/CaatingaErrorCode.ts @@ -54,6 +54,10 @@ export const CaatingaErrorCode = { TEMPLATE_INCOMPATIBLE: "CAATINGA_TEMPLATE_INCOMPATIBLE", ZK_VERIFICATION_FAILED: "CAATINGA_ZK_VERIFICATION_FAILED", ZK_DEV_CEREMONY_BLOCKED: "CAATINGA_ZK_DEV_CEREMONY_BLOCKED", + ZK_VK_REQUIRED: "CAATINGA_ZK_VK_REQUIRED", + ZK_INVOKE_FAILED: "CAATINGA_ZK_INVOKE_FAILED", + ZK_DOWNLOAD_FAILED: "CAATINGA_ZK_DOWNLOAD_FAILED", + ZK_UNSUPPORTED_PLATFORM: "CAATINGA_ZK_UNSUPPORTED_PLATFORM", DOCTOR_PARTIAL_DEPLOY: "CAATINGA_DOCTOR_PARTIAL_DEPLOY", ROLLBACK_TARGET_NOT_FOUND: "CAATINGA_ROLLBACK_TARGET_NOT_FOUND", ESTIMATE_FAILED: "CAATINGA_ESTIMATE_FAILED", diff --git a/packages/core/src/errors/error-surface.test.ts b/packages/core/src/errors/error-surface.test.ts index 34efce1f..ab9f2fa8 100644 --- a/packages/core/src/errors/error-surface.test.ts +++ b/packages/core/src/errors/error-surface.test.ts @@ -254,6 +254,22 @@ const productionTriggerTests: Record { expect(result.message).toBe("Verifier returned false."); expect(result.hint).toBe("Check your proof inputs."); }); + + it.each([ + ["ZK_VK_REQUIRED", CaatingaErrorCode.ZK_VK_REQUIRED], + ["ZK_INVOKE_FAILED", CaatingaErrorCode.ZK_INVOKE_FAILED], + ["ZK_DOWNLOAD_FAILED", CaatingaErrorCode.ZK_DOWNLOAD_FAILED], + ["ZK_UNSUPPORTED_PLATFORM", CaatingaErrorCode.ZK_UNSUPPORTED_PLATFORM], + ])("should_map_ZkError_%s", (sourceCode, expectedCode) => { + const result = toCaatingaError(Object.assign(new Error("zk failure"), { code: sourceCode })); + + expect(result.code).toBe(expectedCode); + }); });