@ar.io/sdk 4.0.0-solana.25 → 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

@@ -42,7 +42,7 @@ import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruct
 import { getTransferCheckedInstruction } from '@solana-program/token';
 import { ARIO_ANT_PROGRAM_ID, TOKEN_DECIMALS } from './constants.js';
 import { SolanaARIOReadable } from './io-readable.js';
-import { getAntRecordPDA, getArioConfigPDA, getArnsRecordPDA, getArnsRegistryPDA, getArnsSettingsPDA, getDelegationPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObservationPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getPrimaryNameReversePDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, getWithdrawalCounterPDA, getWithdrawalPDA, hashName, } from './pda.js';
+import { getAntConfigPDA, getAntRecordPDA, getArioConfigPDA, getArnsRecordPDA, getArnsRegistryPDA, getArnsSettingsPDA, getDelegationPDA, getDemandFactorPDA, getEpochPDA, getEpochSettingsPDA, getGarSettingsPDA, getGatewayPDA, getGatewayRegistryPDA, getObservationPDA, getObserverLookupPDA, getPrimaryNamePDA, getPrimaryNameRequestPDA, getPrimaryNameReversePDA, getReservedNamePDA, getReturnedNamePDA, getVaultPDA, getWithdrawalCounterPDA, getWithdrawalPDA, hashName, } from './pda.js';
 import { predictPrescribedObservers, } from './predict-prescribed-observers.js';
 import { reclaimLookupTablesForSigner, sendAndConfirm, sendWithEphemeralLookupTable, } from './send.js';
 const addressDecoder = getAddressDecoder();
@@ -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`:
@@ -1427,14 +1457,16 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5
      * reshape (ADR-016): ario-core no longer reads MPL Core asset bytes.
-     * Authorization is "caller is the AntRecord.owner for this name" via
-     * PDA-seed-pinned lookup.
+     * Authorization is "caller is the effective AntRecord owner for this
+     * name", resolved from the `AntRecord` + `AntConfig` PDAs (freshness-
+     * gated against `AntConfig.last_known_owner` — see ario-core BD-097 /
+     * BD-109). Both are program-PDA-pinned lookups.
      *
      * Layouts the on-chain handlers expect:
      *   request_primary_name:               [arnsRecord, demandFactor]
-     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord]
-     *   approve_primary_name:               [arnsRecord, antRecord]
-     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@)]
+     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord, antConfig]
+     *   approve_primary_name:               [arnsRecord, antRecord, antConfig]
+     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@), antConfig]
      *
      * `antRecord` keys off the undername part for undernames (e.g.
      * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
@@ -1506,6 +1538,15 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 : undername;
             const [antRecordPda] = await getAntRecordPDA(antMint, antUndername, antProgram);
             remaining.push({ address: antRecordPda, role: AccountRole.READONLY });
+            // AntConfig PDA (ANT-level owner snapshot). ario-core reads
+            // `AntConfig.last_known_owner` as the implicit-owner source and to
+            // freshness-gate the per-record `AntRecord.owner` delegate (BD-097 /
+            // BD-109). Derived under the SAME resolved `antProgram` as the
+            // AntRecord above. Required trailing account for all three ANT-auth
+            // variants (and the funding-plan variant, whose validation_account_count
+            // is derived from this array's length downstream).
+            const [antConfigPda] = await getAntConfigPDA(antMint, antProgram);
+            remaining.push({ address: antConfigPda, role: AccountRole.READONLY });
         }
         return { remaining, antProgram };
     }
@@ -1662,7 +1703,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * Mirrors the on-chain `approve_primary_name` instruction
      * (`programs/ario-core/src/instructions/primary_name.rs`).
-     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     * remaining_accounts: [arns_record(base), ant_record(undername | @), ant_config].
      */
     async approvePrimaryName(params, _options) {
         const { baseName } = splitPrimaryName(params.name);
@@ -2616,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.25';
+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`:
@@ -350,14 +373,16 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5
      * reshape (ADR-016): ario-core no longer reads MPL Core asset bytes.
-     * Authorization is "caller is the AntRecord.owner for this name" via
-     * PDA-seed-pinned lookup.
+     * Authorization is "caller is the effective AntRecord owner for this
+     * name", resolved from the `AntRecord` + `AntConfig` PDAs (freshness-
+     * gated against `AntConfig.last_known_owner` — see ario-core BD-097 /
+     * BD-109). Both are program-PDA-pinned lookups.
      *
      * Layouts the on-chain handlers expect:
      *   request_primary_name:               [arnsRecord, demandFactor]
-     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord]
-     *   approve_primary_name:               [arnsRecord, antRecord]
-     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@)]
+     *   request_and_set_primary_name:       [arnsRecord, demandFactor, antRecord, antConfig]
+     *   approve_primary_name:               [arnsRecord, antRecord, antConfig]
+     *   remove_primary_name_for_base_name:  [arnsRecord, antRecord(@), antConfig]
      *
      * `antRecord` keys off the undername part for undernames (e.g.
      * "blog_arweave" → AntRecord at "blog") or the canonical "@" sentinel
@@ -400,7 +425,7 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * Mirrors the on-chain `approve_primary_name` instruction
      * (`programs/ario-core/src/instructions/primary_name.rs`).
-     * remaining_accounts: [arns_record(base), ant_record(undername | @)].
+     * remaining_accounts: [arns_record(base), ant_record(undername | @), ant_config].
      */
     approvePrimaryName(params: {
         initiator: Address;

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.24";
+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.25",
+  "version": "4.0.0-solana.27",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"