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

package/lib/esm/common/ant.js

@@ -3,18 +3,23 @@ export class ANT {
         return (async () => {
             const { SolanaANTReadable } = await import('../solana/ant-readable.js');
             const { SolanaANTWriteable } = await import('../solana/ant-writeable.js');
-            // ADR-016 / BD-100: when no explicit `antProgramId` is passed,
-            // resolve it from the asset's `ANT Program` Attributes-plugin entry.
-            // Without this auto-detection, third-party (BYO-ANT) assets would
-            // silently mis-derive PDAs through the canonical default.
-            let antProgramId = config.antProgramId;
-            if (!antProgramId) {
-                const { fetchAntProgramFromAsset } = await import('../solana/mpl-core.js');
-                const { ARIO_ANT_PROGRAM_ID } = await import('../solana/constants.js');
-                const { address } = await import('@solana/kit');
-                const detected = await fetchAntProgramFromAsset(config.rpc, address(config.processId), { commitment: config.commitment ?? 'confirmed' });
-                antProgramId = detected ?? ARIO_ANT_PROGRAM_ID;
-            }
+            // ADR-016 / BD-100: when no explicit `antProgramId` is passed, resolve
+            // it from the asset's `ANT Program` Attributes-plugin entry so that
+            // third-party (BYO-ANT) assets derive PDAs through the right program.
+            //
+            // SECURITY: that trait is untrusted asset/RPC data. The *read* path may
+            // use it freely (it never signs). The *write* path runs it through
+            // `resolveWriteAntProgram`, which refuses to sign against a non-canonical
+            // detected value unless the caller opted in by passing `antProgramId`
+            // explicitly — otherwise a spoofed trait could route a signed tx to an
+            // attacker-controlled program.
+            const explicit = config.antProgramId;
+            const { fetchAntProgramFromAsset, resolveWriteAntProgram } = await import('../solana/mpl-core.js');
+            const { ARIO_ANT_PROGRAM_ID } = await import('../solana/constants.js');
+            const { address } = await import('@solana/kit');
+            const detected = explicit !== undefined
+                ? null
+                : await fetchAntProgramFromAsset(config.rpc, address(config.processId), { commitment: config.commitment ?? 'confirmed' });
             if (config.signer) {
                 if (!config.rpcSubscriptions) {
                     throw new Error('ANT.init({ signer }) requires rpcSubscriptions for transaction confirmation.');
@@ -25,14 +30,14 @@ export class ANT {
                     processId: config.processId,
                     signer: config.signer,
                     commitment: config.commitment,
-                    antProgramId,
+                    antProgramId: resolveWriteAntProgram({ explicit, detected }),
                 });
             }
             return new SolanaANTReadable({
                 rpc: config.rpc,
                 processId: config.processId,
                 commitment: config.commitment,
-                antProgramId,
+                antProgramId: explicit ?? detected ?? ARIO_ANT_PROGRAM_ID,
             });
         })();
     }

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,11 +36,11 @@ 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';
-import { TOKEN_DECIMALS } from './constants.js';
+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 { sendAndConfirm } from './send.js';
@@ -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
@@ -1333,10 +1420,13 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
      * `ANT Program` Attributes-plugin trait selects which program owns the
