@crediolabs/policy-synth 1.1.0 → 1.1.1

package/dist/install/build-install-policy.d.ts

@@ -112,6 +112,21 @@ export interface InstallCallDescribes {
 export interface BuildInstallPolicyResult {
     /** Unsigned Soroban transaction envelope, base64 XDR. */
     unsignedXdr: string;
+    /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+     *  prove it arrived whole.
+     *
+     *  This envelope runs to several thousand characters, and the only route
+     *  from a tool result onto disk is the caller re-emitting it. A truncated
+     *  copy is not obviously wrong - it fails later as
+     *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+     *  transaction rather than a transport problem. Observed in practice: one of
+     *  two envelopes written in the same session lost its tail and its base64
+     *  length went from a multiple of four to `len % 4 == 3`.
+     *
+     *  Check both before signing. They are cheap, and they turn a silent,
+     *  fatal truncation into a retry. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     /** Smart account contract address (echo). */
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
@@ -168,6 +183,11 @@ export declare function buildRevokePolicyXdr(args: {
 }): Promise<BuildRevokePolicyResult>;
 export interface BuildRevokePolicyResult {
     unsignedXdr: string;
+    /** Same integrity pair as the install result, for the same reason: a revoke
+     *  envelope also has to reach a signer intact, and a truncated copy fails as
+     *  a malformed transaction rather than as a transport error. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     smartAccount: string;
     sourceAccount: string;
     call: {

package/dist/install/build-install-policy.js

@@ -62,6 +62,14 @@ export function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: createHash('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 export async function buildInstallPolicyXdr(args) {
@@ -90,7 +98,7 @@ export async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -119,7 +127,7 @@ export async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },

package/dist/run/schemas.d.ts

@@ -2849,10 +2849,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -4233,12 +4233,12 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
 export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>;
 export declare const RevokePolicyInputSchema: z.ZodEffects<z.ZodObject<{
     /** The smart account contract address (C...). */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;

package/dist/run/schemas.js

@@ -14,6 +14,7 @@
 // This module is the SINGLE source of truth for these shapes. The MCP package
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
+import { StrKey } from '@stellar/stellar-sdk';
 import { z } from 'zod';
 import { isStellarAddress } from "../synth/address.js";
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -471,6 +472,20 @@ export const NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field) => z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(StrKey.isValidContract, `${field} is not a valid contract address: the checksum does not match, so this address does not exist`);
+const accountAddress = (field) => z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(StrKey.isValidEd25519PublicKey, `${field} is not a valid account address: the checksum does not match, so this address does not exist`);
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -532,14 +547,10 @@ export const InstallPolicyInputSchema = z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -673,16 +684,12 @@ export const InstallPolicyInputSchema = z
 export const RevokePolicyInputSchema = z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),

package/dist-cjs/install/build-install-policy.d.ts

@@ -112,6 +112,21 @@ export interface InstallCallDescribes {
 export interface BuildInstallPolicyResult {
     /** Unsigned Soroban transaction envelope, base64 XDR. */
     unsignedXdr: string;
+    /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+     *  prove it arrived whole.
+     *
+     *  This envelope runs to several thousand characters, and the only route
+     *  from a tool result onto disk is the caller re-emitting it. A truncated
+     *  copy is not obviously wrong - it fails later as
+     *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+     *  transaction rather than a transport problem. Observed in practice: one of
+     *  two envelopes written in the same session lost its tail and its base64
+     *  length went from a multiple of four to `len % 4 == 3`.
+     *
+     *  Check both before signing. They are cheap, and they turn a silent,
+     *  fatal truncation into a retry. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     /** Smart account contract address (echo). */
     smartAccount: string;
     /** Source account (echo) - the address that must sign. */
@@ -168,6 +183,11 @@ export declare function buildRevokePolicyXdr(args: {
 }): Promise<BuildRevokePolicyResult>;
 export interface BuildRevokePolicyResult {
     unsignedXdr: string;
+    /** Same integrity pair as the install result, for the same reason: a revoke
+     *  envelope also has to reach a signer intact, and a truncated copy fails as
+     *  a malformed transaction rather than as a transport error. */
+    unsignedXdrLength: number;
+    unsignedXdrSha256: string;
     smartAccount: string;
     sourceAccount: string;
     call: {

package/dist-cjs/install/build-install-policy.js

@@ -68,6 +68,14 @@ function rpcClientFromServer(server, networkPassphrase) {
         },
     };
 }
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr) {
+    return {
+        unsignedXdr,
+        unsignedXdrLength: unsignedXdr.length,
+        unsignedXdrSha256: (0, node_crypto_1.createHash)('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+    };
+}
 /** Build the unsigned transaction envelope for `account.add_context_rule(...)`.
  *  The output XDR is signed by the wallet, not by us. */
 async function buildInstallPolicyXdr(args) {
@@ -96,7 +104,7 @@ async function buildInstallPolicyXdr(args) {
     //    The human approval binds to the exact bytes the wallet will sign.
     const describes = decodeInstallCallDescribes(finalTx, args.installNonce);
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -125,7 +133,7 @@ async function buildRevokePolicyXdr(args) {
     // consumer supplies only the ordinary envelope signature.
     const { finalTx, original, validUntilLedger } = await buildAuthorisedSmartAccountTx(args, 'remove_context_rule', [stellar_sdk_1.xdr.ScVal.scvU32(args.ruleId)], 'revoke_policy');
     return {
-        unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+        ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
         smartAccount: args.smartAccount,
         sourceAccount: args.sourceAccount,
         call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },

package/dist-cjs/run/schemas.d.ts

@@ -2849,10 +2849,10 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
         predicate?: unknown;
     }>, "many">>;
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -4233,12 +4233,12 @@ export declare const InstallPolicyInputSchema: z.ZodEffects<z.ZodEffects<z.ZodOb
 export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>;
 export declare const RevokePolicyInputSchema: z.ZodEffects<z.ZodObject<{
     /** The smart account contract address (C...). */
-    smartAccount: z.ZodString;
+    smartAccount: z.ZodEffects<z.ZodString, string, string>;
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z.ZodString;
+    sourceAccount: z.ZodEffects<z.ZodString, string, string>;
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: z.ZodOptional<z.ZodEnum<["mainnet", "testnet"]>>;

package/dist-cjs/run/schemas.js

@@ -17,6 +17,7 @@
 // them here so it can build the same args envelope the MCP transport builds.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolErrorSchema = exports.GetInterpreterInfoInputSchema = exports.RevokePolicyInputSchema = exports.InstallPolicyInputSchema = exports.DeclarePolicyInputSchema = exports.NETWORK_PASSPHRASES = exports.PINNED_OZ_POLICY_WASM_SHA256 = exports.PINNED_OZ_POLICY_ADDRESS_BY_NETWORK = exports.PINNED_OZ_STELLAR_CONTRACTS_TAG = exports.RPC_URL_BY_NETWORK = exports.PINNED_INTERPRETER_ADDRESS_BY_NETWORK = exports.MAINNET_RPC_URL = exports.TESTNET_RPC_URL = exports.PINNED_INTERPRETER_GRAMMAR_VERSION = exports.PINNED_INTERPRETER_WASM_SHA256 = exports.PINNED_INTERPRETER_MAINNET_ADDRESS = exports.PINNED_INTERPRETER_TESTNET_ADDRESS = exports.ObservedRuleSchema = exports.VerifyPolicyInputSchema = exports.SimulatePolicyInputSchema = exports.PredicateNodeSchema = exports.PredicateLeafSchema = exports.SynthesizePolicyInputSchema = exports.InterpreterOptionsSchema = exports.RecordTransactionInputSchema = exports.ComposeUserResponsesSchema = exports.RecordedTransactionSchema = exports.ParseConfidenceSchema = exports.OnChainEventSchema = exports.TokenMovementSchema = exports.ContractInvocationSchema = exports.ScValSchema = exports.NetworkSchema = void 0;
+const stellar_sdk_1 = require("@stellar/stellar-sdk");
 const zod_1 = require("zod");
 const address_ts_1 = require("../synth/address.js");
 /** Soroban `valid_until` is a u32 ledger sequence; a value above this cannot be
@@ -474,6 +475,20 @@ exports.NETWORK_PASSPHRASES = {
 // `sourceAccount` is the signing wallet (G...).
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/;
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/;
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field) => zod_1.z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(stellar_sdk_1.StrKey.isValidContract, `${field} is not a valid contract address: the checksum does not match, so this address does not exist`);
+const accountAddress = (field) => zod_1.z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(stellar_sdk_1.StrKey.isValidEd25519PublicKey, `${field} is not a valid account address: the checksum does not match, so this address does not exist`);
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -535,14 +550,10 @@ exports.InstallPolicyInputSchema = zod_1.z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: zod_1.z.array(exports.ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: zod_1.z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: zod_1.z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -676,16 +687,12 @@ exports.InstallPolicyInputSchema = zod_1.z
 exports.RevokePolicyInputSchema = zod_1.z
     .object({
     /** The smart account contract address (C...). */
-    smartAccount: zod_1.z
-        .string()
-        .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: zod_1.z
-        .string()
-        .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: exports.NetworkSchema.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crediolabs/policy-synth",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "license": "MIT",
   "description": "Off-chain TypeScript synthesis core for the OZ Accounts Policy Builder. Records Soroban transactions, synthesises the minimal policy that permits exactly that flow, verifies it, and returns an unsigned install transaction.",
   "type": "module",

package/src/install/build-install-policy.ts

@@ -182,12 +182,40 @@ export interface InstallCallDescribes {
   installNonce: number
 }
 
+/** `unsignedXdr` plus the length and digest that prove it arrived whole. */
+function xdrIntegrity(unsignedXdr: string): {
+  unsignedXdr: string
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
+} {
+  return {
+    unsignedXdr,
+    unsignedXdrLength: unsignedXdr.length,
+    unsignedXdrSha256: createHash('sha256').update(unsignedXdr, 'utf8').digest('hex'),
+  }
+}
+
 /** Output of the install-policy build. The unsigned XDR is the wallet's
  *  input; the captured auth nonce + invocation root make the response
  *  self-describing for callers that want to inspect what they signed. */
 export interface BuildInstallPolicyResult {
   /** Unsigned Soroban transaction envelope, base64 XDR. */
   unsignedXdr: string
+  /** Length and SHA-256 of `unsignedXdr`, so a caller that has to move it can
+   *  prove it arrived whole.
+   *
+   *  This envelope runs to several thousand characters, and the only route
+   *  from a tool result onto disk is the caller re-emitting it. A truncated
+   *  copy is not obviously wrong - it fails later as
+   *  "failed to decode XDR: xdr value invalid", which reads like a malformed
+   *  transaction rather than a transport problem. Observed in practice: one of
+   *  two envelopes written in the same session lost its tail and its base64
+   *  length went from a multiple of four to `len % 4 == 3`.
+   *
+   *  Check both before signing. They are cheap, and they turn a silent,
+   *  fatal truncation into a retry. */
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
   /** Smart account contract address (echo). */
   smartAccount: string
   /** Source account (echo) - the address that must sign. */
@@ -258,7 +286,7 @@ export async function buildInstallPolicyXdr(
   const describes = decodeInstallCallDescribes(finalTx, args.installNonce)
 
   return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'add_context_rule' },
@@ -302,7 +330,7 @@ export async function buildRevokePolicyXdr(args: {
   )
 
   return {
-    unsignedXdr: finalTx.toEnvelope().toXDR().toString('base64'),
+    ...xdrIntegrity(finalTx.toEnvelope().toXDR().toString('base64')),
     smartAccount: args.smartAccount,
     sourceAccount: args.sourceAccount,
     call: { contract: args.smartAccount, fn: 'remove_context_rule', ruleId: args.ruleId },
@@ -314,6 +342,11 @@ export async function buildRevokePolicyXdr(args: {
 
 export interface BuildRevokePolicyResult {
   unsignedXdr: string
+  /** Same integrity pair as the install result, for the same reason: a revoke
+   *  envelope also has to reach a signer intact, and a truncated copy fails as
+   *  a malformed transaction rather than as a transport error. */
+  unsignedXdrLength: number
+  unsignedXdrSha256: string
   smartAccount: string
   sourceAccount: string
   call: { contract: string; fn: 'remove_context_rule'; ruleId: number }

package/src/run/schemas.ts

@@ -15,6 +15,7 @@
 // imports them here so its tool-shape bindings stay in step; the CLI imports
 // them here so it can build the same args envelope the MCP transport builds.
 
+import { StrKey } from '@stellar/stellar-sdk'
 import { z } from 'zod'
 import { isStellarAddress } from '../synth/address.ts'
 
@@ -550,6 +551,29 @@ export const NETWORK_PASSPHRASES: Record<Network, string> = {
 const STELLAR_CONTRACT_ADDRESS = /^C[2-7A-Z]{55}$/
 const STELLAR_ACCOUNT_ADDRESS = /^G[2-7A-Z]{55}$/
 
+// The regexes above check SHAPE only. A wrong-but-well-formed address - the
+// classic case being one an agent reproduced from memory - passes them and then
+// fails the SDK's StrKey decoder deep inside the build, where the throw is
+// caught by the tool envelope and reported as a bare "invalid checksum" naming
+// no field. A caller holding several addresses then cannot tell which one is
+// wrong. Validating the checksum HERE keeps the field name attached.
+const contractAddress = (field: string) =>
+  z
+    .string()
+    .regex(STELLAR_CONTRACT_ADDRESS, `${field} must be a Stellar contract address (C...)`)
+    .refine(
+      StrKey.isValidContract,
+      `${field} is not a valid contract address: the checksum does not match, so this address does not exist`
+    )
+const accountAddress = (field: string) =>
+  z
+    .string()
+    .regex(STELLAR_ACCOUNT_ADDRESS, `${field} must be a Stellar account address (G...)`)
+    .refine(
+      StrKey.isValidEd25519PublicKey,
+      `${field} is not a valid account address: the checksum does not match, so this address does not exist`
+    )
+
 // ===== declare_policy =====
 //
 // The declarative front-end: the constraint stated outright, with no
@@ -613,14 +637,10 @@ export const InstallPolicyInputSchema = z
      *  result says so rather than reporting "no overlaps found". */
     existingRules: z.array(ObservedRuleSchema).optional(),
     /** The smart account contract address (C...) that will receive the rule. */
-    smartAccount: z
-      .string()
-      .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The signer that authorises the install (G... wallet). Used only for
      *  sequence number + auth nonce simulation; never persisted, never signed. */
-    sourceAccount: z
-      .string()
-      .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the install. Selects which interpreter pin and
      *  which RPC URL are valid by default. Defaults to `testnet` so the
      *  pre-mainnet callers keep working: they were always pointing at
@@ -760,16 +780,12 @@ export type InstallPolicyInput = z.infer<typeof InstallPolicyInputSchema>
 export const RevokePolicyInputSchema = z
   .object({
     /** The smart account contract address (C...). */
-    smartAccount: z
-      .string()
-      .regex(STELLAR_CONTRACT_ADDRESS, 'smartAccount must be a Stellar contract address (C...)'),
+    smartAccount: contractAddress('smartAccount'),
     /** The wallet that will sign the removal. The ACCOUNT decides whether it
      *  accepts that signer; this schema does not assert a rule it cannot
      *  verify, since the account's source is not in this repo. Proven on
      *  testnet: the account's deployer can revoke. */
-    sourceAccount: z
-      .string()
-      .regex(STELLAR_ACCOUNT_ADDRESS, 'sourceAccount must be a Stellar account address (G...)'),
+    sourceAccount: accountAddress('sourceAccount'),
     /** Target network for the revoke. Same `testnet`-default as install,
      *  so pre-mainnet callers keep working without an explicit flag. */
     network: NetworkSchema.optional(),