@ar.io/sdk 4.0.0-solana.26 → 4.0.0-solana.27

package/lib/esm/solana/io-readable.js

@@ -1723,8 +1723,21 @@ export class SolanaARIOReadable {
         return out;
     }
     /**
-     * Enumerate Gateway PDAs whose `status == Gone` (already left the
-     * network but PDA not yet GC'd). Eligible for `finalizeGone`.
+     * Enumerate Gateway PDAs that are candidates for `finalizeGone` GC — i.e.
+     * those whose `status == Leaving`.
+     *
+     * NOTE: despite the historical name, this returns `Leaving` (not `Gone`)
+     * gateways. `Gone` is NOT a persistent discovery state: the on-chain
+     * `finalize_gone` instruction accepts a `Leaving` gateway, flips it to
+     * `Gone`, and closes the Gateway PDA in the *same* instruction
+     * (programs/ario-gar/src/instructions/gateway.rs::finalize_gone), so a
+     * gateway is never observably parked at `Gone`. Filtering on `Gone` matched
+     * nothing and left Leaving gateways un-GC'd. Time/delegation eligibility is
+     * still enforced on-chain (`finalize_gone` reverts early if the leave window
+     * hasn't elapsed or delegations remain), so over-returning not-yet-eligible
+     * Leaving gateways is safe — the tx just no-ops/reverts.
+     *
+     * @deprecated Prefer {@link getLeavingGateways} — same result, accurate name.
      */
     async getGoneGateways() {
         const accounts = await this.getAccountsByDiscriminator(this.garProgram, GATEWAY_DISCRIMINATOR);
@@ -1733,7 +1746,7 @@ export class SolanaARIOReadable {
         for (const { pubkey, data } of accounts) {
             try {
                 const g = decoder.decode(data);
-                if (g.status === GatewayStatus.Gone) {
+                if (g.status === GatewayStatus.Leaving) {
                     out.push({ pubkey, operator: g.operator });
                 }
             }
@@ -1743,6 +1756,14 @@ export class SolanaARIOReadable {
         }
         return out;
     }
+    /**
+     * Enumerate Gateway PDAs whose `status == Leaving` — the persistent
+     * pre-finalization state that `finalizeGone` GC's. Alias for
+     * {@link getGoneGateways} with a name that matches the on-chain state.
+     */
+    async getLeavingGateways() {
+        return this.getGoneGateways();
+    }
     /**
      * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
      * (`allow_delegated_staking == false`) yet still hold delegated stake

package/lib/esm/solana/io-writeable.js

@@ -69,6 +69,36 @@ function withRemainingAccounts(ix, remaining) {
     ];
     return { ...ix, accounts };
 }
+/**
+ * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
+ * `remaining_accounts[0]`.
+ *
+ * `finalize_gone` reclaims a gateway's slot from the compact GatewayRegistry by
+ * moving the LAST active slot into it and rewriting that swapped gateway's
+ * stored `registry_index`. When the finalized gateway is NOT already the last
+ * slot, the on-chain handler requires the swapped Gateway PDA (writable) at
+ * `remaining_accounts[0]`; when it IS the last slot, no swap occurs and no
+ * extra account is needed. See
+ * `programs/ario-gar/src/instructions/gateway.rs::finalize_gone`.
+ *
+ * `registryAddresses` MUST be the active registry operator addresses in slot
+ * order (`getRegistryGatewayAddresses()` — length === on-chain
+ * `registry.count`), so `registryAddresses[length - 1]` is exactly the
+ * `registry.gateways[count - 1].address` the on-chain swap reads.
+ *
+ * @returns the swapped gateway's operator address, or `null` when the finalized
+ *   gateway already occupies the last slot.
+ * @throws if `registryIndex` is outside the active registry count (mirrors the
+ *   on-chain `index < registry.count` guard, surfacing a stale index early).
+ */
+export function selectFinalizeGoneSwapOperator(registryIndex, registryAddresses) {
+    if (registryIndex < 0 || registryIndex >= registryAddresses.length) {
+        throw new Error(`finalizeGone: registry index ${registryIndex} is outside the active ` +
+            `registry count ${registryAddresses.length}`);
+    }
+    const lastIndex = registryAddresses.length - 1;
+    return registryIndex === lastIndex ? null : registryAddresses[lastIndex];
+}
 /**
  * Split a primary name into its undername + base parts using the same rule
  * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:
@@ -2627,11 +2657,34 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     async finalizeGone(params, _options) {
         const gatewayAddr = address(params.gateway);
         const [gatewayPda] = await getGatewayPDA(gatewayAddr, this.garProgram);
+        // `finalize_gone` reclaims this gateway's compact-registry slot by
+        // swap-removing the LAST active slot into it. When this gateway is not the
+        // last slot, the on-chain handler rewrites the swapped gateway's stored
+        // registry_index and therefore requires that swapped Gateway PDA as
+        // writable remaining_accounts[0]
+        // (programs/ario-gar/src/instructions/gateway.rs::finalize_gone). Read the
+        // gateway's slot index + the active registry to decide.
+        const gatewayAccount = await fetchEncodedAccount(this.rpc, gatewayPda, {
+            commitment: this.commitment,
+        });
+        if (!gatewayAccount.exists) {
+            throw new Error(`Gateway not found for operator ${params.gateway}`);
+        }
+        const gateway = getGatewayDecoder().decode(gatewayAccount.data);
+        const registryAddresses = await this.getRegistryGatewayAddresses();
+        const swappedOperator = selectFinalizeGoneSwapOperator(gateway.registryIndex.index, registryAddresses);
         const ix = await getFinalizeGoneInstructionAsync(await this.withGarDefaults({
             gateway: gatewayPda,
             caller: this.signer,
         }), { programAddress: this.garProgram });
-        const sig = await this.sendTransaction([ix]);
+        let finalIx = ix;
+        if (swappedOperator !== null) {
+            const [swappedGatewayPda] = await getGatewayPDA(address(swappedOperator), this.garProgram);
+            finalIx = withRemainingAccounts(ix, [
+                { address: swappedGatewayPda, role: AccountRole.WRITABLE },
+            ]);
+        }
+        const sig = await this.sendTransaction([finalIx]);
         return { id: sig };
     }
     /**

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '4.0.0-solana.26';
+export const version = '4.0.0-solana.27';

package/lib/types/solana/io-readable.d.ts

@@ -302,13 +302,35 @@ export declare class SolanaARIOReadable {
         failedConsecutive: number;
     }>>;
     /**
-     * Enumerate Gateway PDAs whose `status == Gone` (already left the
-     * network but PDA not yet GC'd). Eligible for `finalizeGone`.
+     * Enumerate Gateway PDAs that are candidates for `finalizeGone` GC — i.e.
+     * those whose `status == Leaving`.
+     *
+     * NOTE: despite the historical name, this returns `Leaving` (not `Gone`)
+     * gateways. `Gone` is NOT a persistent discovery state: the on-chain
+     * `finalize_gone` instruction accepts a `Leaving` gateway, flips it to
+     * `Gone`, and closes the Gateway PDA in the *same* instruction
+     * (programs/ario-gar/src/instructions/gateway.rs::finalize_gone), so a
+     * gateway is never observably parked at `Gone`. Filtering on `Gone` matched
+     * nothing and left Leaving gateways un-GC'd. Time/delegation eligibility is
+     * still enforced on-chain (`finalize_gone` reverts early if the leave window
+     * hasn't elapsed or delegations remain), so over-returning not-yet-eligible
+     * Leaving gateways is safe — the tx just no-ops/reverts.
+     *
+     * @deprecated Prefer {@link getLeavingGateways} — same result, accurate name.
      */
     getGoneGateways(): Promise<Array<{
         pubkey: Address;
         operator: Address;
     }>>;
+    /**
+     * Enumerate Gateway PDAs whose `status == Leaving` — the persistent
+     * pre-finalization state that `finalizeGone` GC's. Alias for
+     * {@link getGoneGateways} with a name that matches the on-chain state.
+     */
+    getLeavingGateways(): Promise<Array<{
+        pubkey: Address;
+        operator: Address;
+    }>>;
     /**
      * Enumerate Joined Gateway PDAs whose delegation has been DISABLED
      * (`allow_delegated_staking == false`) yet still hold delegated stake

package/lib/types/solana/io-writeable.d.ts

@@ -26,6 +26,29 @@ import type { mARIOToken } from '../types/token.js';
 import { deserializeEpochSettingsFull } from './deserialize.js';
 import { SolanaARIOReadable } from './io-readable.js';
 import type { SolanaRpcSubscriptions, SolanaSigner, SolanaWriteConfig } from './types.js';
+/**
+ * Pick the swapped-gateway operator that `finalize_gone` needs as a writable
+ * `remaining_accounts[0]`.
+ *
+ * `finalize_gone` reclaims a gateway's slot from the compact GatewayRegistry by
+ * moving the LAST active slot into it and rewriting that swapped gateway's
+ * stored `registry_index`. When the finalized gateway is NOT already the last
+ * slot, the on-chain handler requires the swapped Gateway PDA (writable) at
+ * `remaining_accounts[0]`; when it IS the last slot, no swap occurs and no
+ * extra account is needed. See
+ * `programs/ario-gar/src/instructions/gateway.rs::finalize_gone`.
+ *
+ * `registryAddresses` MUST be the active registry operator addresses in slot
+ * order (`getRegistryGatewayAddresses()` — length === on-chain
+ * `registry.count`), so `registryAddresses[length - 1]` is exactly the
+ * `registry.gateways[count - 1].address` the on-chain swap reads.
+ *
+ * @returns the swapped gateway's operator address, or `null` when the finalized
+ *   gateway already occupies the last slot.
+ * @throws if `registryIndex` is outside the active registry count (mirrors the
+ *   on-chain `index < registry.count` guard, surfacing a stale index early).
+ */
+export declare function selectFinalizeGoneSwapOperator(registryIndex: number, registryAddresses: string[]): string | null;
 /**
  * Split a primary name into its undername + base parts using the same rule
  * as the on-chain `splitn(2, '_')` in `programs/ario-core/src/instructions/primary_name.rs`:

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "4.0.0-solana.25";
+export declare const version = "4.0.0-solana.26";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.26",
+  "version": "4.0.0-solana.27",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"