Merge pull request #723 from ar-io/feat/adr0029-epoch-rent-receipt

feat(solana): route epoch rent to the creator (ADR-0029)

Author: vilenarios

package.json

@@ -114,7 +114,7 @@
     "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@ar.io/solana-contracts": "1.1.0",
+    "@ar.io/solana-contracts": "1.2.0",
     "@noble/hashes": "^1.8.0",
     "@solana-program/address-lookup-table": "^0.11.0",
     "@solana-program/compute-budget": "^0.15.0",

src/solana/constants.ts

@@ -77,6 +77,17 @@ export const WITHDRAWAL_SEED = Buffer.from('withdrawal');
 export const WITHDRAWAL_COUNTER_SEED = Buffer.from('withdrawal_counter');
 export const ALLOWLIST_SEED = Buffer.from('allowlist');
 export const EPOCH_SEED = Buffer.from('epoch');
+/**
+ * Seed for the `EpochRentReceipt` PDA (ADR-0029). The receipt records which
+ * account funded an Epoch's rent so `close_epoch` can refund the creator
+ * rather than whoever wins the race to sign the close.
+ *
+ * Derived by hand rather than with a generated helper: the account is reached
+ * only through `remaining_accounts` and `admin_close_orphaned_epoch_rent_receipt`,
+ * so the IDL carries no seed metadata for it and Codama emits no
+ * `findEpochRentReceiptPda`.
+ */
+export const EPOCH_RENT_RECEIPT_SEED = Buffer.from('epoch_rent_receipt');
 export const EPOCH_SETTINGS_SEED = Buffer.from('epoch_settings');
 export const OBSERVATION_SEED = Buffer.from('observation');
 export const REDELEGATION_SEED = Buffer.from('redelegation');

