@ar.io/sdk 4.0.0-solana.21 → 4.0.0-solana.22

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

@@ -264,21 +264,37 @@ export class SolanaANTWriteable extends SolanaANTReadable {
         const newOwnerDest = await this.registry.resolveDestinationAclAccounts({
             user: newOwner,
         });
-        // Resolve the old owner's source ACL accounts. The current owner
-        // *must* have a live `(asset, Owner)` entry — every spawn /
-        // import path seeds it, so a missing entry indicates state
-        // corruption. We surface that as `AclEntryNotFound` from the
-        // contract by passing the derived PDAs as a fallback rather than
-        // failing client-side here.
+        // Resolve the old owner's source ACL accounts. If the entry is
+        // missing (e.g. the ANT was acquired via a marketplace transfer or
+        // before the ACL system existed), heal it by bootstrapping the
+        // config/page and recording the owner entry so the on-chain
+        // transfer handler can successfully remove it.
         const oldOwnerSource = await this.registry.resolveSourceAclAccountsForEntry({
             user: oldOwner,
             asset: this.mint,
             role: 'owner',
         });
-        const oldOwnerAclConfigPda = oldOwnerSource?.aclConfigPda ??
-            (await this.registry.deriveAclConfigPda(oldOwner));
-        const oldOwnerAclPagePda = oldOwnerSource?.aclPagePda ??
-            (await this.registry.deriveAclPagePda(oldOwner, 0n));
+        let oldOwnerAclConfigPda;
+        let oldOwnerAclPagePda;
+        const oldOwnerHealIxs = [];
+        if (oldOwnerSource) {
+            oldOwnerAclConfigPda = oldOwnerSource.aclConfigPda;
+            oldOwnerAclPagePda = oldOwnerSource.aclPagePda;
+        }
+        else {
+            const dest = await this.registry.resolveDestinationAclAccounts({
+                user: oldOwner,
+            });
+            oldOwnerAclConfigPda = dest.aclConfigPda;
+            oldOwnerAclPagePda = dest.aclPagePda;
+            oldOwnerHealIxs.push(...dest.prepIxs);
+            oldOwnerHealIxs.push(await this.registry.buildRecordIx({
+                user: oldOwner,
+                asset: this.mint,
+                role: 'owner',
+                pageIdx: dest.pageIdx,
+            }));
+        }
         const transferIx = await getTransferInstructionAsync({
             asset: this.mint,
             caller: this.signer,
@@ -306,6 +322,7 @@ export class SolanaANTWriteable extends SolanaANTReadable {
             controllers: exControllers,
         });
         const sig = await this.sendTransaction([
+            ...oldOwnerHealIxs,
             ...newOwnerDest.prepIxs,
             transferIx,
             ...cleanupIxs,

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

@@ -19,10 +19,10 @@
  *      surface for them.
  */
 import { AccountRole, address, fetchEncodedAccount, getAddressDecoder, } from '@solana/kit';
-import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
+import { PurchaseType, getBuyNameFromDelegationInstructionAsync, getBuyNameFromFundingPlanInstructionAsync, getBuyNameFromOperatorStakeInstructionAsync, getBuyNameFromWithdrawalInstructionAsync, getBuyNameInstructionAsync, getBuyReturnedNameFromDelegationInstructionAsync, getBuyReturnedNameFromFundingPlanInstructionAsync, getBuyReturnedNameFromOperatorStakeInstructionAsync, getBuyReturnedNameFromWithdrawalInstructionAsync, getBuyReturnedNameInstructionAsync, getExtendLeaseFromDelegationInstructionAsync, getExtendLeaseFromFundingPlanInstructionAsync, getExtendLeaseFromOperatorStakeInstructionAsync, getExtendLeaseFromWithdrawalInstructionAsync, getExtendLeaseInstructionAsync, getIncreaseUndernameLimitFromDelegationInstructionAsync, getIncreaseUndernameLimitFromFundingPlanInstructionAsync, getIncreaseUndernameLimitFromOperatorStakeInstructionAsync, getIncreaseUndernameLimitFromWithdrawalInstructionAsync, getIncreaseUndernameLimitInstructionAsync, getMigrateArnsRecordInstruction, getPruneExpiredNamesInstructionAsync, getPruneExpiredReservationInstruction, getPruneNameToReturnedInstructionAsync, getPruneReturnedNamesInstructionAsync, getReassignNameInstructionAsync, getReleaseNameInstructionAsync, getUpgradeNameFromDelegationInstructionAsync, getUpgradeNameFromFundingPlanInstructionAsync, getUpgradeNameFromOperatorStakeInstructionAsync, getUpgradeNameFromWithdrawalInstructionAsync, getUpgradeNameInstructionAsync, } from '@ar.io/solana-contracts/arns';
 import { FundingSourceKind as GeneratedFundingSourceKindEnum } from '@ar.io/solana-contracts/gar';
 import { buildCreateAtaIdempotentIx, getAssociatedTokenAddressKit, } from './ata.js';
-import { deserializeArnsRecord, deserializeEpochSettingsFull, } from './deserialize.js';
+import { deserializeArnsRecord, deserializeEpochSettingsFull, deserializePrimaryName, } from './deserialize.js';
 import { buildFundingPlan as buildFundingPlanCore, buildFundingPlanRemainingAccounts, computeResidueIndexes, predictResidueVaults, } from './funding-plan.js';
 /** Maps the SDK's user-facing FundingSourceKind string union to the
  *  Codama-generated enum used by the on-chain ix payload. */
@@ -36,7 +36,7 @@ function toGeneratedFundingSourceSpec(s) {
     return { kind: kindMap[s.kind], amount: s.amount };
 }
 import { getSyncAttributesInstruction } from '@ar.io/solana-contracts/ant';
-import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
+import { getApprovePrimaryNameInstructionAsync, getCloseExpiredRequestInstruction, getCreateVaultInstructionAsync, getExtendVaultInstructionAsync, getIncreaseVaultInstructionAsync, getReleaseVaultInstructionAsync, getRemovePrimaryNameInstructionAsync, getRequestAndSetPrimaryNameFromFundingPlanInstructionAsync, getRequestAndSetPrimaryNameInstructionAsync, getRequestPrimaryNameFromFundingPlanInstructionAsync, getRequestPrimaryNameInstructionAsync, getRevokeVaultInstructionAsync, getVaultedTransferInstructionAsync, } from '@ar.io/solana-contracts/core';
 import { getDelegationDecoder, getGatewayDecoder, } from '@ar.io/solana-contracts/gar';
 import { Protocol, getAllowDelegateInstructionAsync, getCancelWithdrawalInstruction, getClaimDelegateFromLeavingGatewayInstructionAsync, getClaimWithdrawalInstructionAsync, getCloseDrainedWithdrawalInstruction, getCloseEmptyDelegationInstruction, getCloseEpochInstructionAsync, getCloseObservationInstructionAsync, getCreateEpochInstructionAsync, getDecreaseDelegateStakeInstructionAsync, getDecreaseOperatorStakeInstructionAsync, getDelegateStakeInstructionAsync, getDisallowDelegateInstructionAsync, getDistributeEpochInstructionAsync, getFinalizeGoneInstructionAsync, getIncreaseOperatorStakeInstructionAsync, getInstantWithdrawalInstructionAsync, getJoinNetworkInstructionAsync, getLeaveNetworkInstructionAsync, getPrescribeEpochInstructionAsync, getPruneGatewayInstructionAsync, getRedelegateStakeInstructionAsync, getSaveObservationsInstructionAsync, getSetAllowlistEnabledInstructionAsync, getTallyWeightsInstructionAsync, getUpdateGatewaySettingsInstructionAsync, } from '@ar.io/solana-contracts/gar';
 import { getTransferCheckedInstruction } from '@solana-program/token';
@@ -280,6 +280,35 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         const [nameRegistry] = await getArnsRegistryPDA(this.arnsProgram);
         return { config, demandFactor, nameRegistry, ...input };
     }
+    /**
+     * If the on-chain ArnsRecord for `name` hasn't been migrated to the
+     * current schema (name_hash at offset 8 doesn't match the expected
+     * hash), return a `migrate_arns_record` instruction that must be
+     * prepended to any operation referencing the record with PDA seed
+     * verification.
+     *
+     * Returns an empty array when the record is already up-to-date or
+     * doesn't exist.
+     */
+    async _buildMigrateArnsRecordIxIfNeeded(name) {
+        const [arnsRecordPda] = await getArnsRecordPDA(name, this.arnsProgram);
+        const account = await fetchEncodedAccount(this.rpc, arnsRecordPda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const data = Buffer.from(account.data);
+        const expectedHash = hashName(name);
+        const storedHash = data.subarray(8, 40);
+        if (storedHash.equals(expectedHash))
+            return [];
+        return [
+            getMigrateArnsRecordInstruction({
+                record: arnsRecordPda,
+                payer: this.signer,
+            }, { programAddress: this.arnsProgram }),
+        ];
+    }
     /** Inject ARIO core default PDAs (config). */
     async withCoreDefaults(input) {
         const [config] = await getArioConfigPDA(this.coreProgram);
@@ -1046,12 +1075,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return pda;
     }
     async upgradeRecord(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'upgrade',
         });
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     async syncAttributes(params, _options) {
@@ -1061,8 +1091,9 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // `_buildSyncAttributesIxIfOwner`, which skips when not the owner so
         // the wrapping arns ix can still succeed for non-holder management
         // — see BD-095.)
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildSyncAttributesIxUnconditional(params.name);
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1130,6 +1161,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         }, { programAddress: this.antProgram });
     }
     async extendLease(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'extend',
@@ -1137,17 +1169,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         });
         // BD-095: extend_lease changes only `end_timestamp`, which isn't
         // mirrored in any Metaplex Attributes plugin trait. No bundle.
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     async increaseUndernameLimit(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const ix = await this._buildManageStakeIx({
             params,
             operation: 'increaseUndername',
             quantity: params.increaseCount,
         });
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const sig = await this.sendTransaction(syncIx ? [...migrateIxs, ix, syncIx] : [...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1312,6 +1345,60 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     // =========================================
     // Primary name operations (ario-core)
     // =========================================
+    /**
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
+     */
+    async _buildRemoveExistingPrimaryNameIxs() {
+        const [primaryNamePda] = await getPrimaryNamePDA(this.signer.address, this.coreProgram);
+        const account = await fetchEncodedAccount(this.rpc, primaryNamePda, {
+            commitment: this.commitment,
+        });
+        if (!account.exists)
+            return [];
+        const { name: oldName } = deserializePrimaryName(Buffer.from(account.data));
+        const [primaryNameReversePda] = await getPrimaryNameReversePDA(oldName, this.coreProgram);
+        const reverseAccount = await fetchEncodedAccount(this.rpc, primaryNameReversePda, { commitment: this.commitment });
+        if (!reverseAccount.exists) {
+            // Fail fast with an actionable message. See method docstring for
+            // why request_and_set would reject this regardless.
+            throw new Error(`Cannot change primary name: signer "${this.signer.address}" has a ` +
+                `legacy PrimaryName ("${oldName}") with no paired PrimaryNameReverse PDA ` +
+                `(${primaryNameReversePda}). The on-chain remove_primary_name and ` +
+                `request_and_set_primary_name ixs both require the reverse PDA — ` +
+                `request_and_set will reject with MustRemoveExistingPrimaryName (code 6022). ` +
+                `Run \`yarn workspace @ar-io/migration-import backfill:primary-name-reverse\` ` +
+                `against this cluster's ario-core program to materialize the missing reverse ` +
+                `PDA, then retry.`);
+        }
+        return [
+            await getRemovePrimaryNameInstructionAsync({
+                primaryName: primaryNamePda,
+                primaryNameReverse: primaryNameReversePda,
+                owner: this.signer,
+                reverseLookupHash: hashName(oldName),
+            }, { programAddress: this.coreProgram }),
+        ];
+    }
     /**
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5
@@ -1399,6 +1486,11 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         return { remaining, antProgram };
     }
     async requestPrimaryName(params, _options) {
+        // If the caller already has a primary name, prepend remove ixs so
+        // the on-chain handler doesn't reject with MustRemoveExistingPrimaryName.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const coreConfig = await this.getCoreConfig();
         const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
         const { remaining } = await this._buildPrimaryNameValidationAccounts(params.name, 'request');
@@ -1424,13 +1516,18 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 operation: 'request',
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
         return { id: sig };
     }
     async setPrimaryName(params, _options) {
         // setPrimaryName routes to the on-chain `request_and_set_primary_name`
         // path — the auto-approve flow when the caller owns the AntRecord
         // for the matching name (undername part, or "@" for base names).
+        // If the caller already has a primary name, prepend remove ixs so
+        // the "change" is atomic in a single transaction.
+        const removeIxs = await this._buildRemoveExistingPrimaryNameIxs();
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const coreConfig = await this.getCoreConfig();
         const signerATA = await getAssociatedTokenAddressKit(coreConfig.mint, this.signer.address);
         const { remaining, antProgram } = await this._buildPrimaryNameValidationAccounts(params.name, 'requestAndSet');
@@ -1456,7 +1553,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
                 antProgramId: antProgram,
             });
         }
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...removeIxs, ...migrateIxs, ix]);
         return { id: sig };
     }
     /**
@@ -1544,6 +1641,8 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * remaining_accounts: [arns_record(base), ant_record(undername | @)].
      */
     async approvePrimaryName(params, _options) {
+        const { baseName } = splitPrimaryName(params.name);
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(baseName);
         const [requestPda] = await getPrimaryNameRequestPDA(params.initiator, this.coreProgram);
         const [primaryNamePda] = await getPrimaryNamePDA(params.initiator, this.coreProgram);
         const [primaryNameReversePda] = await getPrimaryNameReversePDA(params.name, this.coreProgram);
@@ -1565,7 +1664,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             reverseLookupHash: hashName(params.name),
             antProgramId: antProgram,
         }), { programAddress: this.coreProgram }), remaining);
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     // =========================================
@@ -1803,18 +1902,14 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
     // =========================================
     /** Reassign an ArNS name to a different ANT. */
     async reassignName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const newAnt = address(params.processId);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
