feat(PR30): XRPL escrow budget fields in PolicyGrantLike (#48)

* feat(PR30): add budgetMinor, budgetEscrowRef, authorizedGateway, offlineMaxSinglePayment to PolicyGrantLike

XRPL-escrow budget enforcement requires these PA-signed fields in the PolicyGrant
so the Trust Gateway can enforce ceilings from a tamper-proof source rather than
trusting agent-reported values.

- PolicyGrantLike: budgetMinor, budgetCurrency, budgetEscrowRef, authorizedGateway,
  offlineMaxSinglePayment, offlineMaxSinglePaymentCurrency
- policyGrantForVerificationSchema: Zod validators for all six fields (numeric strings
  validated via regex)
- createPolicyGrant / CreatePolicyGrantInput: factory and input type updated

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix: review corrections — JSDoc consistency and rail-agnostic wording

- types.ts: authorizedGateway — remove XRPL-specific "address" wording, use rail-agnostic description
- types.ts: offlineMaxSinglePayment — "(drops)" → "minor units" (rail-agnostic)
- types.ts: budgetEscrowRef example — add lockId to eth example for consistency with spec
- createPolicyGrant.ts: add missing JSDoc for authorizedGateway, offlineMaxSinglePayment,
  offlineMaxSinglePaymentCurrency (other new fields had docs, these three did not)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: NAOR YUVAL <naoryuval@NAORs-MacBook-Air.local>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

src/protocol/schema/verifySchemas.ts

@@ -25,6 +25,12 @@ export const policyGrantForVerificationSchema = z
     revocationEndpoint: z.string().url().optional(),
     allowedPurposes: z.array(z.string()).optional(),
     anchorRef: z.string().optional(),
+    budgetMinor: z.string().regex(/^\d+$/).optional(),
+    budgetCurrency: z.string().optional(),
+    budgetEscrowRef: z.string().optional(),
+    authorizedGateway: z.string().optional(),
+    offlineMaxSinglePayment: z.string().regex(/^\d+$/).optional(),
+    offlineMaxSinglePaymentCurrency: z.string().optional(),
   })
   .refine((g) => g.expiresAt != null || g.expiresAtISO != null, {
     message: "policy_grant_missing_expiry",

src/sdk/createPolicyGrant.ts

@@ -12,6 +12,18 @@ export interface CreatePolicyGrantInput {
   revocationEndpoint?: string;
   allowedPurposes?: string[];
   anchorRef?: string;
+  /** Total authorized spend in minor units (e.g. drops for XRP). Signed by the PA. */
+  budgetMinor?: string;
+  /** Currency code for budgetMinor (e.g. "XRP"). Required when budgetMinor is set. */
+  budgetCurrency?: string;
+  /** On-chain escrow locking budgetMinor. Format: "xrpl:escrow:{account}:{sequence}". Signed by the PA. */
+  budgetEscrowRef?: string;
+  /** Address of the only gateway authorized to spend against this grant's escrow. Rail-specific format. PA-signed. */
+  authorizedGateway?: string;
+  /** PA-signed per-transaction cap for offline merchant acceptance, in minor units (see offlineMaxSinglePaymentCurrency). */
+  offlineMaxSinglePayment?: string;
+  /** Currency code for offlineMaxSinglePayment (e.g. "XRP"). */
+  offlineMaxSinglePaymentCurrency?: string;
 }
 
 /**
@@ -30,5 +42,11 @@ export function createPolicyGrant(input: CreatePolicyGrantInput): PolicyGrantLik
     ...(input.revocationEndpoint ? { revocationEndpoint: input.revocationEndpoint } : {}),
     ...(input.allowedPurposes ? { allowedPurposes: input.allowedPurposes } : {}),
     ...(input.anchorRef ? { anchorRef: input.anchorRef } : {}),
+    ...(input.budgetMinor ? { budgetMinor: input.budgetMinor } : {}),
+    ...(input.budgetCurrency ? { budgetCurrency: input.budgetCurrency } : {}),
+    ...(input.budgetEscrowRef ? { budgetEscrowRef: input.budgetEscrowRef } : {}),
+    ...(input.authorizedGateway ? { authorizedGateway: input.authorizedGateway } : {}),
+    ...(input.offlineMaxSinglePayment ? { offlineMaxSinglePayment: input.offlineMaxSinglePayment } : {}),
+    ...(input.offlineMaxSinglePaymentCurrency ? { offlineMaxSinglePaymentCurrency: input.offlineMaxSinglePaymentCurrency } : {}),
   };
 }

src/verifier/types.ts

@@ -16,6 +16,24 @@ export interface PolicyGrantLike {
   revocationEndpoint?: string;
   allowedPurposes?: string[];
   anchorRef?: string; // "hcs:{topicId}:{seq}" | "xrpl:nft:{tokenId}"
+  /** Total authorized spend for this grant in minor units (e.g. drops for XRP). PA-signed. */
+  budgetMinor?: string;
+  /** Currency code for budgetMinor (e.g. "XRP"). Required when budgetMinor is set. */
+  budgetCurrency?: string;
+  /**
+   * On-chain budget escrow reference — proof that budgetMinor is locked on-chain.
+   * Format is rail-specific:
+   *   XRPL:    "xrpl:escrow:{account}:{sequence}"
+   *   (future) "eth:timelock:{contract}:{lockId}"
+   * Included in the PA signature, making the escrow commitment tamper-evident.
+   */
+  budgetEscrowRef?: string;
+  /** Address of the only gateway authorized to spend against this grant's escrow. Rail-specific format. PA-signed. */
+  authorizedGateway?: string;
+  /** PA-signed per-transaction cap for offline merchant acceptance, in minor units (see offlineMaxSinglePaymentCurrency). */
+  offlineMaxSinglePayment?: string;
+  /** Currency for offlineMaxSinglePayment (e.g. "XRP"). */
+  offlineMaxSinglePaymentCurrency?: string;
 }
 
 /** Shared verification result for all verifiers. Use with CLI and callers. */