src/solana/epoch-rent-receipt.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Unit tests for the ADR-0029 epoch-rent-receipt client surface:
+ *
+ *   - `getEpochRentReceiptPDA` — the hand-rolled PDA derivation. Codama emits
+ *     no finder for `EpochRentReceipt` (the account is reached only through
+ *     `remaining_accounts` and `admin_close_orphaned_epoch_rent_receipt`, so
+ *     the IDL carries no seed metadata), which makes this derivation the one
+ *     place a typo would silently produce a wrong-but-valid address.
+ *   - `buildCloseEpochRentAccounts` — the `remaining_accounts` tail for
+ *     `close_epoch`.
+ *
+ * Mirrors `programs/ario-gar/src/instructions/epoch.rs`:
+ *   create_epoch: `ctx.remaining_accounts.first()` is the receipt; when absent
+ *                 the epoch is created with `has_rent_receipt = 0`.
+ *   close_epoch:  branches on `epoch.has_rent_receipt != 0` — NOT on what the
+ *                 caller passed — then requires
+ *                 `remaining_accounts = [receipt, creator]`, both writable.
+ */
+import { strict as assert } from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { AccountRole, type Address, getAddressDecoder } from '@solana/kit';
+
+import { buildCloseEpochRentAccounts } from './io-writeable.js';
+import { getEpochPDA, getEpochRentReceiptPDA } from './pda.js';
+
+const dec = getAddressDecoder();
+function pk(tag: number): Address {
+  const u = new Uint8Array(32);
+  u[0] = tag & 0xff;
+  u[31] = 0x2a;
+  return dec.decode(u);
+}
+const GAR = 'ARioGarProgramXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' as Address;
+const RECEIPT = pk(7);
+const CREATOR = pk(8);
+
+describe('getEpochRentReceiptPDA', () => {
+  it('is deterministic for a given index', async () => {
+    const [a] = await getEpochRentReceiptPDA(42, GAR);
+    const [b] = await getEpochRentReceiptPDA(42, GAR);
+    assert.equal(a, b);
+  });
+
+  it('differs per epoch index', async () => {
+    const [a] = await getEpochRentReceiptPDA(42, GAR);
+    const [b] = await getEpochRentReceiptPDA(43, GAR);
+    assert.notEqual(a, b);
+  });
+
+  it('accepts number and bigint identically (u64 LE seed)', async () => {
+    const [a] = await getEpochRentReceiptPDA(780, GAR);
+    const [b] = await getEpochRentReceiptPDA(780n, GAR);
+    assert.equal(a, b);
+  });
+
+  it('is NOT the Epoch PDA for the same index (distinct seed prefix)', async () => {
+    const [receipt] = await getEpochRentReceiptPDA(780, GAR);
+    const [epoch] = await getEpochPDA(780, GAR);
+    assert.notEqual(receipt, epoch);
+  });
+
+  it('is program-scoped', async () => {
+    const [a] = await getEpochRentReceiptPDA(1, GAR);
+    const [b] = await getEpochRentReceiptPDA(1, pk(123));
+    assert.notEqual(a, b);
+  });
+});
+
+describe('buildCloseEpochRentAccounts', () => {
+  it('returns no extra accounts for a pre-ADR-0029 epoch (flag clear)', () => {
+    // This is what keeps un-upgraded crankers working through the transition.
+    assert.deepEqual(buildCloseEpochRentAccounts(0, RECEIPT, null, 100), []);
+  });
+
+  it('ignores a creator that happens to be known when the flag is clear', () => {
+    // The program refunds `payer` in this branch; passing extras would be wrong.
+    assert.deepEqual(buildCloseEpochRentAccounts(0, RECEIPT, CREATOR, 100), []);
+  });
+
+  it('returns [receipt, creator] in that exact order when the flag is set', () => {
+    const got = buildCloseEpochRentAccounts(1, RECEIPT, CREATOR, 100);
+    assert.equal(got.length, 2);
+    assert.equal(
+      got[0].address,
+      RECEIPT,
+      'receipt must be remaining_accounts[0]',
+    );
+    assert.equal(
+      got[1].address,
+      CREATOR,
+      'creator must be remaining_accounts[1]',
+    );
+  });
+
+  it('marks both accounts writable — the program drains both', () => {
+    const got = buildCloseEpochRentAccounts(1, RECEIPT, CREATOR, 100);
+    assert.equal(got[0].role, AccountRole.WRITABLE);
+    assert.equal(got[1].role, AccountRole.WRITABLE);
+  });
+
+  it('treats any non-zero flag byte as set, matching `has_rent_receipt != 0`', () => {
+    for (const flag of [1, 2, 255]) {
+      assert.equal(
+        buildCloseEpochRentAccounts(flag, RECEIPT, CREATOR, 100).length,
+        2,
+        `flag ${flag} should take the receipted branch`,
+      );
+    }
+  });
+
+  it('throws a diagnosable error when the flag is set but the receipt is gone', () => {
+    assert.throws(
+      () => buildCloseEpochRentAccounts(1, RECEIPT, null, 4242),
+      /Epoch 4242 .*flagged.*rent receipt.*MissingEpochRentReceipt/s,
+    );
+  });
+});

src/solana/io-writeable.ts