-        // The on-chain `reassign_name` (PR #73 / BD-106 / BD-095) now authorizes
-        // against the CURRENT Metaplex Core holder of `record.ant` via a named
-        // `ant_asset` account constrained to `arns_record.ant`. We must read the
-        // current record to know which asset to pass — that's the OLD ant (the
-        // one we're reassigning AWAY FROM), not `newAnt`.
-        const currentRecord = await this.getArNSRecord({ name: params.name });
-        const currentAnt = address(currentRecord.processId);
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
         const ix = await getReassignNameInstructionAsync(await this.withArnsDefaults({
             arnsRecord,
-            antAsset: currentAnt,
+            antAsset,
             caller: this.signer,
             newAnt,
         }), { programAddress: this.arnsProgram });
@@ -1828,21 +1923,25 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // the new ANT's holder; otherwise the ix is sent alone and the new
         // owner runs `syncAttributes()` later (BD-095/096).
         const syncIx = await this._buildSyncAttributesIxIfOwner(params.name, newAnt);
-        const sig = await this.sendTransaction(syncIx ? [ix, syncIx] : [ix]);
+        const reassignWithMetas = withRemainingAccounts(ix, [
+            { address: newAnt, role: AccountRole.READONLY },
+        ]);
+        const sig = await this.sendTransaction(syncIx
+            ? [...migrateIxs, reassignWithMetas, syncIx]
+            : [...migrateIxs, reassignWithMetas]);
         return { id: sig };
     }
     /** Release a permabuy name back to the registry (creates a returned name auction). */
     async releaseName(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const [returnedNamePda] = await getReturnedNamePDA(params.name, this.arnsProgram);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
-        // PR #73 / BD-106: `release_name` now authorizes against the current
-        // Metaplex Core holder of `record.ant` via a named `ant_asset` account
-        // constrained to `arns_record.ant`. Fetch the record to know which.
-        const currentRecord = await this.getArNSRecord({ name: params.name });
+        const record = await this.getArNSRecord({ name: params.name });
+        const antAsset = address(record.processId);
         const ix = await getReleaseNameInstructionAsync(await this.withArnsDefaults({
             arnsRecord,
             returnedName: returnedNamePda,
-            antAsset: address(currentRecord.processId),
+            antAsset,
             caller: this.signer,
         }), { programAddress: this.arnsProgram });
         // Note: no sync_attributes bundle here — release_name closes the
@@ -1850,7 +1949,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
         // asset's stale traits remain pointing at the released name; off-chain
         // resolvers should treat ArnsRecord as the source of truth and ignore
         // a "ArNS Name" trait that no longer resolves.
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         return { id: sig };
     }
     // =========================================
