Guard outgoing transfer actor and default to tracked principal

Author: warmidris

docs/AGENT-PIPE-TEST-LOG.md

@@ -0,0 +1,24 @@
+# Agent Pipe Test Log (Warm Idris)
+
+Purpose: capture real-world StackFlow pipe test outcomes so onboarding for other agents is based on observed behavior, not assumptions.
+
+## Per-test template
+
+- Timestamp (UTC):
+- Counterparty:
+- Pipe identifier / contract:
+- Scenario:
+- Preconditions:
+- Action executed:
+- Expected result:
+- Observed result:
+- Artifacts (txid, signatures, nonce, logs):
+- Pass/Fail:
+- Root cause (if fail):
+- Fix / mitigation:
+- Process improvement for future agents:
+
+---
+
+## Run log
+

packages/stackflow-agent/README.md

@@ -106,7 +106,7 @@ await agent.openPipe({
 const outgoing = agent.buildOutgoingTransfer({
   pipeId: tracked.pipeId,
   amount: "25",
-  actor: tracked.localPrincipal,
+  // actor defaults to tracked.localPrincipal
 });
 ```
 
@@ -135,5 +135,6 @@ const result = await agent.acceptIncomingTransfer({
 4. Watcher retries are idempotent for already-disputed closures (same closure txid is skipped on later polls).
 5. Read-only polling isolates per-pipe failures (`getPipeState` errors on one pipe do not stop others).
 6. Event scan mode intentionally holds the cursor when any dispute submission errors occur, so failed disputes are retried on next run.
-7. Incoming transfer validation enforces tracked contract/pipe/principals/token consistency; mismatched `pipeId`, `pipeKey`, `actor`, or token payloads are rejected.
-8. For production hardening, add alerting, signer balance checks, and idempotency audit logs.
+7. `buildOutgoingTransfer(...)` defaults `actor` to the tracked local principal and rejects mismatched actor values.
+8. Incoming transfer validation enforces tracked contract/pipe/principals/token consistency; mismatched `pipeId`, `pipeKey`, `actor`, or token payloads are rejected.
+9. For production hardening, add alerting, signer balance checks, and idempotency audit logs.

packages/stackflow-agent/src/agent-service.js

@@ -88,7 +88,7 @@ export class StackflowAgentService {
   buildOutgoingTransfer({
     pipeId,
     amount,
-    actor,
+    actor = null,
     action = "1",
     secret = null,
     validAfter = null,
@@ -134,6 +134,14 @@ export class StackflowAgentService {
     const nextTheir = currentTheir + transferAmount;
     const nextNonce = currentNonce + 1n;
 
+    const normalizedActor =
+      actor == null || String(actor).trim() === ""
+        ? tracked.localPrincipal
+        : assertNonEmptyString(actor, "actor");
+    if (normalizedActor !== tracked.localPrincipal) {
+      throw new Error("actor must match tracked local principal");
+    }
+
     return {
       contractId: tracked.contractId,
       pipeKey: tracked.pipeKey,
@@ -144,7 +152,7 @@ export class StackflowAgentService {
       theirBalance: nextTheir.toString(10),
       nonce: nextNonce.toString(10),
       action: toUnsignedString(action, "action"),
-      actor: assertNonEmptyString(actor, "actor"),
+      actor: normalizedActor,
       secret,
       validAfter,
       beneficialOnly: beneficialOnly === true,

tests/stackflow-agent.test.ts

@@ -965,9 +965,9 @@ describe("stackflow agent", () => {
     const outgoing = agent.buildOutgoingTransfer({
       pipeId,
       amount: "25",
-      actor: "ST1LOCAL",
     });
 
+    expect(outgoing.actor).toBe("ST1LOCAL");
     expect(outgoing.myBalance).toBe("75");
     expect(outgoing.theirBalance).toBe("25");
     expect(outgoing.nonce).toBe("1");
@@ -992,6 +992,71 @@ describe("stackflow agent", () => {
     store.close();
   });
 
+  it("rejects outgoing transfer requests with actor mismatch", () => {
+    const dbFile = tempDbFile("agent-send-actor-mismatch");
+    const store = new AgentStateStore({ dbFile });
+
+    const contractId = "ST1TESTABC.contract";
+    const pipeKey = {
+      "principal-1": "ST1LOCAL",
+      "principal-2": "ST1OTHER",
+      token: null,
+    };
+    const pipeId = buildPipeId({ contractId, pipeKey });
+
+    store.upsertTrackedPipe({
+      pipeId,
+      contractId,
+      pipeKey,
+      localPrincipal: "ST1LOCAL",
+      counterpartyPrincipal: "ST1OTHER",
+      token: null,
+    });
+
+    store.upsertSignatureState({
+      contractId,
+      pipeKey,
+      forPrincipal: "ST1LOCAL",
+      withPrincipal: "ST1OTHER",
+      token: null,
+      myBalance: "100",
+      theirBalance: "0",
+      nonce: "0",
+      action: "1",
+      actor: "ST1LOCAL",
+      mySignature: "0x" + "11".repeat(65),
+      theirSignature: "0x" + "22".repeat(65),
+      secret: null,
+      validAfter: null,
+      beneficialOnly: false,
+    });
+
+    const agent = new StackflowAgentService({
+      stateStore: store,
+      signer: {
+        async sip018Sign() {
+          return "0x" + "44".repeat(65);
+        },
+        async submitDispute() {
+          return { txid: "0x1" };
+        },
+        async callContract() {
+          return { ok: true };
+        },
+      },
+    });
+
+    expect(() =>
+      agent.buildOutgoingTransfer({
+        pipeId,
+        amount: "25",
+        actor: "ST1THIRD",
+      }),
+    ).toThrow("actor must match tracked local principal");
+
+    store.close();
+  });
+
   it("defaults watcher interval to one hour", () => {
     const dbFile = tempDbFile("agent-interval");
     const store = new AgentStateStore({ dbFile });