@@ -174,6 +174,8 @@ import {
 } from '@ar.io/solana-contracts/gar';
 import {
   Protocol,
+  fetchMaybeEpoch,
+  fetchMaybeEpochRentReceipt,
   getAdminSetRewardRatiosInstructionAsync,
   getAllowDelegateInstructionAsync,
   getCancelWithdrawalInstruction,
@@ -224,6 +226,7 @@ import {
   getDelegationPDA,
   getDemandFactorPDA,
   getEpochPDA,
+  getEpochRentReceiptPDA,
   getEpochSettingsPDA,
   getGarSettingsPDA,
   getGatewayPDA,
@@ -291,6 +294,52 @@ function withRemainingAccounts<I extends Instruction>(
   return { ...ix, accounts } as I;
 }
 
+/**
+ * Build the `remaining_accounts` tail that `close_epoch` requires (ADR-0029).
+ *
+ * Mirrors `programs/ario-gar/src/instructions/epoch.rs::close_epoch`, which
+ * branches on `Epoch.has_rent_receipt` — **program-controlled state, never
+ * "did the caller pass a receipt?"**. That distinction is the whole security
+ * property: if the branch keyed off account presence, a scavenger would simply
+ * omit the receipt to fall through to the legacy `close = payer` path and
+ * pocket rent the epoch's creator paid for.
+ *
+ * - flag clear (every pre-ADR-0029 epoch) → no extra accounts; the program
+ *   refunds `payer` exactly as before, which is what lets un-upgraded crankers
+ *   keep closing old epochs during the ~8-day transition window.
+ * - flag set → exactly two accounts, in this order, both writable because both
+ *   are drained: `[receipt, creator]`. The program rejects a missing or
+ *   read-only entry with `MissingEpochRentReceipt`, a wrong-PDA or
+ *   foreign-owned receipt with `InvalidEpochRentReceipt`, and a creator that
+ *   does not match `receipt.creator` with `WrongEpochCreator`.
+ *
+ * @param hasRentReceipt `Epoch.hasRentReceipt`. Any non-zero value counts — the
+ *   byte was padding before ADR-0029 and the program itself treats it as
+ *   boolean (`epoch.has_rent_receipt != 0`).
+ * @param creator `EpochRentReceipt.creator`, or `null` if no receipt account
+ *   exists at the derived address.
+ */
+export function buildCloseEpochRentAccounts(
+  hasRentReceipt: number,
+  receiptPda: Address,
+  creator: Address | null,
+  epochIndex: number,
+): AccountMeta[] {
+  if (hasRentReceipt === 0) return [];
+  if (creator === null) {
+    throw new Error(
+      `Epoch ${epochIndex} is flagged as having a rent receipt but none exists ` +
+        `at ${receiptPda}. close_epoch would fail with MissingEpochRentReceipt; ` +
+        `an authority can clear the orphan with ` +
+        `admin_close_orphaned_epoch_rent_receipt.`,
+    );
+  }
+  return [
+    { address: receiptPda, role: AccountRole.WRITABLE },
+    { address: creator, role: AccountRole.WRITABLE },
+  ];
+}
+
 /**
  * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
  * `remaining_accounts[0]`.
@@ -4117,7 +4166,27 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
       { programAddress: this.garProgram },
     );
 
-    const sig = await this.sendTransaction([ix], 1_000_000);
+    // ADR-0029: record who funded the Epoch's rent so `close_epoch` can refund
+    // the creator instead of whoever wins the race to sign the close.
+    //
+    // The receipt rides as a trailing `remaining_accounts` entry, NOT a declared
+    // account, so `create_epoch`'s IDL account list is unchanged and crankers
+    // running an older client keep working — they simply omit it and the epoch
+    // is created with `has_rent_receipt = 0`, taking the legacy refund path.
+    // On-chain: `create_epoch` reads `ctx.remaining_accounts.first()`.
+    const [receiptPda] = await getEpochRentReceiptPDA(
+      epochIndex,
+      this.garProgram,
+    );
+
+    const sig = await this.sendTransaction(
+      [
+        withRemainingAccounts(ix, [
+          { address: receiptPda, role: AccountRole.WRITABLE },
+        ]),
+      ],
+      1_000_000,
+    );
     return { id: sig };
   }
 
@@ -4286,7 +4355,51 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
       { programAddress: this.garProgram },
     );
 
-    const sig = await this.sendTransaction([ix]);
+    // ADR-0029: `close_epoch` decides where the rent goes by reading
+    // `Epoch.hasRentReceipt` — program-controlled state, deliberately NOT
+    // "did the caller pass a receipt?" (that would let a scavenger omit the
+    // receipt to force the legacy `close = payer` branch and pocket the rent).
+    //
+    // So mirror the program: read the flag, and only when it is set append the
+    // two accounts the receipted branch requires, in this exact order:
+    //   remaining_accounts[0] = the EpochRentReceipt PDA   (writable — closed)
+    //   remaining_accounts[1] = receipt.creator            (writable — paid)
+    // Both are mandatory in that branch; omitting either is
+    // `MissingEpochRentReceipt`. Epochs created before this upgrade have the
+    // flag clear and need no extra accounts, which is what keeps the ~8-day
+    // mixed-version transition window working in both directions.
+    const [epochPda] = await getEpochPDA(params.epochIndex, this.garProgram);
+    const epochAccount = await fetchMaybeEpoch(this.rpc, epochPda, {
+      commitment: this.commitment,
+    });
+    const hasRentReceipt = epochAccount.exists
+      ? epochAccount.data.hasRentReceipt
+      : 0;
+
+    const [receiptPda] = await getEpochRentReceiptPDA(
+      params.epochIndex,
+      this.garProgram,
+    );
+    let creator: Address | null = null;
+    if (hasRentReceipt !== 0) {
+      const receipt = await fetchMaybeEpochRentReceipt(this.rpc, receiptPda, {
+        commitment: this.commitment,
+      });
+      creator = receipt.exists ? receipt.data.creator : null;
+    }
+
+    const remainingAccounts = buildCloseEpochRentAccounts(
+      hasRentReceipt,
+      receiptPda,
+      creator,
+      params.epochIndex,
+    );
+
+    const sig = await this.sendTransaction([
+      remainingAccounts.length > 0
+        ? withRemainingAccounts(ix, remainingAccounts)
+        : ix,
+    ]);
     return { id: sig };
   }
 

src/solana/pda.ts

@@ -51,6 +51,7 @@ import {
   BALANCE_SEED,
   DELEGATION_SEED,
   DEMAND_FACTOR_SEED,
+  EPOCH_RENT_RECEIPT_SEED,
   EPOCH_SEED,
   EPOCH_SETTINGS_SEED,
   ESCROW_ANT_SEED,
@@ -262,6 +263,28 @@ export async function getEpochPDA(
   });
 }
 
+/**
+ * `EpochRentReceipt` PDA for an epoch (ADR-0029) — seeds
+ * `["epoch_rent_receipt", u64_le(epochIndex)]`.
+ *
+ * `create_epoch` initialises this as a trailing `remaining_accounts` entry and
+ * sets `Epoch.hasRentReceipt`; `close_epoch` then refunds the Epoch's rent to
+ * the recorded `creator` instead of the closing signer. Hand-rolled because the
+ * account never appears in a declared `Accounts` struct for those two
+ * instructions, so the IDL has no seeds for it and Codama generates no finder.
+ */
+export async function getEpochRentReceiptPDA(
+  epochIndex: number | bigint,
+  programId: Address = ARIO_GAR_PROGRAM_ID,
+): Promise<Pda> {
+  const indexBuf = Buffer.alloc(8);
+  indexBuf.writeBigUInt64LE(BigInt(epochIndex));
+  return getProgramDerivedAddress({
+    programAddress: programId,
+    seeds: [EPOCH_RENT_RECEIPT_SEED, indexBuf],
+  });
+}
+
 export async function getEpochSettingsPDA(
   programId: Address = ARIO_GAR_PROGRAM_ID,
 ): Promise<Pda> {

yarn.lock

@@ -30,10 +30,10 @@
   resolved "https://registry.yarnpkg.com/@actions/io/-/io-3.0.2.tgz#6f89b27a159d109836d983efa283997c23b92284"
   integrity sha512-nRBchcMM+QK1pdjO7/idu86rbJI5YHUKCvKs0KxnSYbVe3F51UfGxuZX4Qy/fWlp6l7gWFwIkrOzN+oUK03kfw==
 
-"@ar.io/solana-contracts@1.1.0":
-  version "1.1.0"
-  resolved "https://registry.yarnpkg.com/@ar.io/solana-contracts/-/solana-contracts-1.1.0.tgz#900784dad9b0867ae76678dc177d346692f5e61f"
-  integrity sha512-qX8ttp5GoZYMMNNgVzGMdBmaym3g1XL3Y7GyApbbXo4e4SSgt3DXMKl6PCISij5snhkec21LAhHxzHuLyoOe8w==
+"@ar.io/solana-contracts@1.2.0":
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/@ar.io/solana-contracts/-/solana-contracts-1.2.0.tgz#3e56cdbce36c295001572a105fe689690cb77236"
+  integrity sha512-g/zqlYNK3geFzjaiYhicFniGsBu2T3MDM+Gh7IuOmQXV1HSPakib3oP1p0wWeJ0ho1SipoPvW+KncUaM9KVQHA==
   dependencies:
     "@noble/hashes" "^1.5.0"
     bs58 "^6.0.0"