-     * AntRecord PDA. Absent / unparseable → canonical fallback. Both the
-     * PDA derivation here and the `ant_program_id` arg the caller passes
-     * to the on-chain ix MUST agree (the handler re-derives and rejects
-     * mismatches).
+     * AntRecord PDA. Absent / unparseable → canonical fallback. The detected
+     * trait is untrusted asset/RPC data, so it is honored only when it matches
+     * the canonical program or this client's explicitly-configured
+     * `this.antProgram`; any other value falls back to the configured program
+     * (see the SECURITY note in the body). Both the PDA derivation here and the
+     * `ant_program_id` arg the caller passes to the on-chain ix MUST agree (the
+     * handler re-derives and rejects mismatches).
      */
     async _buildPrimaryNameValidationAccounts(name, variant) {
         const { isUndername, baseName, undername } = splitPrimaryName(name);
@@ -1364,10 +1454,26 @@ export class SolanaARIOWriteable extends SolanaARIOReadable {
             const arnsRecord = deserializeArnsRecord(Buffer.from(arnsAccount.data));
             const antMint = address(arnsRecord.processId);
             const { fetchAntProgramFromAsset } = await import('./mpl-core.js');
+            const detected = await fetchAntProgramFromAsset(this.rpc, antMint, {
+                commitment: this.commitment,
+            });
+            // SECURITY (BD-100 / SDK ANT-program auth finding): the asset's
+            // `ANT Program` trait is untrusted asset/RPC data. Only honor a detected
+            // value when it matches the canonical program or the program this client
+            // was explicitly configured with (`this.antProgram`); otherwise fall back
+            // to the configured program so a spoofed trait can't redirect the
+            // AntRecord PDA derivation. This path only derives a READONLY validation
+            // account (the instruction itself targets the canonical core program), so
+            // the fallback is silent rather than a throw — but the gate keeps an
+            // attacker from steering PDA derivation. Heterogeneous BYO-ANT primary
+            // names (an asset on a non-configured program) await the contract-side
+            // resolution of the `ant_program == ario_ant::ID` pin; see the
+            // accompanying security note.
             antProgram =
-                (await fetchAntProgramFromAsset(this.rpc, antMint, {
-                    commitment: this.commitment,
-                })) ?? this.antProgram;
+                detected !== null &&
+                    (detected === ARIO_ANT_PROGRAM_ID || detected === this.antProgram)
+                    ? detected
+                    : this.antProgram;
             // removeForBaseName always uses the "@" undername (the base-name
             // owner's record). The other ANT-auth variants use the undername
             // part if the primary name is an undername.
@@ -1380,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');
@@ -1405,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');
@@ -1437,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 };
     }
     /**
@@ -1525,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);
@@ -1546,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 };
     }
     // =========================================
@@ -1784,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 });
@@ -1809,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
@@ -1831,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 };
     }
     // =========================================
@@ -2081,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({
@@ -2088,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/solana/mpl-core.js

@@ -26,6 +26,7 @@
  * `ANT Program` attribute or has a layout the walker doesn't recognise.
  */
 import { fetchEncodedAccount, } from '@solana/kit';
+import { ARIO_ANT_PROGRAM_ID } from './constants.js';
 import { getAssetV1Decoder } from './generated/mpl-core/accounts/assetV1.js';
 import { getPluginHeaderV1Decoder } from './generated/mpl-core/accounts/pluginHeaderV1.js';
 import { getPluginRegistryV1Decoder } from './generated/mpl-core/accounts/pluginRegistryV1.js';
@@ -116,6 +117,44 @@ export async function fetchAntProgramFromAsset(rpc, mint, config) {
     // self-grief that surfaces at the next PDA derivation.
     return value;
 }
