@vallum/contracts-metadata 0.0.0-prerelease

package/README.md

@@ -0,0 +1,18 @@
+# @vallum/contracts-metadata
+
+Versioned contract template metadata registry for Vallum policy
+allow-lists.
+
+This package is local prerelease workspace code. It provides metadata and pure
+evaluation helpers for approved contract templates such as `escrow_v1`,
+`receipt_v1`, `pay_per_call_v1`, `data_license_v1`, `service_bounty_v1`,
+`reputation_receipt_v1`, and `subscription_v1`; it does not deploy contracts,
+verify providers, settle payments, operate reputation scoring, operate
+recurring billing, or prove live package addresses.
+
+## Local checks
+
+```bash
+npm run build -w @vallum/contracts-metadata
+node --import tsx --test packages/contracts-metadata/src/*.test.ts
+```

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+export type ContractTemplateRiskCategory = "low" | "medium" | "high";
+export interface ContractTemplateMetadata {
+    readonly templateId: string;
+    readonly version: string;
+    readonly packageId: string;
+    readonly module: string;
+    readonly entryFunctions: readonly string[];
+    readonly allowedActions: readonly string[];
+    readonly riskCategory: ContractTemplateRiskCategory;
+    readonly receiptEvents: readonly string[];
+    readonly requiredManifestFields: readonly string[];
+    readonly refundDisputeBehavior: string;
+}
+export interface ContractTemplateAction {
+    readonly templateId?: string;
+    readonly templateVersion?: string;
+    readonly packageId: string;
+    readonly module?: string;
+    readonly functionName: string;
+}
+export type ContractTemplateDecision = {
+    readonly allowed: true;
+    readonly template: ContractTemplateMetadata;
+} | {
+    readonly allowed: false;
+    readonly reasonCode: "CONTRACT_TEMPLATE_NOT_REGISTERED" | "CONTRACT_TEMPLATE_VERSION_MISMATCH" | "CONTRACT_PACKAGE_NOT_REGISTERED" | "CONTRACT_MODULE_NOT_REGISTERED" | "CONTRACT_FUNCTION_NOT_REGISTERED";
+    readonly message: string;
+};
+export interface ContractTemplateRegistry {
+    readonly templates: readonly ContractTemplateMetadata[];
+    readonly findTemplate: (templateId: string, version: string) => ContractTemplateMetadata | undefined;
+    readonly findTemplateVersions: (templateId: string) => readonly ContractTemplateMetadata[];
+}
+export declare const escrowContractTemplateV1: ContractTemplateMetadata;
+export declare const receiptContractTemplateV1: ContractTemplateMetadata;
+export declare const payPerCallContractTemplateV1: ContractTemplateMetadata;
+export declare const dataLicenseContractTemplateV1: ContractTemplateMetadata;
+export declare const serviceBountyContractTemplateV1: ContractTemplateMetadata;
+export declare const reputationReceiptContractTemplateV1: ContractTemplateMetadata;
+export declare const subscriptionContractTemplateV1: ContractTemplateMetadata;
+export declare const defaultContractTemplates: readonly [ContractTemplateMetadata, ContractTemplateMetadata, ContractTemplateMetadata, ContractTemplateMetadata, ContractTemplateMetadata, ContractTemplateMetadata, ContractTemplateMetadata];
+export declare const defaultContractTemplateRegistry: ContractTemplateRegistry;
+export declare function createContractTemplateRegistry(templates: readonly ContractTemplateMetadata[]): ContractTemplateRegistry;
+export declare function evaluateContractTemplateAction(registry: ContractTemplateRegistry, action: ContractTemplateAction): ContractTemplateDecision;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,140 @@
+export const escrowContractTemplateV1 = {
+    templateId: "escrow_v1",
+    version: "1.0.0",
+    packageId: "0x2222222222222222222222222222222222222222222222222222222222222222",
+    module: "escrow",
+    entryFunctions: ["open_escrow", "release_escrow", "refund_escrow"],
+    allowedActions: ["open_escrow", "release_escrow", "refund_escrow"],
+    riskCategory: "medium",
+    receiptEvents: ["escrow_opened", "escrow_released", "escrow_refunded"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Verifier release or expiry/refund state transition.",
+};
+export const receiptContractTemplateV1 = {
+    templateId: "receipt_v1",
+    version: "1.0.0",
+    packageId: "0x4444444444444444444444444444444444444444444444444444444444444444",
+    module: "receipt",
+    entryFunctions: ["create_receipt", "mark_released", "mark_refunded"],
+    allowedActions: ["create_receipt", "mark_released", "mark_refunded"],
+    riskCategory: "low",
+    receiptEvents: ["receipt_created", "receipt_released", "receipt_refunded"],
+    requiredManifestFields: ["agent", "owner", "action", "receipt"],
+    refundDisputeBehavior: "Records external escrow outcome without independently settling funds.",
+};
+export const payPerCallContractTemplateV1 = {
+    templateId: "pay_per_call_v1",
+    version: "1.0.0",
+    packageId: "0x5555555555555555555555555555555555555555555555555555555555555555",
+    module: "pay_per_call",
+    entryFunctions: ["request_call", "deliver", "refund"],
+    allowedActions: ["request_call", "deliver", "refund"],
+    riskCategory: "medium",
+    receiptEvents: ["pay_per_call_created", "submitted", "completed", "failed"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Provider delivery after payment confirmation or refund/fail before result delivery.",
+};
+export const dataLicenseContractTemplateV1 = {
+    templateId: "data_license_v1",
+    version: "1.0.0",
+    packageId: "0x6666666666666666666666666666666666666666666666666666666666666666",
+    module: "data_license",
+    entryFunctions: ["request_license", "grant_access", "revoke_access"],
+    allowedActions: ["request_license", "grant_access", "revoke_access"],
+    riskCategory: "medium",
+    receiptEvents: ["data_license_created", "access_granted", "access_revoked", "failed"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Provider grants scoped access after policy approval or revokes access with receipt evidence.",
+};
+export const serviceBountyContractTemplateV1 = {
+    templateId: "service_bounty_v1",
+    version: "1.0.0",
+    packageId: "0x7777777777777777777777777777777777777777777777777777777777777777",
+    module: "service_bounty",
+    entryFunctions: ["post_bounty", "complete_bounty", "release_bounty", "cancel_bounty"],
+    allowedActions: ["post_bounty", "complete_bounty", "release_bounty", "cancel_bounty"],
+    riskCategory: "medium",
+    receiptEvents: ["service_bounty_created", "submitted", "completed", "released", "failed"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Provider completion proof followed by requester release, or cancellation/failure evidence.",
+};
+export const reputationReceiptContractTemplateV1 = {
+    templateId: "reputation_receipt_v1",
+    version: "1.0.0",
+    packageId: "0x8888888888888888888888888888888888888888888888888888888888888888",
+    module: "reputation_receipt",
+    entryFunctions: ["create_receipt", "attest_reputation", "fail_receipt"],
+    allowedActions: ["create_receipt", "attest_reputation", "fail_receipt"],
+    riskCategory: "medium",
+    receiptEvents: ["reputation_receipt_created", "submitted", "completed", "failed"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Issuer attests local reputation evidence; failures are receipt evidence, not public scoring.",
+};
+export const subscriptionContractTemplateV1 = {
+    templateId: "subscription_v1",
+    version: "1.0.0",
+    packageId: "0x9999999999999999999999999999999999999999999999999999999999999998",
+    module: "subscription",
+    entryFunctions: ["start_subscription", "renew_subscription", "cancel_subscription", "fail_subscription"],
+    allowedActions: ["start_subscription", "renew_subscription", "cancel_subscription", "fail_subscription"],
+    riskCategory: "medium",
+    receiptEvents: ["subscription_created", "activated", "renewed", "canceled", "failed"],
+    requiredManifestFields: ["agent", "owner", "spend", "action", "counterparty", "receipt"],
+    refundDisputeBehavior: "Local entitlement evidence for activation, renewal, cancellation, or failed proof.",
+};
+export const defaultContractTemplates = [
+    escrowContractTemplateV1,
+    receiptContractTemplateV1,
+    payPerCallContractTemplateV1,
+    dataLicenseContractTemplateV1,
+    serviceBountyContractTemplateV1,
+    reputationReceiptContractTemplateV1,
+    subscriptionContractTemplateV1,
+];
+export const defaultContractTemplateRegistry = createContractTemplateRegistry(defaultContractTemplates);
+export function createContractTemplateRegistry(templates) {
+    const byTemplateVersion = new Map();
+    const byTemplate = new Map();
+    for (const template of templates) {
+        byTemplateVersion.set(templateKey(template.templateId, template.version), template);
+        const versions = byTemplate.get(template.templateId) ?? [];
+        versions.push(template);
+        byTemplate.set(template.templateId, versions);
+    }
+    return {
+        templates: Object.freeze([...templates]),
+        findTemplate(templateId, version) {
+            return byTemplateVersion.get(templateKey(templateId, version));
+        },
+        findTemplateVersions(templateId) {
+            return Object.freeze([...(byTemplate.get(templateId) ?? [])]);
+        },
+    };
+}
+export function evaluateContractTemplateAction(registry, action) {
+    if (!action.templateId || !action.templateVersion) {
+        return reject("CONTRACT_TEMPLATE_NOT_REGISTERED", "Contract action is missing template id or version metadata.");
+    }
+    const template = registry.findTemplate(action.templateId, action.templateVersion);
+    if (!template) {
+        const knownVersions = registry.findTemplateVersions(action.templateId);
+        return reject(knownVersions.length > 0 ? "CONTRACT_TEMPLATE_VERSION_MISMATCH" : "CONTRACT_TEMPLATE_NOT_REGISTERED", "Contract template id and version are not registered.");
+    }
+    if (template.packageId !== action.packageId) {
+        return reject("CONTRACT_PACKAGE_NOT_REGISTERED", "Contract package does not match approved template metadata.");
+    }
+    if (template.module !== action.module) {
+        return reject("CONTRACT_MODULE_NOT_REGISTERED", "Contract module does not match approved template metadata.");
+    }
+    if (!template.entryFunctions.includes(action.functionName)) {
+        return reject("CONTRACT_FUNCTION_NOT_REGISTERED", "Contract function does not match approved template metadata.");
+    }
+    return { allowed: true, template };
+}
+function templateKey(templateId, version) {
+    return `${templateId}@${version}`;
+}
+function reject(reasonCode, message) {
+    return { allowed: false, reasonCode, message };
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vallum/contracts-metadata",
+  "version": "0.0.0-prerelease",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "license": "Apache-2.0",
+  "description": "Versioned contract template metadata registry for Vallum policy allow-lists.",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}