Merge pull request #343 from anonfedora/feat/memo-types-middleware-and-examples

features

Author: Dami24-hub

README.md

@@ -199,6 +199,22 @@ Places a manage-sell offer on the Stellar DEX. This example creates an offer to
 npx ts-node scripts/examples/place_dex_offer.ts
 ```
 
+### `query_contract.ts` — soroban_query
+
+Performs a read-only query on a Soroban contract without broadcasting. This example calls `get_state` on a deployed escrow contract to verify state after deployment. Pass the contract address via `CONTRACT_ID`:
+
+```bash
+CONTRACT_ID=C... npx ts-node scripts/examples/query_contract.ts
+```
+
+### `fee_bump.ts` — fee_bump
+
+Wraps a transaction in a fee-bump envelope for sponsored retry flows. This is useful when the agent needs to pay fees on behalf of a transaction signed by a different account. Pass the inner transaction XDR via `INNER_TX_XDR`:
+
+```bash
+INNER_TX_XDR=AAAA... npx ts-node scripts/examples/fee_bump.ts
+```
+
 ---
 
 ## E2E Tests

backend/agent.ts

@@ -127,6 +127,26 @@ export interface AgentResult {
   correlationId?: string;
 }
 
+// ─── Middleware types ─────────────────────────────────────────────────────────────
+
+/**
+ * Task middleware function type.
+ *
+ * Middleware functions are executed in registration order before the task
+ * is dispatched to the appropriate tool. Each middleware receives the task
+ * and a `next` function to continue execution. Calling `next()` passes control
+ * to the next middleware or the actual task execution. If a middleware returns
+ * a result without calling `next()`, it short-circuits execution.
+ *
+ * @param task - The task to be executed
+ * @param next - Function to call the next middleware or the actual task
+ * @returns The result of task execution or middleware short-circuit
+ */
+export type TaskMiddleware = (
+  task: AgentTask,
+  next: () => Promise<AgentResult>
+) => Promise<AgentResult>;
+
 // ─── Payload sanitisation ─────────────────────────────────────────────────────
 
 const SECRET_KEY_RE = /^(?<prefix>.*?["':\s]?)(?<secret>S[ A-Z2-7]{55})(?<suffix>["'\s]?.*)$/i;
@@ -178,6 +198,9 @@ export class PayFiAgent extends EventEmitter {
   // reference — EventEmitter requires identity equality for removal.
   private readonly _boundHandlers = new Map<string, (...args: unknown[]) => void>();
 
+  // Middleware array for pre/post task execution hooks
+  private middlewares: TaskMiddleware[] = [];
+
   constructor() {
     super();
 
@@ -337,6 +360,22 @@ export class PayFiAgent extends EventEmitter {
     logger.info("Agent draining — rejecting new tasks");
   }
 
+  /**
+   * Register a middleware function for pre/post task execution hooks.
+   *
+   * Middleware functions are executed in registration order before the task
+   * is dispatched to the appropriate tool. Each middleware can:
+   * - Inspect and modify the task
+   * - Short-circuit execution by returning a result without calling next()
+   * - Call next() to continue to the next middleware or actual task execution
+   *
+   * @param middleware - Middleware function to register
+   */
+  use(middleware: TaskMiddleware): void {
+    this.middlewares.push(middleware);
+    logger.info("Middleware registered", { totalMiddlewares: this.middlewares.length });
+  }
+
   async waitForPendingTasks(): Promise<void> {
     if (this.activeTasks === 0 && this.taskQueue.length === 0) return;
     logger.info("Waiting for pending tasks to finish", {
@@ -450,74 +489,116 @@ export class PayFiAgent extends EventEmitter {
   ): Promise<AgentResult> {
     this.activeTasks++;
     taskLog.info({ taskType: task.type }, "Running task");
-    try {
-      let data: unknown;
-
-      switch (task.type) {
-        case "stellar_payment": {
-          const p = task.payload as Record<string, unknown>;
-          assertWithinSpendingLimit(p?.amount);
-          const paymentResult = await this.paymentTool.execute(task.payload);
-          data = {
-            ...paymentResult,
-            network: config.STELLAR_NETWORK,
-          };
-          break;
-        }
 
-        case "soroban_invoke": {
-          data = await this.sorobanTool.execute(task.payload);
-          break;
-        }
+    // ── Compose middleware chain ────────────────────────────────────────────────
+    const executeTask = async (): Promise<AgentResult> => {
+      try {
+        let data: unknown;
+
+        switch (task.type) {
+          case "stellar_payment": {
+            const p = task.payload as Record<string, unknown>;
+            assertWithinSpendingLimit(p?.amount);
+            const paymentResult = await this.paymentTool.execute(task.payload);
+            data = {
+              ...paymentResult,
+              network: config.STELLAR_NETWORK,
+            };
+            break;
+          }
 
-        case "soroban_query":
-          data = await this.sorobanQueryTool.query(task.payload);
-          break;
+          case "soroban_invoke": {
+            data = await this.sorobanTool.execute(task.payload);
+            break;
+          }
 
-        case "x402_respond": {
-          const p = task.payload as Record<string, unknown>;
-          assertWithinSpendingLimit(p?.amount);
-          data = await this.x402Tool.respond(task.payload);
-          break;
-        }
+          case "soroban_query":
+            data = await this.sorobanQueryTool.query(task.payload);
+            break;
 
-        case "account_info":
-          data = await this.accountInfoTool.fetch();
-          break;
+          case "x402_respond": {
+            const p = task.payload as Record<string, unknown>;
+            assertWithinSpendingLimit(p?.amount);
+            data = await this.x402Tool.respond(task.payload);
+            break;
+          }
 
-        case "change_trust":
-          data = await this.trustlineTool.execute(task.payload);
-          break;
+          case "account_info":
+            data = await this.accountInfoTool.fetch();
+            break;
+
+          case "change_trust":
+            data = await this.trustlineTool.execute(task.payload);
+            break;
 
-        case "multisig_payment":
-          data = await this.multiSigTool.execute(task.payload);
+          case "multisig_payment":
+            data = await this.multiSigTool.execute(task.payload);
           break;
 
 
-        case "batch_payment":
-          data = await this.batchPaymentTool.execute(task.payload);
-          break;
+          case "batch_payment":
+            data = await this.batchPaymentTool.execute(task.payload);
+            break;
 
-        case "balance_check":
-          data = await this.balanceCheckTool.getBalance(task.payload);
-          break;
+          case "balance_check":
+            data = await this.balanceCheckTool.getBalance(task.payload);
+            break;
 
-        case "path_payment":
-          data = await this.pathPaymentTool.execute(task.payload);
-          break;
+          case "path_payment":
+            data = await this.pathPaymentTool.execute(task.payload);
+            break;
 
-        case "fee_bump":
-          data = await this.feeBumpTool.execute(task.payload);
-          break;
+          case "fee_bump":
+            data = await this.feeBumpTool.execute(task.payload);
+            break;
 
-        case "dex_offer":
-          data = await this.dexOfferTool.execute(task.payload);
-          break;
+          case "dex_offer":
+            data = await this.dexOfferTool.execute(task.payload);
+            break;
 
-        default:
-          throw new Error(`Unknown task type: ${(task as AgentTask).type}`);
+          default:
+            throw new Error(`Unknown task type: ${(task as AgentTask).type}`);
+        }
+
+        taskLog.info({ taskType: task.type }, "Task completed");
+        const result: AgentResult = { success: true, taskType: task.type, data, correlationId };
+        this.emit("task:complete", result);
+
+        saveResult({ ...result, timestamp: new Date().toISOString() });
+        void dispatchWebhook(result);
+
+        return result;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const safe = redactSecretString(message);
+        const sanitized = sanitizePayload(task.payload);
+        taskLog.error(
+          { taskType: task.type, error: safe, sanitizedPayload: sanitized },
+          "Task failed"
+        );
+        const result: AgentResult = {
+          success: false,
+          taskType: task.type,
+          error: safe,
+          errorType: getErrorType(err),
+          correlationId,
+        };
+        this.emit("task:failed", result);
+        void dispatchWebhook(result);
+        return result;
       }
+    };
 
+    // Build middleware chain: middleware[n] -> middleware[n-1] -> ... -> executeTask
+    let chain: () => Promise<AgentResult> = executeTask;
+    for (let i = this.middlewares.length - 1; i >= 0; i--) {
+      const middleware = this.middlewares[i];
+      const next: () => Promise<AgentResult> = chain;
+      chain = () => middleware(task, next);
+    }
+
+    try {
+      return await chain();
       taskLog.info({ taskType: task.type }, "Task completed");
       const result: AgentResult = { success: true, taskType: task.type, data, correlationId };
       this.emit("task:complete", result);

backend/tools/PathPaymentTool.ts

@@ -42,10 +42,8 @@ export const PathPaymentInputSchema = z.object({
     .regex(/^(?!0(\.0+)?$)\d+(\.\d{1,7})?$/, "destMinAmount must be a valid Stellar decimal")
     .refine((v) => parseFloat(v) > 0, "destMinAmount must be greater than zero"),
   path: z.array(AssetSchema).optional().default([]),
-  memo: z
-    .string()
-    .refine((v) => Buffer.byteLength(v, "utf8") <= 28, "Memo must be at most 28 bytes")
-    .optional(),
+  memoType: z.enum(["text", "id", "hash", "return"]).optional().default("text"),
+  memo: z.union([z.string(), z.number()]).optional(),
 });
 
 export type PathPaymentInput = z.infer<typeof PathPaymentInputSchema>;
@@ -60,6 +58,67 @@ function toAsset(a: { code: string; issuer?: string | undefined }): Asset {
   return new Asset(a.code, a.issuer);
 }
 
+/**
+ * Build a Stellar Memo object based on memoType and value.
+ *
+ * @param memoType - Type of memo: "text", "id", "hash", or "return"
+ * @param memoValue - Memo value (string for text/return/hash, number for id)
+ * @returns Memo instance or null if memoValue is undefined
+ */
+function buildMemo(memoType: string, memoValue: string | number | undefined): Memo | null {
+  if (memoValue === undefined) {
+    return null;
+  }
+
+  switch (memoType) {
+    case "id":
+      if (typeof memoValue !== "number") {
+        throw new Error("Memo ID must be a number");
+      }
+      // Convert to unsigned 64-bit integer
+      const id = BigInt(memoValue);
+      if (id < 0n || id > 18446744073709551615n) {
+        throw new Error("Memo ID must be a 64-bit unsigned integer (0 to 2^64-1)");
+      }
+      return Memo.id(id.toString());
+    case "hash":
+      if (typeof memoValue !== "string") {
+        throw new Error("Memo hash must be a string");
+      }
+      // Remove 0x prefix if present and validate length
+      const hashHex = memoValue.replace(/^0x/, "");
+      if (hashHex.length !== 64) {
+        throw new Error("Memo hash must be a 32-byte hex string (64 hex characters)");
+      }
+      if (!/^[0-9a-fA-F]{64}$/.test(hashHex)) {
+        throw new Error("Memo hash must contain only valid hex characters");
+      }
+      return Memo.hash(hashHex);
+    case "return":
+      if (typeof memoValue !== "string") {
+        throw new Error("Memo return must be a string");
+      }
+      // Remove 0x prefix if present and validate length
+      const returnHex = memoValue.replace(/^0x/, "");
+      if (returnHex.length !== 64) {
+        throw new Error("Memo return must be a 32-byte hex string (64 hex characters)");
+      }
+      if (!/^[0-9a-fA-F]{64}$/.test(returnHex)) {
+        throw new Error("Memo return must contain only valid hex characters");
+      }
+      return Memo.return(returnHex);
+    case "text":
+    default:
+      if (typeof memoValue !== "string") {
+        throw new Error("Memo text must be a string");
+      }
+      if (Buffer.byteLength(memoValue, "utf8") > 28) {
+        throw new Error("Memo text must be at most 28 bytes");
+      }
+      return Memo.text(memoValue);
+  }
+}
+
 // ─── Tool implementation ──────────────────────────────────────────────────────
 
 export class PathPaymentTool {
@@ -103,8 +162,11 @@ export class PathPaymentTool {
         })
       );
 
-      if (input.memo) {
-        builder.addMemo(Memo.text(input.memo));
+      if (input.memo !== undefined) {
+        const memo = buildMemo(input.memoType, input.memo);
+        if (memo) {
+          builder.addMemo(memo);
+        }
       }
 
       return builder.setTimeout(30).build();