@ar.io/sdk 3.24.0 → 4.0.0-solana.1

package/lib/cjs/solana/deserialize.js

@@ -0,0 +1,1127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BorshWriter = exports.BorshReader = void 0;
+exports.deserializeGateway = deserializeGateway;
+exports.deserializeArnsRecord = deserializeArnsRecord;
+exports.deserializeVault = deserializeVault;
+exports.deserializeDelegation = deserializeDelegation;
+exports.deserializeBalance = deserializeBalance;
+exports.deserializeEpochSettings = deserializeEpochSettings;
+exports.deserializeArioConfig = deserializeArioConfig;
+exports.deserializeDemandFactor = deserializeDemandFactor;
+exports.deserializeReservedName = deserializeReservedName;
+exports.deserializeReturnedName = deserializeReturnedName;
+exports.deserializeWithdrawal = deserializeWithdrawal;
+exports.deserializeRedelegationRecord = deserializeRedelegationRecord;
+exports.deserializePrimaryNameRequest = deserializePrimaryNameRequest;
+exports.deserializeGarSettings = deserializeGarSettings;
+exports.deserializeGarSupplyCounters = deserializeGarSupplyCounters;
+exports.deserializeEpochSettingsFull = deserializeEpochSettingsFull;
+exports.deserializeEpoch = deserializeEpoch;
+exports.deserializeObservation = deserializeObservation;
+exports.deserializeAntConfig = deserializeAntConfig;
+exports.deserializeAntControllers = deserializeAntControllers;
+exports.deserializeAntRecord = deserializeAntRecord;
+exports.deserializeAntRecordMetadata = deserializeAntRecordMetadata;
+exports.deserializeAclConfig = deserializeAclConfig;
+exports.deserializeAclPage = deserializeAclPage;
+exports.deserializePrimaryName = deserializePrimaryName;
+exports.deserializeAllowlist = deserializeAllowlist;
+/**
+ * Account deserialization for AR.IO Solana programs.
+ *
+ * Reads raw account data (Borsh-encoded by Anchor) and returns SDK-compatible
+ * types. Each function skips the 8-byte Anchor discriminator, then reads
+ * fields in the exact order defined in the Rust structs.
+ *
+ * NOTE on discriminators: this module no longer exports a hand-rolled
+ * discriminator table. The Codama-generated account modules under
+ * `./generated/<program>/accounts/` already export
+ * `<NAME>_DISCRIMINATOR: Uint8Array` constants pulled directly from each
+ * IDL, so they're guaranteed to match the on-chain struct names.
+ * Use those at the call site (see `io-readable.ts` for the
+ * `getAccountsByDiscriminator` helper that bs58-encodes them for
+ * `getProgramAccounts` memcmp filters).
+ *
+ * Borsh encoding rules (Anchor default):
+ *   - u8/bool: 1 byte
+ *   - u16: 2 bytes LE
+ *   - u32: 4 bytes LE
+ *   - u64: 8 bytes LE
+ *   - u128: 16 bytes LE
+ *   - i64: 8 bytes LE (signed)
+ *   - Pubkey: 32 bytes
+ *   - String: 4-byte LE length prefix + UTF-8 bytes
+ *   - Option<T>: 1-byte tag (0=None, 1=Some) + T if Some
+ *   - Vec<T>: 4-byte LE length + T[] elements
+ *   - Enum: 1-byte variant index
+ */
+const kit_1 = require("@solana/kit");
+const constants_js_1 = require("./constants.js");
+const balance_js_1 = require("./generated/core/accounts/balance.js");
+const addressDecoder = (0, kit_1.getAddressDecoder)();
+const addressEncoder = (0, kit_1.getAddressEncoder)();
+// =========================================
+// Buffer reader helper
+// =========================================
+class BorshReader {
+    data;
+    offset;
+    constructor(data, startOffset = 0) {
+        this.data = data;
+        this.offset = startOffset;
+    }
+    readU8() {
+        const val = this.data.readUInt8(this.offset);
+        this.offset += 1;
+        return val;
+    }
+    readBool() {
+        return this.readU8() !== 0;
+    }
+    readU16() {
+        const val = this.data.readUInt16LE(this.offset);
+        this.offset += 2;
+        return val;
+    }
+    readU32() {
+        const val = this.data.readUInt32LE(this.offset);
+        this.offset += 4;
+        return val;
+    }
+    readU64() {
+        const val = this.data.readBigUInt64LE(this.offset);
+        this.offset += 8;
+        return val;
+    }
+    readU64AsNumber() {
+        return Number(this.readU64());
+    }
+    readI64() {
+        const val = this.data.readBigInt64LE(this.offset);
+        this.offset += 8;
+        return val;
+    }
+    readI64AsNumber() {
+        return Number(this.readI64());
+    }
+    readU128() {
+        const lo = this.data.readBigUInt64LE(this.offset);
+        const hi = this.data.readBigUInt64LE(this.offset + 8);
+        this.offset += 16;
+        return (hi << 64n) | lo;
+    }
+    readPubkey() {
+        const bytes = this.data.subarray(this.offset, this.offset + 32);
+        this.offset += 32;
+        return addressDecoder.decode(bytes);
+    }
+    readString() {
+        const len = this.readU32();
+        const str = this.data.toString('utf8', this.offset, this.offset + len);
+        this.offset += len;
+        return str;
+    }
+    readOptionI64() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readI64AsNumber();
+    }
+    readOptionU32() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readU32();
+    }
+    skip(bytes) {
+        this.offset += bytes;
+    }
+    getOffset() {
+        return this.offset;
+    }
+    remaining() {
+        return this.data.length - this.offset;
+    }
+    readOptionPubkey() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readPubkey();
+    }
+    readOptionString() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readString();
+    }
+    readVecString() {
+        const count = this.readU32();
+        const result = [];
+        for (let i = 0; i < count; i++) {
+            result.push(this.readString());
+        }
+        return result;
+    }
+    readOptionVecString() {
+        const tag = this.readU8();
+        if (tag === 0)
+            return undefined;
+        return this.readVecString();
+    }
+    readVecPubkey() {
+        const count = this.readU32();
+        const result = [];
+        for (let i = 0; i < count; i++) {
+            result.push(this.readPubkey());
+        }
+        return result;
+    }
+    readFixedU64Array(count) {
+        const result = [];
+        for (let i = 0; i < count; i++) {
+            result.push(this.readU64AsNumber());
+        }
+        return result;
+    }
+    readFixedBytes(count) {
+        const buf = this.data.subarray(this.offset, this.offset + count);
+        this.offset += count;
+        return Buffer.from(buf);
+    }
+}
+exports.BorshReader = BorshReader;
+// =========================================
+// Buffer writer helper
+// =========================================
+class BorshWriter {
+    buf;
+    offset;
+    constructor(size) {
+        this.buf = Buffer.alloc(size);
+        this.offset = 0;
+    }
+    writeU8(val) {
+        this.buf.writeUInt8(val, this.offset);
+        this.offset += 1;
+    }
+    writeBool(val) {
+        this.writeU8(val ? 1 : 0);
+    }
+    writeU16(val) {
+        this.buf.writeUInt16LE(val, this.offset);
+        this.offset += 2;
+    }
+    writeU32(val) {
+        this.buf.writeUInt32LE(val, this.offset);
+        this.offset += 4;
+    }
+    writeU64(val) {
+        this.buf.writeBigUInt64LE(BigInt(val), this.offset);
+        this.offset += 8;
+    }
+    writeI64(val) {
+        this.buf.writeBigInt64LE(BigInt(val), this.offset);
+        this.offset += 8;
+    }
+    writePubkey(key) {
+        const bytes = addressEncoder.encode(key);
+        for (let i = 0; i < 32; i++) {
+            this.buf[this.offset + i] = bytes[i];
+        }
+        this.offset += 32;
+    }
+    /** Write raw bytes without a length prefix (fixed-size fields). */
+    writeFixedBytes(data) {
+        for (let i = 0; i < data.length; i++) {
+            this.buf[this.offset + i] = data[i];
+        }
+        this.offset += data.length;
+    }
+    writeString(str) {
+        const encoded = Buffer.from(str, 'utf8');
+        this.writeU32(encoded.length);
+        encoded.copy(this.buf, this.offset);
+        this.offset += encoded.length;
+    }
+    writeOptionI64(val) {
+        if (val === undefined) {
+            this.writeU8(0);
+        }
+        else {
+            this.writeU8(1);
+            this.writeI64(val);
+        }
+    }
+    writeOptionU32(val) {
+        if (val === undefined) {
+            this.writeU8(0);
+        }
+        else {
+            this.writeU8(1);
+            this.writeU32(val);
+        }
+    }
+    writeOptionPubkey(key) {
+        if (key === undefined) {
+            this.writeU8(0);
+        }
+        else {
+            this.writeU8(1);
+            this.writePubkey(key);
+        }
+    }
+    writeOptionString(val) {
+        if (val === undefined) {
+            this.writeU8(0);
+        }
+        else {
+            this.writeU8(1);
+            this.writeString(val);
+        }
+    }
+    /** Borsh `Option<Vec<String>>`: 0/1 tag, then u32 length + each string. */
+    writeOptionStringVec(val) {
+        if (val === undefined) {
+            this.writeU8(0);
+        }
+        else {
+            this.writeU8(1);
+            this.writeU32(val.length);
+            for (const s of val)
+                this.writeString(s);
+        }
+    }
+    toBuffer() {
+        return this.buf.subarray(0, this.offset);
+    }
+    getOffset() {
+        return this.offset;
+    }
+}
+exports.BorshWriter = BorshWriter;
+// =========================================
+// Helper: scale factor -> float
+// =========================================
+/** Convert a RATE_SCALE-encoded u64 to a float (e.g., 1_000_000 -> 1.0) */
+function scaleToFloat(value, scale = constants_js_1.RATE_SCALE) {
+    return value / scale;
+}
+// =========================================
+// Gateway deserialization
+// =========================================
+/**
+ * Deserialize a Gateway account from raw bytes.
+ * PDA: ["gateway", operator_pubkey] in ario-gar program.
+ *
+ * Returns the SDK-compatible AoGateway type.
+ */
+function deserializeGateway(data) {
+    const r = new BorshReader(data, 8); // skip 8-byte discriminator
+    const operator = r.readPubkey();
+    const label = r.readString();
+    const fqdn = r.readString();
+    const port = r.readU16();
+    r.readU8(); // protocolIdx: 0=Http, 1=Https
+    const properties = r.readString();
+    const note = r.readString();
+    const operatorStake = r.readU64AsNumber();
+    const totalDelegatedStake = r.readU64AsNumber();
+    const statusIdx = r.readU8(); // 0=Joined, 1=Leaving
+    const startTimestamp = r.readI64AsNumber();
+    const leaveTimestamp = r.readOptionI64();
+    // GatewayStats
+    const passedEpochCount = r.readU32();
+    const failedEpochCount = r.readU32();
+    const totalEpochCount = r.readU32();
+    const prescribedEpochCount = r.readU32();
+    const observedEpochCount = r.readU32();
+    const failedConsecutiveEpochs = r.readU8();
+    const passedConsecutiveEpochs = r.readU8();
+    // GatewayWeights (6 x u64)
+    const stakeWeight = r.readU64AsNumber();
+    const tenureWeight = r.readU64AsNumber();
+    const gatewayPerformanceRatio = r.readU64AsNumber();
+    const observerPerformanceRatio = r.readU64AsNumber();
+    const compositeWeight = r.readU64AsNumber();
+    const normalizedCompositeWeight = r.readU64AsNumber();
+    // GatewaySettings2
+    const allowDelegatedStaking = r.readBool();
+    const delegateRewardShareRatio = r.readU16();
+    const autoStake = r.readBool();
+    const minDelegatedStake = r.readU64AsNumber();
+    const allowlistEnabled = r.readBool();
+    // RegistryIndex (index: u32, _reserved: u8 — was is_registered:bool)
+    r.readU32(); // registryIndex
+    r.readU8(); // _reserved (layout-preserving placeholder for the legacy is_registered byte)
+    // observer_address
+    const observerAddress = r.readPubkey();
+    // cumulative_reward_per_token (u128, not exposed in SDK type)
+    r.skip(16);
+    // bump
+    r.skip(1);
+    const stats = {
+        passedEpochCount,
+        failedEpochCount,
+        totalEpochCount,
+        prescribedEpochCount,
+        observedEpochCount,
+        passedConsecutiveEpochs,
+        failedConsecutiveEpochs,
+    };
+    const weights = {
+        stakeWeight: scaleToFloat(stakeWeight),
+        tenureWeight: scaleToFloat(tenureWeight),
+        gatewayPerformanceRatio: scaleToFloat(gatewayPerformanceRatio),
+        observerPerformanceRatio: scaleToFloat(observerPerformanceRatio),
+        gatewayRewardRatioWeight: scaleToFloat(gatewayPerformanceRatio), // deprecated alias
+        observerRewardRatioWeight: scaleToFloat(observerPerformanceRatio), // deprecated alias
+        compositeWeight: scaleToFloat(compositeWeight),
+        normalizedCompositeWeight: scaleToFloat(normalizedCompositeWeight),
+    };
+    const settings = {
+        allowDelegatedStaking: allowlistEnabled
+            ? 'allowlist'
+            : allowDelegatedStaking,
+        delegateRewardShareRatio,
+        allowedDelegates: [], // populated separately from allowlist PDAs
+        minDelegatedStake,
+        autoStake,
+        label,
+        note,
+        properties,
+        fqdn,
+        port,
+        protocol: 'https', // protocolIdx: 0=Http, 1=Https — only HTTPS in practice
+    };
+    return {
+        operator: operator,
+        settings,
+        stats,
+        totalDelegatedStake,
+        startTimestamp,
+        endTimestamp: leaveTimestamp ?? 0,
+        observerAddress: observerAddress,
+        operatorStake,
+        status: statusIdx === 0 ? 'joined' : 'leaving',
+        weights,
+    };
+}
+// =========================================
+// ArNS Record deserialization
+// =========================================
+/**
+ * Deserialize an ArNS record account from raw bytes.
+ * PDA: ["arns_record", hash(name)] in ario-arns program.
+ *
+ * Field order is **load-bearing** and mirrors the on-chain
+ * `ArnsRecord` struct in `contracts/programs/ario-arns/src/state/mod.rs`.
+ * Every fixed-size field appears before the variable-length `name` so
+ * `getProgramAccounts` callers can `memcmp`-filter on `ant` (offset
+ * 72) — see `ARNS_RECORD_ANT_OFFSET` in `./constants.ts`. If you
+ * touch the contract layout, both files have to move in lockstep.
+ */
+function deserializeArnsRecord(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.readPubkey(); // 32-byte name hash (used as PDA seed)
+    const owner = r.readPubkey();
+    const ant = r.readPubkey(); // ANT Metaplex Core asset address
+    const typeIdx = r.readU8(); // 0=Lease, 1=Permabuy
+    const startTimestamp = r.readI64AsNumber();
+    const endTimestamp = r.readOptionI64();
+    // u16 on-chain — the prior implementation read u32 here and silently
+    // consumed two bytes of `purchase_price`, producing junk for both
+    // fields. Caught while reworking the layout for memcmp filtering.
+    const undernameLimit = r.readU16();
+    const purchasePrice = r.readU64AsNumber();
+    r.skip(1); // bump
+    const name = r.readString();
+    const baseData = {
+        name,
+        owner: owner,
+        processId: ant, // SDK calls ANT address "processId"
+        startTimestamp,
+        undernameLimit,
+        purchasePrice,
+    };
+    if (typeIdx === 0 && endTimestamp !== undefined) {
+        return {
+            ...baseData,
+            type: 'lease',
+            endTimestamp,
+        };
+    }
+    return {
+        ...baseData,
+        type: 'permabuy',
+    };
+}
+// =========================================
+// Vault deserialization
+// =========================================
+/**
+ * Deserialize a Vault account from raw bytes.
+ * PDA: ["vault", owner, vault_id] in ario-core program.
+ *
+ * On-chain layout (matches `state::Vault`):
+ *   disc(8) + owner(Pubkey=32) + vault_id(u64=8) + amount(u64=8)
+ *   + start_timestamp(i64=8) + end_timestamp(i64=8)
+ *   + controller(Option<Pubkey>=33) + revocable(bool=1) + bump(u8=1)
+ */
+function deserializeVault(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const owner = r.readPubkey();
+    // The Rust struct has vault_id BEFORE amount — easy to miss because the
+    // SDK only surfaces `balance` (the AO interface name for `amount`). The
+    // earlier deserializer skipped vault_id and read vault_id-as-balance →
+    // `balance` was always 0 for fresh vaults at index 0.
+    r.skip(8); // vault_id (recoverable from the PDA seeds; not surfaced)
+    const balance = r.readU64AsNumber();
+    const startTimestamp = r.readI64AsNumber();
+    const endTimestamp = r.readI64AsNumber();
+    // controller: Option<Pubkey>
+    const hasController = r.readU8();
+    const controller = hasController ? r.readPubkey() : undefined;
+    // revocable: bool
+    r.readBool();
+    // bump
+    r.skip(1);
+    return {
+        owner: owner,
+        balance,
+        startTimestamp,
+        endTimestamp,
+        controller,
+    };
+}
+/**
+ * Deserialize a Delegation account from raw bytes.
+ * PDA: ["delegation", gateway, delegator] in ario-gar program.
+ */
+function deserializeDelegation(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const gateway = r.readPubkey();
+    const delegator = r.readPubkey();
+    const amount = r.readU64AsNumber();
+    const startTimestamp = r.readI64AsNumber();
+    // reward_debt: u128, bump: u8 — skip
+    r.skip(16 + 1);
+    return {
+        gateway: gateway,
+        delegator: delegator,
+        delegatedStake: amount,
+        startTimestamp,
+    };
+}
+// =========================================
+// Balance deserialization
+// =========================================
+/**
+ * Deserialize a Balance account from raw bytes.
+ * PDA: ["balance", owner] in ario-core program.
+ *
+ * Backed by the Codama-generated decoder so the encoder
+ * (`getBalanceEncoder` used by migration/snapshot) and decoder share a single
+ * source of truth derived from the `ario_core` IDL.
+ */
+function deserializeBalance(data) {
+    const decoded = (0, balance_js_1.getBalanceDecoder)().decode(data);
+    return {
+        owner: decoded.owner,
+        balance: Number(decoded.amount),
+    };
+}
+// =========================================
+// Epoch Settings deserialization
+// =========================================
+function deserializeEpochSettings(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.skip(32); // authority
+    const epochDuration = r.readI64AsNumber();
+    const maxObservers = r.readU8(); // prescribed_observer_count
+    const prescribedNameCount = r.readU8();
+    r.skip(8); // min_observer_stake (u64)
+    r.skip(2); // slash_rate (u16)
+    r.skip(1); // enabled (bool)
+    r.skip(8); // current_epoch_index (u64)
+    const epochZeroStartTimestamp = r.readI64AsNumber(); // genesis_timestamp
+    return {
+        // SDK expects milliseconds (matching AO convention), Solana stores
+        // seconds — convert both timestamps and durations here.
+        epochZeroStartTimestamp: epochZeroStartTimestamp * 1000,
+        durationMs: epochDuration * 1000,
+        prescribedNameCount,
+        maxObservers,
+    };
+}
+// =========================================
+// ArIO Config deserialization
+// =========================================
+/**
+ * Deserialize an ArioConfig account from raw bytes.
+ * PDA: ["ario_config"] in ario-core program.
+ */
+function deserializeArioConfig(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.skip(32); // authority
+    r.skip(32); // mint
+    r.skip(32); // arns_program
+    r.skip(32); // treasury
+    const totalSupply = r.readU64AsNumber();
+    const protocolBalance = r.readU64AsNumber();
+    const circulatingSupply = r.readU64AsNumber();
+    const lockedSupply = r.readU64AsNumber();
+    // remaining fields not needed: min_vault_duration, max_vault_duration,
+    // primary_name_request_expiry, migration_active, migration_authority, bump
+    return {
+        totalSupply,
+        protocolBalance,
+        circulatingSupply,
+        lockedSupply,
+    };
+}
+// =========================================
+// Demand Factor deserialization
+// =========================================
+/**
+ * Deserialize a DemandFactor account from raw bytes.
+ * PDA: ["demand_factor"] in ario-arns program.
+ */
+function deserializeDemandFactor(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const currentDemandFactorRaw = r.readU64AsNumber();
+    const currentPeriod = r.readU64AsNumber();
+    r.skip(8); // purchases_this_period (u64)
+    r.skip(8); // revenue_this_period (u64)
+    const consecutivePeriodsWithMinDemandFactor = r.readU32();
+    const trailingPeriodPurchases = r.readFixedU64Array(7);
+    const trailingPeriodRevenues = r.readFixedU64Array(7);
+    const fees = r.readFixedU64Array(51);
+    const periodZeroStartTimestamp = r.readI64AsNumber();
+    // criteria: u8, bump: u8 — skip
+    return {
+        currentDemandFactor: currentDemandFactorRaw / constants_js_1.RATE_SCALE,
+        currentPeriod,
+        periodZeroStartTimestamp,
+        consecutivePeriodsWithMinDemandFactor,
+        trailingPeriodPurchases,
+        trailingPeriodRevenues,
+        fees,
+    };
+}
+// =========================================
+// Reserved Name deserialization
+// =========================================
+/**
+ * Deserialize a ReservedName account from raw bytes.
+ * PDA: ["reserved_name", hash(name)] in ario-arns program.
+ */
+function deserializeReservedName(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const name = r.readString();
+    const reservedFor = r.readOptionPubkey();
+    const expiresAt = r.readOptionI64();
+    // reserved_by: Pubkey, created_at: i64, bump: u8 — not needed
+    return {
+        name,
+        target: reservedFor,
+        endTimestamp: expiresAt,
+    };
+}
+// =========================================
+// Returned Name deserialization
+// =========================================
+const RETURN_AUCTION_DURATION_SECONDS = 14 * 86_400; // 14 days
+/**
+ * Deserialize a ReturnedName account from raw bytes.
+ * PDA: ["returned_name", hash(name)] in ario-arns program.
+ */
+function deserializeReturnedName(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const name = r.readString();
+    r.skip(32); // name_hash [u8; 32]
+    const initiator = r.readPubkey();
+    const returnedAt = r.readI64AsNumber();
+    // bump: u8 — skip
+    return {
+        name,
+        startTimestamp: returnedAt,
+        endTimestamp: returnedAt + RETURN_AUCTION_DURATION_SECONDS,
+        initiator: initiator,
+        premiumMultiplier: 1, // calculated at query time from elapsed vs auction duration
+    };
+}
+// =========================================
+// Withdrawal deserialization
+// =========================================
+/**
+ * Deserialize a Withdrawal account from raw bytes.
+ * PDA: ["withdrawal", gateway, owner, withdrawal_id] in ario-gar program.
+ */
+function deserializeWithdrawal(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const owner = r.readPubkey();
+    const withdrawalId = r.readU64AsNumber();
+    const gateway = r.readPubkey();
+    const amount = r.readU64AsNumber();
+    const createdAt = r.readI64AsNumber();
+    const availableAt = r.readI64AsNumber();
+    const isDelegate = r.readBool();
+    // is_exit_vault: bool, bump: u8 — skip
+    return {
+        owner: owner,
+        vaultId: String(withdrawalId),
+        gateway: gateway,
+        balance: amount,
+        startTimestamp: createdAt,
+        endTimestamp: availableAt,
+        isDelegate,
+    };
+}
+// =========================================
+// Redelegation Record deserialization
+// =========================================
+/**
+ * Deserialize a RedelegationRecord account from raw bytes.
+ * PDA: ["redelegation", delegator] in ario-gar program.
+ */
+function deserializeRedelegationRecord(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const delegator = r.readPubkey();
+    const redelegationCount = r.readU32();
+    const lastRedelegationAt = r.readI64AsNumber();
+    const feeResetAt = r.readI64AsNumber();
+    // bump: u8 — skip
+    return {
+        delegator: delegator,
+        redelegationCount,
+        lastRedelegationAt,
+        feeResetAt,
+    };
+}
+// =========================================
+// Primary Name Request deserialization
+// =========================================
+/**
+ * Deserialize a PrimaryNameRequest account from raw bytes.
+ * PDA: ["primary_name_request", initiator] in ario-core program.
+ */
+function deserializePrimaryNameRequest(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const initiator = r.readPubkey();
+    const name = r.readString();
+    const createdAt = r.readI64AsNumber();
+    const expiresAt = r.readI64AsNumber();
+    // bump: u8 — skip
+    return {
+        name,
+        initiator: initiator,
+        startTimestamp: createdAt,
+        endTimestamp: expiresAt,
+    };
+}
+// =========================================
+// GAR Settings deserialization (full)
+// =========================================
+/**
+ * Deserialize a GarSettings account from raw bytes and return
+ * the full AoGatewayRegistrySettings type.
+ * PDA: ["gar_settings"] in ario-gar program.
+ *
+ * Fields not stored in GarSettings are filled with protocol defaults.
+ */
+function deserializeGarSettings(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.skip(32); // authority
+    r.skip(32); // mint
+    const minOperatorStake = r.readU64AsNumber();
+    const minDelegateStake = r.readU64AsNumber();
+    const withdrawalPeriod = r.readI64AsNumber(); // seconds
+    const maxExpeditedWithdrawalPenalty = r.readU64AsNumber();
+    const minExpeditedWithdrawalPenalty = r.readU64AsNumber();
+    const minExpeditedWithdrawalAmount = r.readU64AsNumber();
+    r.readU32(); // max_delegates_per_gateway
+    // migration_active: bool, migration_authority: Pubkey, bump: u8 — skip
+    const withdrawalPeriodMs = withdrawalPeriod * 1000;
+    return {
+        delegates: {
+            minStake: minDelegateStake,
+            withdrawLengthMs: withdrawalPeriodMs,
+        },
+        observers: {
+            tenureWeightDurationMs: 15_552_000_000, // 180 days in ms
+            maxTenureWeight: 4,
+        },
+        operators: {
+            minStake: minOperatorStake,
+            withdrawLengthMs: withdrawalPeriodMs,
+            leaveLengthMs: withdrawalPeriodMs,
+            maxDelegateRewardSharePct: 95,
+            failedEpochCountMax: 30,
+            failedGatewaySlashRate: 0,
+        },
+        redelegations: {
+            minRedelegationPenaltyRate: 0,
+            maxRedelegationPenaltyRate: 600_000,
+            minRedelegationAmount: 10_000_000,
+            redelegationFeeResetIntervalMs: 7 * 86_400 * 1000,
+        },
+        expeditedWithdrawals: {
+            minExpeditedWithdrawalPenaltyRate: minExpeditedWithdrawalPenalty,
+            maxExpeditedWithdrawalPenaltyRate: maxExpeditedWithdrawalPenalty,
+            minExpeditedWithdrawalAmount: minExpeditedWithdrawalAmount,
+        },
+    };
+}
+/**
+ * Deserialize supply counter fields from GatewaySettings account.
+ * These 3 fields were added after arns_program_id, before bump.
+ */
+function deserializeGarSupplyCounters(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.skip(32); // authority
+    r.skip(32); // mint
+    r.skip(8); // min_operator_stake
+    r.skip(8); // min_delegate_stake
+    r.skip(8); // withdrawal_period
+    r.skip(8); // max_expedited_withdrawal_penalty
+    r.skip(8); // min_expedited_withdrawal_penalty
+    r.skip(8); // min_expedited_withdrawal_amount
+    r.skip(4); // max_delegates_per_gateway
+    r.skip(1); // migration_active
+    r.skip(32); // migration_authority
+    r.skip(32); // stake_token_account
+    r.skip(32); // protocol_token_account
+    r.skip(32); // arns_program_id
+    const totalStaked = r.readU64AsNumber();
+    const totalDelegated = r.readU64AsNumber();
+    const totalWithdrawn = r.readU64AsNumber();
+    return { totalStaked, totalDelegated, totalWithdrawn };
+}
+// =========================================
+// Epoch Settings Full deserialization
+// =========================================
+/**
+ * Deserialize the full EpochSettings account from raw bytes.
+ * Unlike deserializeEpochSettings (which returns 4 fields), this reads
+ * all fields from the on-chain struct.
+ * PDA: ["epoch_settings"] in ario-gar program.
+ */
+function deserializeEpochSettingsFull(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    r.skip(32); // authority
+    const epochDuration = r.readI64AsNumber();
+    const prescribedObserverCount = r.readU8();
+    const prescribedNameCount = r.readU8();
+    r.skip(8); // min_observer_stake (u64)
+    r.skip(2); // slash_rate (u16)
+    const enabled = r.readU8() !== 0;
+    const currentEpochIndex = r.readU64AsNumber();
+    const genesisTimestamp = r.readI64AsNumber();
+    const tenureWeightDuration = r.readI64AsNumber();
+    const maxTenureWeight = r.readU64AsNumber();
+    const gatewayRewardRatio = r.readU64AsNumber();
+    const observerRewardRatio = r.readU64AsNumber();
+    r.skip(8); // missed_observation_penalty_rate (u64)
+    r.skip(8); // max_reward_rate (u64)
+    r.skip(8); // min_reward_rate (u64)
+    r.skip(8); // reward_decay_start_epoch (u64)
+    r.skip(8); // reward_decay_last_epoch (u64)
+    const maxConsecutiveFailures = r.readU8();
+    // failed_gateway_slash_rate: u64, bump: u8 — skip
+    return {
+        currentEpochIndex,
+        genesisTimestamp,
+        epochDuration,
+        enabled,
+        prescribedObserverCount,
+        prescribedNameCount,
+        tenureWeightDuration,
+        maxTenureWeight,
+        gatewayRewardRatio,
+        observerRewardRatio,
+        maxConsecutiveFailures,
+    };
+}
+// =========================================
+// Epoch deserialization (zero-copy #[repr(C)])
+// =========================================
+/**
+ * Deserialize an Epoch account from raw bytes.
+ * PDA: ["epoch", epoch_index_le_bytes] in ario-gar program.
+ *
+ * This is a zero-copy account with #[repr(C)] layout (not Borsh).
+ * Fields are at fixed offsets after the 8-byte discriminator.
+ */
+function deserializeEpoch(data) {
+    // All offsets relative to start of struct (after 8-byte discriminator)
+    const base = 8;
+    const epochIndex = Number(data.readBigUInt64LE(base + 0));
+    const startTimestamp = Number(data.readBigInt64LE(base + 8));
+    const endTimestamp = Number(data.readBigInt64LE(base + 16));
+    const totalEligibleRewards = Number(data.readBigUInt64LE(base + 24));
+    const perGatewayReward = Number(data.readBigUInt64LE(base + 32));
+    const perObserverReward = Number(data.readBigUInt64LE(base + 40));
+    const rewardRate = Number(data.readBigUInt64LE(base + 48));
+    // total_composite_weight_lo/hi at 56, 64 — skip
+    // hashchain at 72 — skip (32 bytes)
+    const activeGatewayCount = data.readUInt32LE(base + 104);
+    const distributionIndex = data.readUInt32LE(base + 108);
+    const tallyIndex = data.readUInt32LE(base + 112);
+    const observerCount = data.readUInt8(base + 116);
+    const nameCount = data.readUInt8(base + 117);
+    const observationsSubmitted = data.readUInt8(base + 118);
+    const rewardsDistributed = data.readUInt8(base + 119);
+    const weightsTallied = data.readUInt8(base + 120);
+    const prescriptionsDone = data.readUInt8(base + 121);
+    // bump at 122, _padding1 at 123
+    // failure_counts: [u16; 3000] at offset 124
+    const failureCounts = new Uint16Array(3000);
+    for (let i = 0; i < 3000; i++) {
+        failureCounts[i] = data.readUInt16LE(base + 124 + i * 2);
+    }
+    // prescribed_observers: [Pubkey; 50] at offset 6124
+    const prescribedObservers = [];
+    for (let i = 0; i < 50; i++) {
+        const off = base + 6124 + i * 32;
+        prescribedObservers.push(addressDecoder.decode(data.subarray(off, off + 32)));
+    }
+    // prescribed_observer_gateways: [Pubkey; 50] at offset 7724
+    const prescribedObserverGateways = [];
+    for (let i = 0; i < 50; i++) {
+        const off = base + 7724 + i * 32;
+        prescribedObserverGateways.push(addressDecoder.decode(data.subarray(off, off + 32)));
+    }
+    // prescribed_names: [[u8; 32]; 2] at offset 9324
+    const prescribedNameHashes = [];
+    for (let i = 0; i < 2; i++) {
+        const off = base + 9324 + i * 32;
+        prescribedNameHashes.push(Buffer.from(data.subarray(off, off + 32)));
+    }
+    // has_observed: [u8; 7] at offset 9388
+    const hasObserved = new Uint8Array(data.subarray(base + 9388, base + 9395));
+    return {
+        epochIndex,
+        startTimestamp,
+        endTimestamp,
+        totalEligibleRewards,
+        perGatewayReward,
+        perObserverReward,
+        rewardRate,
+        activeGatewayCount,
+        distributionIndex,
+        tallyIndex,
+        observerCount,
+        nameCount,
+        observationsSubmitted,
+        rewardsDistributed,
+        weightsTallied,
+        prescriptionsDone,
+        failureCounts,
+        prescribedObservers,
+        prescribedObserverGateways,
+        prescribedNameHashes,
+        hasObserved,
+    };
+}
+// =========================================
+// Observation deserialization
+// =========================================
+/**
+ * Deserialize an Observation account from raw bytes.
+ * PDA: ["observation", epoch_index_le_bytes, observer_pubkey] in ario-gar program.
+ */
+function deserializeObservation(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const epochIndex = r.readU64AsNumber();
+    const observer = r.readPubkey();
+    const gatewayResults = r.readFixedBytes(375);
+    const gatewayCount = r.readU16();
+    const reportTxId = r.readFixedBytes(32).toString('base64url');
+    const submittedAt = r.readI64AsNumber();
+    return {
+        epochIndex,
+        observer,
+        gatewayResults,
+        gatewayCount,
+        reportTxId,
+        submittedAt,
+    };
+}
+// =========================================
+// ANT Config deserialization
+// =========================================
+/**
+ * Deserialize an AntConfig account from raw bytes.
+ * PDA: ["ant_config", mint] in ario-ant program.
+ */
+function deserializeAntConfig(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const mint = r.readPubkey();
+    const name = r.readString();
+    const ticker = r.readString();
+    const logo = r.readString();
+    const description = r.readString();
+    const keywords = r.readVecString();
+    const lastKnownOwner = r.readPubkey();
+    r.readU8(); // bump
+    let version = 0;
+    try {
+        version = r.readU8();
+    }
+    catch {
+        /* pre-version accounts default to 0 */
+    }
+    return {
+        mint: mint,
+        name,
+        ticker,
+        logo,
+        description,
+        keywords,
+        owner: lastKnownOwner,
+        version,
+    };
+}
+// =========================================
+// ANT Controllers deserialization
+// =========================================
+/**
+ * Deserialize an AntControllers account from raw bytes.
+ * PDA: ["ant_controllers", mint] in ario-ant program.
+ */
+function deserializeAntControllers(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const mint = r.readPubkey();
+    const controllers = r.readVecPubkey().map((pk) => pk);
+    // bump: u8 — skip
+    return {
+        mint: mint,
+        controllers,
+    };
+}
+// =========================================
+// ANT Record deserialization
+// =========================================
+/**
+ * Deserialize an AntRecord account from raw bytes.
+ * PDA: ["ant_record", mint, hash(undername)] in ario-ant program.
+ */
+function deserializeAntRecord(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const mint = r.readPubkey();
+    const undername = r.readString();
+    const transactionId = r.readString(); // on-chain field: target
+    const targetProtocol = r.readU8(); // 0 = Arweave, 1 = IPFS
+    const ttlSeconds = r.readU32();
+    const priority = r.readOptionU32();
+    const ownerPk = r.readOptionPubkey();
+    // last_reconciled_owner: Pubkey, bump: u8 — skip
+    return {
+        mint: mint,
+        undername,
+        transactionId,
+        targetProtocol,
+        ttlSeconds,
+        priority,
+        owner: ownerPk,
+    };
+}
+/**
+ * Deserialize an AntRecordMetadata account from raw bytes.
+ * This is a separate PDA that holds optional per-record metadata fields.
+ */
+function deserializeAntRecordMetadata(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const mint = r.readPubkey();
+    r.skip(32); // undername_hash — [u8; 32], not needed by callers
+    const displayName = r.readOptionString();
+    const logo = r.readOptionString();
+    const description = r.readOptionString();
+    const keywords = r.readOptionVecString();
+    // bump: u8 — skip
+    return { mint, displayName, logo, description, keywords };
+}
+/**
+ * Deserialize an `AclConfig` account (paginated ACL head — ADR-012).
+ * PDA: `["acl_config", user]` in ario-ant program.
+ *
+ * Holds counts but no entries. Read this first, then fan out to each
+ * `AclPage` PDA (`["acl_page", user, page_idx_le]`) for the entries.
+ */
+function deserializeAclConfig(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const user = r.readPubkey();
+    const pageCount = r.readU64();
+    const totalEntries = r.readU64();
+    // bump: u8 — managed by Anchor
+    return {
+        user: user,
+        pageCount,
+        totalEntries,
+    };
+}
+/**
+ * Deserialize an `AclPage` account (paginated ACL page — ADR-012).
+ * PDA: `["acl_page", user, page_idx_le]` in ario-ant program.
+ *
+ * Stores up to `MAX_ACL_PAGE_ENTRIES` `(asset, role)` entries. Pages can
+ * be sparse mid-life (entries are removed via `swap_remove`) — the SDK's
+ * append path fills the first non-full page to keep density reasonable.
+ */
+function deserializeAclPage(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const user = r.readPubkey();
+    const pageIdx = r.readU64();
+    const entryCount = r.readU32();
+    const entries = [];
+    for (let i = 0; i < entryCount; i++) {
+        const asset = r.readPubkey();
+        const role = r.readU8();
+        entries.push({ asset: asset, role });
+    }
+    // bump: u8 — managed by Anchor
+    return {
+        user: user,
+        pageIdx,
+        entries,
+    };
+}
+// =========================================
+// Primary Name deserialization
+// =========================================
+/**
+ * Deserialize a PrimaryName account from raw bytes.
+ * PDA: ["primary_name", owner] in ario-core program.
+ */
+function deserializePrimaryName(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const owner = r.readPubkey();
+    const name = r.readString();
+    const processId = r.readPubkey();
+    const startTimestamp = r.readI64AsNumber();
+    // bump: u8 — skip
+    return {
+        owner: owner,
+        name,
+        processId: processId,
+        startTimestamp,
+    };
+}
+// =========================================
+// Allowlist deserialization
+// =========================================
+/**
+ * Deserialize an Allowlist entry account from raw bytes.
+ * PDA: ["allowlist", gateway, delegate] in ario-gar program.
+ */
+function deserializeAllowlist(data) {
+    const r = new BorshReader(data, 8); // skip discriminator
+    const gateway = r.readPubkey();
+    const delegate = r.readPubkey();
+    // bump: u8 — skip
+    return {
+        gateway: gateway,
+        delegate: delegate,
+    };
+}