@@ -2100,6 +2199,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      * (kicks off the Dutch auction). Permissionless.
      */
     async pruneNameToReturned(params, _options) {
+        const migrateIxs = await this._buildMigrateArnsRecordIxIfNeeded(params.name);
         const [arnsRecord] = await getArnsRecordPDA(params.name, this.arnsProgram);
         const [returnedName] = await getReturnedNamePDA(params.name, this.arnsProgram);
         const ix = await getPruneNameToReturnedInstructionAsync(await this.withArnsDefaults({
@@ -2107,7 +2207,7 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             returnedName,
             payer: this.signer,
         }), { programAddress: this.arnsProgram });
-        const sig = await this.sendTransaction([ix]);
+        const sig = await this.sendTransaction([...migrateIxs, ix]);
         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.21';
+export const version = '4.0.0-solana.22';

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

@@ -109,6 +109,17 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * (codama only reads the named keys from `input`).
      */
     private withArnsDefaults;
+    /**
+     * If the on-chain ArnsRecord for `name` hasn't been migrated to the
+     * current schema (name_hash at offset 8 doesn't match the expected
+     * hash), return a `migrate_arns_record` instruction that must be
+     * prepended to any operation referencing the record with PDA seed
+     * verification.
+     *
+     * Returns an empty array when the record is already up-to-date or
+     * doesn't exist.
+     */
+    private _buildMigrateArnsRecordIxIfNeeded;
     /** Inject ARIO core default PDAs (config). */
     private withCoreDefaults;
     /** Inject GAR default PDAs (settings, epochSettings, registry). */
@@ -266,6 +277,30 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      * Reads the live DemandFactor account + applies the on-chain pricing math.
      */
     private _estimateManageStakeCost;
+    /**
+     * If the signer already has a primary name set, build the instruction(s)
+     * needed to remove it so they can be prepended to a request/set tx —
+     * enabling single-tx "change primary name" flows.
+     *
+     * Returns an empty array when the signer has no existing primary name.
+     *
+     * Throws when the signer has a legacy primary-name state (forward
+     * `PrimaryName` PDA exists but its paired `PrimaryNameReverse` PDA does
+     * NOT). Both `remove_primary_name` AND `request_and_set_primary_name`
+     * require the reverse PDA on-chain — the latter rejects with
+     * `MustRemoveExistingPrimaryName` (0x1786, code 6022) any time a
+     * forward record already exists for the signer, regardless of reverse
+     * state. Silently skipping the remove would queue a tx guaranteed to
+     * fail with that opaque error. Surfacing it at the client with a clear
+     * remediation pointer is the only safe behavior.
+     *
+     * The legacy state should not exist on any cluster post-snapshot/import
+     * PR #159 (which emits PrimaryNameReverse in lockstep with PrimaryName)
+     * — it's a relic of pre-#159 imports. Operators on affected clusters
+     * must run `yarn workspace @ar-io/migration-import backfill:primary-name-reverse`
+     * (in the solana-ar-io repo) before this method can succeed.
+     */
+    private _buildRemoveExistingPrimaryNameIxs;
     /**
      * Build the `remaining_accounts` slice + the `antProgramId` arg the
      * four ario-core primary-name instructions consume. Sprint 2/5

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.20";
+export declare const version = "4.0.0-solana.21";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "4.0.0-solana.21",
+  "version": "4.0.0-solana.22",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -122,7 +122,7 @@
     "typescript": "^5.1.6"
   },
   "dependencies": {
-    "@ar.io/solana-contracts": "^0.4.0",
+    "@ar.io/solana-contracts": "0.4.0",
     "@solana-program/compute-budget": "^0.15.0",
     "@solana-program/token": "^0.13.0",
     "@solana/kit": "^6.8.0",