Fix: MailboxRouterTransport ARC-4 put encoding and burn accounts

Real algod rejected puts (missing uint16 length prefix on byte[]) and burns
(depositor absent from foreign accounts for the inner MBR refund).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 0xLeif

specs/algochat/algochat.spec.md

@@ -214,6 +214,7 @@ Provides the TypeScript implementation of the AlgoChat encrypted-messaging proto
 | `planMailboxPut` | Pure mailbox put planning operation defined below. |
 | `planMailboxFanout` | Pure mailbox atomic fan-out planning operation defined below. |
 | `mailboxMethodSelector` | ARC-4 method selector derivation defined below. |
+| `arc4EncodeDynamicBytes` | ARC-4-encodes a dynamic `byte[]` app arg as `uint16_be(len) ‖ bytes` for router puts. |
 | `MAILBOX_METHODS` | Published protocol value, size boundary, preset, or search default. |
 | `MAILBOX_MSG_KEY_DOMAIN` | Published protocol value, size boundary, preset, or search default. |
 | `MAILBOX_ID_DOMAIN` | Published protocol value, size boundary, preset, or search default. |
@@ -295,3 +296,4 @@ Then SendQueue processes eligible entries in order, records failures for retry,
 | 2 | 2026-07-14 | Added the stable full-library contract for the existing implementation and tests |
 | 3 | 2026-07-14 | CHG-0002-replace-the-incomplete-no-spec-rationale-with-a-stable-full-library-algochat-con: Replace the incomplete no-spec rationale with a stable full-library AlgoChat contract covering every existing source, export, invariant, failure mode, and native test boundary |
 | 2026-07-19 | CHG-0006-add-an-opt-in-mailboxroutertransport-speaking-the-raven-mailbox-protocol-per-co: Add an opt-in MailboxRouterTransport speaking the raven mailbox protocol: per-counter key derivation, MBR-exact put groups, atomic N-recipient fan-out, burn/reclaim/status, off-chain box reads, gated behind service config |
+| 2026-07-19 | Fix MailboxRouterTransport for real algod: ARC-4-encode put envelopes; include depositor in burn/reclaim foreign accounts for inner refunds |

src/blockchain/mailbox.test.ts

@@ -25,6 +25,7 @@ import {
     InvalidViewSecretError,
     deriveMailboxId,
     deriveMsgKey,
+    arc4EncodeDynamicBytes,
     mailboxMbr,
     mailboxMethodSelector,
     planMailboxFanout,
@@ -171,6 +172,17 @@ describe('mailbox put planning', () => {
     });
 });
 
