@carrot-foundation/schemas 0.5.1 → 2.0.0

package/dist/index.js

@@ -28136,12 +28136,11 @@ var StringifiedTokenIdSchema = NonEmptyStringSchema.regex(
   examples: ["#456789", "#1000000"],
   example: "#456789"
 });
-var Sha256HashSchema = z.hash("sha256", {
-  error: "Must be a SHA256 hash as 32-byte hex string"
+var Sha256HashSchema = z.string().regex(/^[a-f0-9]{64}$/, {
+  error: "Must be a SHA-256 hash as 32-byte lowercase hex string (no 0x prefix)"
 }).meta({
-  format: void 0,
   title: "SHA-256 Hash",
-  description: "SHA-256 cryptographic hash as hexadecimal string",
+  description: "SHA-256 cryptographic hash as canonical lowercase hexadecimal string",
   examples: [
     "87f633634cc4b02f628685651f0a29b7bfa22a0bd841f725c6772dd00a58d489"
   ]
@@ -29383,9 +29382,9 @@ var CreditPurchaseReceiptSummarySchema = SummaryBaseSchema.safeExtend({
     title: "Total Amount (USDC)",
     description: "Total amount paid in USDC stablecoin for the credit purchase"
   }),
-  total_credits: CreditAmountSchema.meta({
+  total_credits: CreditAmountSchema.gt(0).meta({
     title: "Total Credits",
-    description: "Total number of environmental impact credits purchased in this transaction"
+    description: "Total number of environmental impact credits purchased in this transaction. Must be greater than 0."
   }),
   purchased_at: IsoDateTimeSchema.meta({
     title: "Purchased At",
@@ -29396,9 +29395,9 @@ var CreditPurchaseReceiptSummarySchema = SummaryBaseSchema.safeExtend({
   description: "Summary totals for the credit purchase including payment amount, credit quantity, certificate count, and timestamp"
 });
 var CreditRetirementReceiptSummarySchema = SummaryBaseSchema.safeExtend({
-  total_credits_retired: CreditAmountSchema.meta({
+  total_credits_retired: CreditAmountSchema.gt(0).meta({
     title: "Total Credits Retired",
-    description: "Total number of environmental impact credits permanently retired (removed from circulation)"
+    description: "Total number of environmental impact credits permanently retired (removed from circulation). Must be greater than 0."
   }),
   retired_at: IsoDateTimeSchema.meta({
     title: "Retired At",
@@ -29485,7 +29484,7 @@ function buildSchemaUrl(schemaPath) {
   return `${getSchemaBaseUrl()}/${cleanPath}`;
 }
 function getSchemaVersionOrDefault() {
-  return "0.5.1";
+  return "2.0.0";
 }
 
 // src/shared/schema-validation.ts
@@ -31080,18 +31079,18 @@ var CreditPurchaseReceiptAttributesSchema = createOrderedAttributesSchema({
 });
 var CreditPurchaseReceiptIdentitySchema = ReceiptIdentitySchema;
 var CreditPurchaseReceiptBuyerSchema = z.strictObject({
-  wallet_address: EthereumAddressSchema.meta({
+  id_hash: Sha256HashSchema.meta({
+    title: "Buyer ID Hash",
+    description: "Anonymized pseudonymous identifier linking this buyer to off-chain records via a keyed hash"
+  }),
+  wallet_address: EthereumAddressSchema.optional().meta({
     title: "Buyer Wallet Address",
     description: "Ethereum address receiving the credits"
   }),
-  id: ExternalIdSchema.optional().meta({
-    title: "Buyer ID",
-    description: "Unique identifier for the buyer"
-  }),
   identity: CreditPurchaseReceiptIdentitySchema.optional()
 }).meta({
   title: "Buyer",
-  description: "Buyer information including wallet address, optional ID, and optional identity"
+  description: "Buyer information including hashed identifier, optional wallet address, and optional identity"
 });
 var CreditPurchaseReceiptCollectionSchema = createReceiptCollectionSchema({
   meta: {
@@ -31107,13 +31106,17 @@ var CreditPurchaseReceiptCertificateSchema = CertificateReferenceBaseSchema.safe
   credit_slug: CreditTokenSlugSchema.meta({
     description: "Slug of the credit type for this certificate"
   }),
+  purchased_amount: CreditAmountSchema.meta({
+    title: "Certificate Purchased Amount",
+    description: "Total credits purchased from this certificate. Authoritative source for receipt totals; cross-checked against sum(collections[].purchased_amount) when collections are non-empty."
+  }),
   collections: uniqueBy(
     CertificateCollectionItemPurchaseSchema,
     (item) => item.slug,
     "Collection slugs within certificate collections must be unique"
-  ).min(1).meta({
+  ).meta({
     title: "Certificate Collections",
-    description: "Collections associated with this certificate, each with purchased and retired amounts"
+    description: "Collections associated with this certificate, each with purchased and retired amounts. May be empty when this certificate is not assigned to any collection."
   })
 }).meta({
   title: "Certificate",
@@ -31127,9 +31130,9 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
     CreditPurchaseReceiptCollectionSchema,
     (collection) => collection.slug,
     "Collection slugs must be unique"
-  ).min(1).meta({
+  ).meta({
     title: "Collections",
-    description: "Impact collections referenced by this purchase, each identified by a unique slug"
+    description: "Impact collections referenced by this purchase, each identified by a unique slug. May be empty when no certificate is assigned to a collection."
   }),
   credits: uniqueBy(
     CreditPurchaseReceiptCreditSchema,
@@ -31159,12 +31162,10 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
   const collectionSlugs = new Set(
     data.collections.map((collection) => String(collection.slug))
   );
+  const referencedCollectionSlugs = /* @__PURE__ */ new Set();
   const creditSlugs = new Set(
     data.credits.map((credit) => String(credit.slug))
   );
-  const creditPurchaseTotalsBySlug = /* @__PURE__ */ new Map();
-  const creditRetiredTotalsBySlug = /* @__PURE__ */ new Map();
-  const collectionPurchasedTotalsBySlug = /* @__PURE__ */ new Map();
   const collectionRetiredTotalsBySlug = /* @__PURE__ */ new Map();
   let totalCreditsFromCertificates = 0;
   data.certificates.forEach((certificate, index) => {
@@ -31175,7 +31176,6 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
       path: ["certificates", index, "credit_slug"]
     });
     let certificatePurchasedTotal = 0;
-    let certificateRetiredTotal = 0;
     validateCertificateCollectionSlugs({
       ctx,
       certificateCollections: certificate.collections,
@@ -31183,6 +31183,7 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
       certificateIndex: index
     });
     certificate.collections.forEach((collectionItem, collectionIndex) => {
+      referencedCollectionSlugs.add(String(collectionItem.slug));
       if (collectionItem.retired_amount > collectionItem.purchased_amount) {
         ctx.addIssue({
           code: "custom",
@@ -31197,42 +31198,45 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
         });
       }
       certificatePurchasedTotal += Number(collectionItem.purchased_amount);
-      certificateRetiredTotal += Number(collectionItem.retired_amount);
-      collectionPurchasedTotalsBySlug.set(
-        collectionItem.slug,
-        (collectionPurchasedTotalsBySlug.get(collectionItem.slug) ?? 0) + Number(collectionItem.purchased_amount)
-      );
       collectionRetiredTotalsBySlug.set(
         collectionItem.slug,
         (collectionRetiredTotalsBySlug.get(collectionItem.slug) ?? 0) + Number(collectionItem.retired_amount)
       );
     });
-    if (certificatePurchasedTotal > certificate.total_amount) {
+    if (certificate.purchased_amount > certificate.total_amount) {
       ctx.addIssue({
         code: "custom",
-        message: "Sum of certificate.collections[].purchased_amount cannot exceed certificate.total_amount",
-        path: ["certificates", index]
+        message: "certificate.purchased_amount cannot exceed certificate.total_amount",
+        path: ["certificates", index, "purchased_amount"]
       });
     }
-    totalCreditsFromCertificates += certificatePurchasedTotal;
-    creditPurchaseTotalsBySlug.set(
-      String(certificate.credit_slug),
-      (creditPurchaseTotalsBySlug.get(certificate.credit_slug) ?? 0) + certificatePurchasedTotal
-    );
-    creditRetiredTotalsBySlug.set(
-      String(certificate.credit_slug),
-      (creditRetiredTotalsBySlug.get(certificate.credit_slug) ?? 0) + certificateRetiredTotal
-    );
+    if (certificate.collections.length > 0 && !nearlyEqual(certificatePurchasedTotal, certificate.purchased_amount)) {
+      ctx.addIssue({
+        code: "custom",
+        message: "certificate.purchased_amount must equal sum of collections[].purchased_amount when collections are present",
+        path: ["certificates", index, "purchased_amount"]
+      });
+    }
+    totalCreditsFromCertificates += Number(certificate.purchased_amount);
   });
   const certificateCollectionRetiredTotal = Array.from(
     collectionRetiredTotalsBySlug.values()
   ).reduce((sum, amount) => sum + amount, 0);
+  data.collections.forEach((collection, collectionIndex) => {
+    if (!referencedCollectionSlugs.has(String(collection.slug))) {
+      ctx.addIssue({
+        code: "custom",
+        message: "collections must only include slugs referenced by certificates[].collections",
+        path: ["collections", collectionIndex, "slug"]
+      });
+    }
+  });
   validateTotalMatches({
     ctx,
     actualTotal: totalCreditsFromCertificates,
     expectedTotal: data.summary.total_credits,
     path: ["summary", "total_credits"],
-    message: "summary.total_credits must equal sum of certificate.collections[].purchased_amount"
+    message: "summary.total_credits must equal sum of certificates[].purchased_amount"
   });
   validateRetirementReceiptRequirement({
     ctx,
@@ -31245,7 +31249,7 @@ var CreditPurchaseReceiptDataSchema = z.strictObject({
 });
 var CreditPurchaseReceiptIpfsSchemaMeta = {
   title: "CreditPurchaseReceipt NFT IPFS Record",
-  description: "Complete CreditPurchaseReceipt NFT IPFS record including purchase summary, buyer details, credit breakdowns, certificate allocations, and NFT display attributes",
+  description: "Complete CreditPurchaseReceipt NFT IPFS record including purchase summary, buyer details, credit breakdowns, certificate allocations, and NFT display attributes. Supports both collection-assigned and no-collection variants.",
   $id: buildSchemaUrl(
     "credit-purchase-receipt/credit-purchase-receipt.schema.json"
   ),
@@ -31383,14 +31387,10 @@ var CreditPurchaseReceiptIpfsSchema = NftIpfsSchema.safeExtend({
       });
       return;
     }
-    const certificatePurchasedTotal = certificate.collections.reduce(
-      (sum, collection) => sum + Number(collection.purchased_amount),
-      0
-    );
     const currentTotal = creditTotalsBySymbol.get(credit.symbol) ?? 0;
     creditTotalsBySymbol.set(
       credit.symbol,
-      currentTotal + certificatePurchasedTotal
+      currentTotal + Number(certificate.purchased_amount)
     );
   });
   data.credits.forEach((credit) => {
@@ -31405,7 +31405,7 @@ var CreditPurchaseReceiptIpfsSchema = NftIpfsSchema.safeExtend({
     } else if (Number(attribute.value) !== expectedTotal) {
       ctx.addIssue({
         code: "custom",
-        message: `Attribute for credit symbol ${credit.symbol} must match sum of certificate.collections[].purchased_amount for the credit symbol`,
+        message: `Attribute for credit symbol ${credit.symbol} must match sum of certificates[].purchased_amount for the credit symbol`,
         path: ["attributes"]
       });
     }
@@ -31507,24 +31507,32 @@ var CreditRetirementReceiptAttributesSchema = createOrderedAttributesSchema({
 });
 var CreditRetirementReceiptIdentitySchema = ReceiptIdentitySchema;
 var CreditRetirementReceiptBeneficiarySchema = z.strictObject({
-  beneficiary_id: ExternalIdSchema.meta({
-    title: "Retirement Beneficiary ID",
-    description: "UUID identifying the beneficiary of the retirement within the Carrot platform"
+  id_hash: Sha256HashSchema.meta({
+    title: "Beneficiary ID Hash",
+    description: "Anonymized pseudonymous identifier linking this beneficiary to off-chain records via a keyed hash"
+  }),
+  wallet_address: EthereumAddressSchema.optional().meta({
+    title: "Beneficiary Wallet Address",
+    description: "Ethereum address associated with the beneficiary, when available"
   }),
   identity: CreditRetirementReceiptIdentitySchema.optional()
 }).meta({
   title: "Beneficiary",
-  description: "Beneficiary receiving the retirement benefit"
+  description: "Beneficiary receiving the retirement benefit, identified by a hashed identifier with optional wallet address and identity"
 });
 var CreditRetirementReceiptCreditHolderSchema = z.strictObject({
-  wallet_address: EthereumAddressSchema.meta({
+  id_hash: Sha256HashSchema.meta({
+    title: "Credit Holder ID Hash",
+    description: "Anonymized pseudonymous identifier linking this credit holder to off-chain records via a keyed hash"
+  }),
+  wallet_address: EthereumAddressSchema.optional().meta({
     title: "Credit Holder Wallet Address",
     description: "Ethereum address of the wallet that held and surrendered the credits"
   }),
   identity: CreditRetirementReceiptIdentitySchema.optional()
 }).meta({
   title: "Credit Holder",
-  description: "Credit holder wallet and optional identity information"
+  description: "Credit holder information including hashed identifier, optional wallet address, and optional identity"
 });
 var CreditRetirementReceiptCollectionSchema = createReceiptCollectionSchema({
   meta: {
@@ -31564,9 +31572,9 @@ var CreditRetirementReceiptCertificateSchema = CertificateReferenceBaseSchema.sa
     CertificateCollectionItemRetirementSchema,
     (item) => item.slug,
     "Collection slugs within certificate collections must be unique"
-  ).min(1).meta({
+  ).meta({
     title: "Certificate Collections",
-    description: "Collections associated with this certificate, each with retired amounts"
+    description: "Collections associated with this certificate, each with retired amounts. May be empty when this certificate is not assigned to any collection."
   }),
   credits_retired: uniqueBy(
     CreditRetirementReceiptCertificateCreditSchema,
@@ -31588,9 +31596,9 @@ var CreditRetirementReceiptDataSchema = z.strictObject({
     CreditRetirementReceiptCollectionSchema,
     (collection) => collection.slug,
     "Collection slugs must be unique"
-  ).min(1).meta({
+  ).meta({
     title: "Collections",
-    description: "Impact collections referenced by this retirement, each identified by a unique slug"
+    description: "Impact collections referenced by this retirement, each identified by a unique slug. May be empty when no certificate is assigned to a collection."
   }),
   credits: uniqueBy(
     CreditRetirementReceiptCreditSchema,
@@ -31644,6 +31652,17 @@ var CreditRetirementReceiptDataSchema = z.strictObject({
         path: ["certificates", index]
       });
     }
+    const creditsRetiredTotal = certificate.credits_retired.reduce(
+      (sum, credit) => sum + Number(credit.amount),
+      0
+    );
+    if (creditsRetiredTotal > certificate.total_amount) {
+      ctx.addIssue({
+        code: "custom",
+        message: "Sum of certificate.credits_retired[].amount cannot exceed certificate.total_amount",
+        path: ["certificates", index, "credits_retired"]
+      });
+    }
     validateCertificateCollectionSlugs({
       ctx,
       certificateCollections: certificate.collections,
@@ -31656,11 +31675,7 @@ var CreditRetirementReceiptDataSchema = z.strictObject({
         (collectionRetiredTotalsBySlug.get(collectionItem.slug) ?? 0) + Number(collectionItem.retired_amount)
       );
     });
-    const creditsRetiredTotal = certificate.credits_retired.reduce(
-      (sum, credit) => sum + Number(credit.amount),
-      0
-    );
-    if (!nearlyEqual(creditsRetiredTotal, certificateCollectionRetiredTotal)) {
+    if (certificate.collections.length > 0 && !nearlyEqual(creditsRetiredTotal, certificateCollectionRetiredTotal)) {
       ctx.addIssue({
         code: "custom",
         message: "certificates.credits_retired amounts must sum to certificate.collections[].retired_amount",
@@ -31711,27 +31726,29 @@ var CreditRetirementReceiptDataSchema = z.strictObject({
         (creditTotalsBySymbol.get(credit.credit_symbol) ?? 0) + credit.amount
       );
     });
-    totalRetiredFromCertificates += certificateCollectionRetiredTotal;
+    totalRetiredFromCertificates += creditsRetiredTotal;
   });
   validateTotalMatches({
     ctx,
     actualTotal: totalRetiredFromCertificates,
     expectedTotal: data.summary.total_credits_retired,
     path: ["summary", "total_credits_retired"],
-    message: "summary.total_credits_retired must equal sum of certificate.collections[].retired_amount"
-  });
-  validateCollectionsHaveRetiredAmounts({
-    ctx,
-    collections: data.collections,
-    retiredTotalsBySlug: collectionRetiredTotalsBySlug
+    message: "summary.total_credits_retired must equal sum of certificates[].credits_retired[].amount"
   });
+  if (data.collections.length > 0) {
+    validateCollectionsHaveRetiredAmounts({
+      ctx,
+      collections: data.collections,
+      retiredTotalsBySlug: collectionRetiredTotalsBySlug
+    });
+  }
 }).meta({
   title: "Credit Retirement Receipt Data",
   description: "Complete data structure for a credit retirement receipt"
 });
 var CreditRetirementReceiptIpfsSchemaMeta = {
   title: "CreditRetirementReceipt NFT IPFS Record",
-  description: "Complete CreditRetirementReceipt NFT IPFS record including retirement summary, beneficiary and credit holder details (identity optional), credit breakdowns, certificate allocations, and NFT display attributes",
+  description: "Complete CreditRetirementReceipt NFT IPFS record including retirement summary, beneficiary and credit holder details (identity optional), credit breakdowns, certificate allocations, and NFT display attributes. Supports both collection-assigned and no-collection variants.",
   $id: buildSchemaUrl(
     "credit-retirement-receipt/credit-retirement-receipt.schema.json"
   ),