+/**
+ * Decide which ANT program id to trust for a SIGNING (write) transaction.
+ *
+ * The `ANT Program` trait returned by {@link fetchAntProgramFromAsset} is read
+ * from Metaplex Core asset / RPC data and is NOT authenticated — a malicious
+ * asset owner, or a spoofed/compromised RPC response, can set it to an
+ * attacker-controlled program. Write instructions use this value as the
+ * instruction `programAddress` while including the caller as a signer, so
+ * silently trusting a non-canonical detected value would let an attacker route
+ * a victim's signed transaction to their own program and inherit signer /
+ * writable privileges over the included accounts.
+ *
+ * Trust rules — BYO-ANT (ADR-016 / BD-100) stays supported, but only via
+ * explicit opt-in:
+ *   - An `explicit` program id (the caller passed `antProgramId`) is always
+ *     honored — the caller has taken responsibility for it.
+ *   - Otherwise a detected value is honored only when it is `null` (no trait)
+ *     or equals the canonical {@link ARIO_ANT_PROGRAM_ID}.
+ *   - A detected NON-canonical value with no explicit opt-in throws, rather
+ *     than silently signing against an untrusted program.
+ *
+ * Read-only paths never sign, so they may auto-detect freely; this guard is
+ * only for the write path.
+ */
+export function resolveWriteAntProgram(args) {
+    const canonical = args.canonical ?? ARIO_ANT_PROGRAM_ID;
+    if (args.explicit !== undefined)
+        return args.explicit;
+    if (args.detected === null || args.detected === canonical)
+        return canonical;
+    throw new Error(`ANT.init auto-detected a non-canonical ANT program (${args.detected}) ` +
+        `from the asset's "${TRAIT_KEY_ANT_PROGRAM}" trait. That value is read ` +
+        `from asset/RPC data and is not authenticated, so the SDK refuses to ` +
+        `build a *signed* transaction against it implicitly (doing so could ` +
+        `route your signature to an attacker-controlled program). To use a ` +
+        `third-party (BYO-ANT) program for writes, pass it explicitly: ` +
+        `ANT.init({ ..., antProgramId }).`);
+}
 /**
  * Fetch the current owner of an MPL Core asset. Returns `null` when the
  * account doesn't exist or the AssetV1 layout can't be decoded.

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.20';
+export const version = '4.0.0-solana.22';

package/lib/types/common/ant.d.ts

@@ -27,6 +27,13 @@ import type { ANTRead, ANTWrite } from '../types/ant.js';
  * (BYO-ANT) and falls back to the canonical default. Callers who already know
  * the program (e.g. immediately after `ANT.spawn`) can pass it explicitly to
  * skip the lookup.
+ *
+ * SECURITY: the `ANT Program` trait is untrusted asset/RPC data. For a
+ * read-only client it's used as-is, but a writeable client (signer present)
+ * will NOT sign against an auto-detected *non-canonical* program — it throws
+ * unless you opted in by passing `antProgramId` explicitly. This prevents a
+ * malicious asset or spoofed RPC response from redirecting your signed
+ * transaction to an attacker-controlled program.
  */
 export type ANTConfig = {
     processId: string;

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
@@ -287,10 +322,13 @@ export declare class SolanaARIOWriteable extends SolanaARIOReadable {
      *
      * `antProgram` honors ADR-016 / BD-100 pluggability: the asset's
      * `ANT Program` Attributes-plugin trait selects which program owns the
-     * AntRecord PDA. Absent / unparseable → canonical fallback. Both the
-     * PDA derivation here and the `ant_program_id` arg the caller passes
-     * to the on-chain ix MUST agree (the handler re-derives and rejects
-     * mismatches).
+     * AntRecord PDA. Absent / unparseable → canonical fallback. The detected
+     * trait is untrusted asset/RPC data, so it is honored only when it matches
+     * the canonical program or this client's explicitly-configured
+     * `this.antProgram`; any other value falls back to the configured program
+     * (see the SECURITY note in the body). Both the PDA derivation here and the
+     * `ant_program_id` arg the caller passes to the on-chain ix MUST agree (the
+     * handler re-derives and rejects mismatches).
      */
     private _buildPrimaryNameValidationAccounts;
     requestPrimaryName(params: ArNSPurchaseParams, _options?: WriteOptions): Promise<MessageResult>;

package/lib/types/solana/mpl-core.d.ts

@@ -61,6 +61,35 @@ export declare function readAttribute(data: Uint8Array | ReadonlyUint8Array, key
  * lookup once and caches the result.
  */
 export declare function fetchAntProgramFromAsset(rpc: Parameters<typeof fetchEncodedAccount>[0], mint: Address, config?: FetchAccountConfig): Promise<Address | null>;
+/**
+ * Decide which ANT program id to trust for a SIGNING (write) transaction.
+ *
+ * The `ANT Program` trait returned by {@link fetchAntProgramFromAsset} is read
+ * from Metaplex Core asset / RPC data and is NOT authenticated — a malicious
+ * asset owner, or a spoofed/compromised RPC response, can set it to an
+ * attacker-controlled program. Write instructions use this value as the
+ * instruction `programAddress` while including the caller as a signer, so
+ * silently trusting a non-canonical detected value would let an attacker route
+ * a victim's signed transaction to their own program and inherit signer /
+ * writable privileges over the included accounts.
+ *
+ * Trust rules — BYO-ANT (ADR-016 / BD-100) stays supported, but only via
+ * explicit opt-in:
+ *   - An `explicit` program id (the caller passed `antProgramId`) is always
+ *     honored — the caller has taken responsibility for it.
+ *   - Otherwise a detected value is honored only when it is `null` (no trait)
+ *     or equals the canonical {@link ARIO_ANT_PROGRAM_ID}.
+ *   - A detected NON-canonical value with no explicit opt-in throws, rather
+ *     than silently signing against an untrusted program.
+ *
+ * Read-only paths never sign, so they may auto-detect freely; this guard is
+ * only for the write path.
+ */
+export declare function resolveWriteAntProgram(args: {
+    explicit?: Address;
+    detected: Address | null;
+    canonical?: Address;
+}): Address;
 /**
  * Fetch the current owner of an MPL Core asset. Returns `null` when the
  * account doesn't exist or the AssetV1 layout can't be decoded.

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.19";
+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.20",
+  "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",