+describe('ARC-4 encoding', () => {
+    test('arc4EncodeDynamicBytes prefixes a big-endian uint16 length', () => {
+        const payload = new Uint8Array([1, 2, 3, 4]);
+        const encoded = arc4EncodeDynamicBytes(payload);
+        expect(encoded.length).toBe(6);
+        expect(encoded[0]).toBe(0);
+        expect(encoded[1]).toBe(4);
+        expect(Buffer.from(encoded.subarray(2)).equals(Buffer.from(payload))).toBe(true);
+    });
+});
+
 describe('ARC-4 selectors', () => {
     test('mailboxMethodSelector matches algosdk for every router method', () => {
         const expectations: Array<[string, algosdk.ABIMethodParams]> = [

src/blockchain/mailbox.ts

@@ -155,6 +155,24 @@ export function mailboxMethodSelector(signature: string): Uint8Array {
     return sha512_256(new TextEncoder().encode(signature)).slice(0, 4);
 }
 
+/**
+ * ARC-4-encodes a dynamic `byte[]` application argument as
+ * `uint16_be(length) ‖ bytes`. Required for raven router `mailboxPut`
+ * envelopes (static `byte[32]` args are passed raw).
+ *
+ * @param bytes - Raw payload bytes (length must fit in a uint16)
+ * @returns Length-prefixed ARC-4 dynamic bytes
+ */
+export function arc4EncodeDynamicBytes(bytes: Uint8Array): Uint8Array {
+    if (bytes.length > 0xffff) {
+        throw new MailboxEnvelopeError(bytes.length);
+    }
+    const encoded = new Uint8Array(2 + bytes.length);
+    new DataView(encoded.buffer).setUint16(0, bytes.length, false);
+    encoded.set(bytes, 2);
+    return encoded;
+}
+
 /**
  * Derives the per-message msg key from a shared view secret and counter.
  *

src/index.ts

@@ -222,6 +222,7 @@ export {
     planMailboxPut,
     planMailboxFanout,
     mailboxMethodSelector,
+    arc4EncodeDynamicBytes,
     type MailboxLeg,
     type MailboxLegPlan,
 } from './blockchain/mailbox.js';

src/services/mailbox-router.service.test.ts

@@ -15,6 +15,7 @@ import {
     MAILBOX_MAX_ENVELOPE_SIZE,
     MailboxError,
     MailboxFanoutLimitError,
+    arc4EncodeDynamicBytes,
     mailboxMbr,
     mailboxMethodSelector,
     planMailboxPut,
@@ -124,7 +125,7 @@ describe('MailboxRouterTransport.send', () => {
         expect(args.length).toBe(3);
         expect(Buffer.from(args[0]).equals(Buffer.from(PUT_SELECTOR))).toBe(true);
         expect(Buffer.from(args[1]).equals(Buffer.from(expected.mailboxId))).toBe(true);
-        expect(Buffer.from(args[2]).equals(Buffer.from(envelope))).toBe(true);
+        expect(Buffer.from(args[2]).equals(Buffer.from(arc4EncodeDynamicBytes(envelope)))).toBe(true);
 
         const boxes = call.applicationCall?.boxes ?? [];
         expect(boxes.length).toBe(1);
@@ -177,7 +178,7 @@ describe('MailboxRouterTransport.sendFanout', () => {
             const args = call.applicationCall?.appArgs ?? [];
             expect(Buffer.from(args[0]).equals(Buffer.from(PUT_SELECTOR))).toBe(true);
             expect(Buffer.from(args[1]).equals(Buffer.from(plan.mailboxId))).toBe(true);
-            expect(Buffer.from(args[2]).equals(Buffer.from(legs[i].envelope))).toBe(true);
+            expect(Buffer.from(args[2]).equals(Buffer.from(arc4EncodeDynamicBytes(legs[i].envelope)))).toBe(true);
         }
         // distinct recipients, distinct mailboxes
         const ids = result.legs.map((leg) => Buffer.from(leg.mailboxId).toString('hex'));
@@ -199,12 +200,20 @@ describe('MailboxRouterTransport.sendFanout', () => {
 });
 
 describe('MailboxRouterTransport burn and reclaim', () => {
-    test('burn submits the proof with the mailbox box reference', async () => {
+    test('burn submits the proof with the mailbox box reference and depositor account', async () => {
         const account = algosdk.generateAccount();
+        const depositor = algosdk.generateAccount();
         const stub = makeStubAlgod();
         const transport = makeTransport(stub);
 
         const plan = planMailboxPut(new Uint8Array(32).fill(7), 4, new Uint8Array(64).fill(1));
+        const header = new Uint8Array(40);
+        header.set(algosdk.decodeAddress(depositor.addr.toString()).publicKey, 0);
+        new DataView(header.buffer).setBigUint64(32, 100n, false);
+        const value = new Uint8Array(40 + 64);
+        value.set(header, 0);
+        stub.boxes.set(Buffer.from(plan.mailboxId).toString('hex'), value);
+
         const msgKey = new Uint8Array(32).fill(11);
         const result = await transport.burn(account, plan.mailboxId, msgKey);
         expect(result.confirmedRound).toBe(101);
@@ -217,6 +226,18 @@ describe('MailboxRouterTransport burn and reclaim', () => {
         expect(Buffer.from(args[1]).equals(Buffer.from(plan.mailboxId))).toBe(true);
         expect(Buffer.from(args[2]).equals(Buffer.from(msgKey))).toBe(true);
         expect(Buffer.from((call.applicationCall?.boxes ?? [])[0].name).equals(Buffer.from(plan.mailboxId))).toBe(true);
+        const foreign = (call.applicationCall?.accounts ?? []).map((entry) => entry.toString());
+        expect(foreign).toContain(depositor.addr.toString());
+    });
+
+    test('burn omits foreign accounts when the mailbox is already absent', async () => {
+        const account = algosdk.generateAccount();
+        const stub = makeStubAlgod();
+        const transport = makeTransport(stub);
+        const mailboxId = new Uint8Array(32).fill(9);
+        await transport.burn(account, mailboxId, new Uint8Array(32).fill(11));
+        const [call] = decodeGroup(stub.captured[0]);
+        expect(call.applicationCall?.accounts ?? []).toHaveLength(0);
     });
 
     test('reclaim submits depositor-only call with the mailbox box reference', async () => {
@@ -225,6 +246,11 @@ describe('MailboxRouterTransport burn and reclaim', () => {
         const transport = makeTransport(stub);
 
         const mailboxId = new Uint8Array(32).fill(21);
+        const header = new Uint8Array(40);
+        header.set(algosdk.decodeAddress(account.addr.toString()).publicKey, 0);
+        new DataView(header.buffer).setBigUint64(32, 100n, false);
+        stub.boxes.set(Buffer.from(mailboxId).toString('hex'), header);
+
         await transport.reclaim(account, mailboxId);
 
         const [call] = decodeGroup(stub.captured[0]);
@@ -233,6 +259,8 @@ describe('MailboxRouterTransport burn and reclaim', () => {
         expect(Buffer.from(args[0]).equals(Buffer.from(RECLAIM_SELECTOR))).toBe(true);
         expect(Buffer.from(args[1]).equals(Buffer.from(mailboxId))).toBe(true);
         expect(Buffer.from((call.applicationCall?.boxes ?? [])[0].name).equals(Buffer.from(mailboxId))).toBe(true);
+        const foreign = (call.applicationCall?.accounts ?? []).map((entry) => entry.toString());
+        expect(foreign).toContain(account.addr.toString());
     });
 });
 

src/services/mailbox-router.service.ts

@@ -22,6 +22,7 @@ import algosdk from 'algosdk';
 import {
     MAILBOX_HEADER_SIZE,
     MAILBOX_METHODS,
+    arc4EncodeDynamicBytes,
     mailboxMethodSelector,
     planMailboxFanout,
     planMailboxPut,
@@ -169,13 +170,17 @@ export class MailboxRouterTransport {
         msgKey: Uint8Array,
         options: MailboxSubmitOptions = {}
     ): Promise<MailboxTxnResult> {
+        // Inner refund pays the depositor from the box header; AVM requires
+        // that address in the foreign accounts array (unless it is Txn.Sender).
+        const accounts = await this.foreignAccountsForRefund(mailboxId);
         const call = algosdk.makeApplicationCallTxnFromObject({
             sender: account.addr,
             appIndex: this.appId,
             onComplete: algosdk.OnApplicationComplete.NoOpOC,
             appArgs: [BURN_SELECTOR, mailboxId, msgKey],
             boxes: [{ appIndex: 0, name: mailboxId }],
             suggestedParams: await this.algodClient.getTransactionParams().do(),
+            ...(accounts ? { accounts } : {}),
         });
         return this.signAndSubmit(account, [call], options.waitRounds ?? DEFAULT_WAIT_ROUNDS);
     }
@@ -193,13 +198,15 @@ export class MailboxRouterTransport {
         mailboxId: Uint8Array,
         options: MailboxSubmitOptions = {}
     ): Promise<MailboxTxnResult> {
+        const accounts = await this.foreignAccountsForRefund(mailboxId);
         const call = algosdk.makeApplicationCallTxnFromObject({
             sender: account.addr,
             appIndex: this.appId,
             onComplete: algosdk.OnApplicationComplete.NoOpOC,
             appArgs: [RECLAIM_SELECTOR, mailboxId],
             boxes: [{ appIndex: 0, name: mailboxId }],
             suggestedParams: await this.algodClient.getTransactionParams().do(),
+            ...(accounts ? { accounts } : {}),
         });
         return this.signAndSubmit(account, [call], options.waitRounds ?? DEFAULT_WAIT_ROUNDS);
     }
@@ -252,7 +259,8 @@ export class MailboxRouterTransport {
                     sender: account.addr,
                     appIndex: this.appId,
                     onComplete: algosdk.OnApplicationComplete.NoOpOC,
-                    appArgs: [PUT_SELECTOR, plan.mailboxId, plan.envelope],
+                    // ARC-4 dynamic byte[]: uint16_be(len) ‖ envelope
+                    appArgs: [PUT_SELECTOR, plan.mailboxId, arc4EncodeDynamicBytes(plan.envelope)],
                     boxes: [{ appIndex: 0, name: plan.mailboxId }],
                     suggestedParams: params,
                 })
@@ -261,6 +269,18 @@ export class MailboxRouterTransport {
         return this.signAndSubmit(account, txns, waitRounds);
     }
 
+    /**
+     * Resolves foreign accounts needed for an inner MBR refund. Absent boxes
+     * (idempotent burn) need no accounts.
+     */
+    private async foreignAccountsForRefund(mailboxId: Uint8Array): Promise<string[] | undefined> {
+        const current = await this.read(mailboxId);
+        if (!current.exists || !current.depositor) {
+            return undefined;
+        }
+        return [current.depositor];
+    }
+
     /**
      * Groups, signs, submits, and confirms a set of transactions.
      */