Equipment and Custody: The Record Moves With the Tool

    pub fn slot_identity(data: &[u8], slot: u8) -> Result<Pubkey, NicechunkPlayerError> {
        let offset =
            Self::slot_offset(slot).map_err(|_| NicechunkPlayerError::InvalidEquipmentSlot)?;
        Self::validate_layout(data)?;
        if data[offset + Self::RECORD_STATE_OFFSET] != 1 {
            return Ok(Pubkey::default());
        }
        Ok(Pubkey::new_from_array(
            solana_program::hash::hashv(&[
                b"equipment-v2",
                &data[offset + Self::RECORD_BACKPACK_OFFSET
                    ..offset + Self::RECORD_BACKPACK_OFFSET + 32],
                &data[offset + Self::RECORD_BACKPACK_SLOT_OFFSET
                    ..offset + Self::RECORD_BACKPACK_SLOT_OFFSET + BACKPACK_SLOT_RECORD_LEN],
            ])
            .to_bytes(),
        ))
    }

An empty slot publishes zero. An active slot hashes the source Backpack address and all 80 current record bytes under the equipment-v2 tag; item_pda, slot index, and model bytes are not the Profile value by themselves.

1. Lines 1–7

   Validate the slot and complete account layout, returning the zero identity for an empty slot.

2. Lines 8–19

   Hash the tag, source Backpack address, and complete record into the 32-byte identity.

    let clears_slot = backpack_index == CLEAR_EQUIPMENT_BACKPACK_INDEX;
    let (was_equipped, was_custodied) = {
        let equipment_data = player_equipment.try_borrow_data()?;
        PlayerEquipment::validate_owner_and_config(
            &equipment_data,
            authority.key,
            player_profile.key,
            global_config.key,
        )?;
        (
            PlayerEquipment::slot_is_equipped(&equipment_data, slot)?,
            PlayerEquipment::slot_is_custodied(&equipment_data, slot)?,
        )
    };

    let mut next_identity = Pubkey::default();
    if clears_slot {
        if was_custodied {
            invoke_backpack_equipment_transfer(
                game_program,
                transfer_authority,
                authority,
                backpack,
                player_equipment,
                material_physics,
                &[1, 11, slot],
                transfer_bump,
            )?;
        }
        if was_equipped {
            let mut equipment_data = player_equipment.try_borrow_mut_data()?;
            PlayerEquipment::clear_slot(&mut equipment_data, slot, clock.slot)?;
        }
    } else {
        let backpack_record = {
            let backpack_data = backpack.try_borrow_data()?;
            BackpackAccountView::validate_pda_and_owner(
                &backpack_data,
                backpack.key,
                backpack.owner,
                authority.key,
            )?;
            BackpackAccountView::equipment_record_at(&backpack_data, authority.key, backpack_index)?
        };
        invoke_backpack_equipment_transfer(
            game_program,
            transfer_authority,
            authority,
            backpack,
            player_equipment,
            material_physics,
            &[1, 10, slot, backpack_index],
            transfer_bump,
        )?;
        {
            let mut equipment_data = player_equipment.try_borrow_mut_data()?;
            PlayerEquipment::write_custodied_slot(
                &mut equipment_data,
                slot,
                backpack_index,
                backpack.key,
                &backpack_record,
                &payload[4..],
                clock.slot,
            )?;
            next_identity = PlayerEquipment::slot_identity(&equipment_data, slot)?;
        }
    }

    let mut profile_data = player_profile.try_borrow_mut_data()?;
    PlayerProfile::write_equipment_slot(&mut profile_data, slot, &next_identity, clock.slot)

Clearing returns a custodied record to Backpack. Equipping validates the Backpack record, transfers it into PlayerEquipment, stores the full record and model bytes, and publishes only the resulting identity through PlayerProfile.

1. Lines 1–13

   Validate PlayerEquipment and remember whether the selected slot currently carries an equipped identity and an item held in equipment custody.

2. Lines 15–31

   A clear request returns a custodied item through the Backpack transfer instruction, then clears any remaining equipped slot state.

3. Lines 32–66

   An equip request validates one Backpack record, moves custody, stores the record and model in PlayerEquipment, and derives the public slot identity.

4. Lines 68–69

   PlayerProfile receives only that resulting identity, while the complete item record remains in PlayerEquipment custody.

    pub fn equipment_record_at(
        data: &[u8],
        owner: &Pubkey,
        index: u8,
    ) -> Result<[u8; BACKPACK_SLOT_RECORD_LEN], NicechunkPlayerError> {
        Self::validate_owner(data, owner).map_err(|_| NicechunkPlayerError::InvalidBackpackData)?;
        if index >= data[BACKPACK_ITEM_COUNT_OFFSET] {
            return Err(NicechunkPlayerError::InvalidBackpackItem);
        }
        let offset = BACKPACK_HEADER_LEN + index as usize * BACKPACK_SLOT_RECORD_LEN;
        if offset + BACKPACK_SLOT_RECORD_LEN > data.len() {
            return Err(NicechunkPlayerError::InvalidBackpackData);
        }
        let kind = data[offset];
        if (kind != BACKPACK_SLOT_KIND_BLOCK && kind != BACKPACK_SLOT_KIND_ITEM)
            || read_u32(data, offset + BACKPACK_SLOT_QUANTITY_OFFSET) == 0
        {
            return Err(NicechunkPlayerError::InvalidBackpackItem);
        }
        if kind == BACKPACK_SLOT_KIND_ITEM
            && (read_u64(data, offset + BACKPACK_SLOT_ITEM_ID_OFFSET) == 0
                || data[offset + BACKPACK_SLOT_ITEM_PDA_OFFSET
                    ..offset + BACKPACK_SLOT_ITEM_PDA_OFFSET + 32]
                    .iter()
                    .all(|byte| *byte == 0))
        {
            return Err(NicechunkPlayerError::InvalidBackpackItem);
        }
        data[offset..offset + BACKPACK_SLOT_RECORD_LEN]
            .try_into()
            .map_err(|_| NicechunkPlayerError::InvalidBackpackData)
    }

The current path returns the complete 80-byte record and accepts both block and item kinds. It requires quantity for either kind and nonzero item ID plus item_pda for item records; forged-specific NCF1 validation happens separately when PlayerEquipment writes the slot.

1. Lines 1–13

   Validate the owner-bound Backpack layout, dense index, and complete record bounds.

2. Lines 14–19

   Accept only block or item records with nonzero quantity.

3. Lines 20–33

   Require identifiers for item records, then return all 80 bytes rather than one pointer.

    let outcome = {
        let mut backpack_data = backpack.try_borrow_mut_data()?;
        BackpackAccount::forge_equipment_from_verified_materials(
            &mut backpack_data,
            owner.key,
            indexes,
            item_id,
            design_hash,
            forged_item.key,
            forging_level,
            clock.slot,
            requirements,
        )?
    };

    add_forging_xp_to_player(
        program_id,
        owner,
        backpack,
        player_profile,
        player_program,
        system_program_account,
        &outcome,
    )
}

The Backpack record receives forged_item.key, not PlayerProfile. The immutable ForgedItem account identifies this output, and the following Player CPI adds XP in the same atomic transaction.

1. Lines 1–13

   Borrow Backpack mutably and settle verified materials into one forged output whose stored item_pda is the supplied immutable ForgedItem account.

2. Lines 15–23

   Pass the completed forge outcome to the Player Program CPI so forging XP is recorded before the surrounding transaction can succeed.

    let item_id_bytes = item_id.to_le_bytes();
    let (expected_forged_item, forged_item_bump) = Pubkey::find_program_address(
        &[FORGED_ITEM_SEED, owner.key.as_ref(), &item_id_bytes],
        program_id,
    );
    require_key_eq(
        forged_item.key,
        &expected_forged_item,
        NicechunkBackpackError::InvalidForgedItemPda,
    )?;
    if forged_item.owner == program_id {
        return Err(NicechunkBackpackError::ForgedItemAlreadyInitialized.into());
    }
    if forged_item.owner != &system_program::ID || forged_item.data_len() != 0 {
        return Err(NicechunkBackpackError::InvalidSystemAccount.into());
    }
    create_forged_item_pda(
        owner,
        forged_item,
        system_program_account,
        program_id,
        item_id,
        forged_item_bump,
    )?;
    {
        let mut forged_item_data = forged_item.try_borrow_mut_data()?;
        ForgedItemAccount::pack(
            &mut forged_item_data,
            &ForgedItemInitArgs {
                bump: forged_item_bump,
                item_id,
                creator: owner.key,
                origin_backpack: backpack.key,
                design_hash,
                code,
                created_slot: clock.slot,
                created_at: clock.unix_timestamp,
            },
        )?;
    }

The address is unique to creator and item ID, must still be an empty System account, and is allocated and packed with the complete verified model before the Backpack output is appended.

1. Lines 1–10

   Derive and require the exact forged-item-v1 PDA for creator and little-endian item ID.

2. Lines 11–24

   Reject reuse or a nonempty foreign account, then create the final-sized PDA.

3. Lines 25–41

   Pack creator, origin Backpack, design hash, complete NCF1 bytes, and creation observations.

        let mut output = BackpackSlotRecord {
            kind: BACKPACK_SLOT_KIND_ITEM,
            category: BACKPACK_ITEM_CATEGORY_FORGED,
            flags: 0,
            quantity: 1,
            resource: BackpackResourceRecord::default(),
            item_code: BACKPACK_FORGED_ITEM_CODE,
            item_id,
            item_pda: *item_pda,
            volume_mm3: outcome.volume_mm3,
            durability_current: outcome.durability_max,
            durability_max: outcome.durability_max,
            grade: outcome.grade,
            item_level: outcome.item_level,
            quality_bps: outcome.quality_bps,
            metadata: design_hash,
        };
        output.set_mass_grams(outcome.mass_grams)?;
        Self::append_item(data, owner, &output, updated_slot)?;
        Ok(outcome)

item_pda receives the already-derived ForgedItem address. The same record carries item ID, calculated mass and volume, durability, grade, level, quality, and design hash before it enters the dense Backpack.

1. Lines 1–9

   Construct one forged item record and copy its unique ForgedItem PDA.

2. Lines 10–16

   Store calculated volume, durability, grade, level, quality, and design hash.

3. Lines 17–18

   Append the complete record to the dense Backpack.

export const NCF1_EQUIPMENT_VERSION = 15;
export const NCF1_EQUIPMENT_MIN_RAW_BYTES = 14;
export const NCF1_EQUIPMENT_MAX_RAW_BYTES = 640;

export function equipmentPayloadBytes(value) {
  if (value instanceof Uint8Array) return value.length ? value : null;
  if (Array.isArray(value)) return value.length ? Uint8Array.from(value) : null;
  if (value instanceof ArrayBuffer) return value.byteLength ? new Uint8Array(value) : null;
  if (ArrayBuffer.isView(value)) {
    return value.byteLength
      ? new Uint8Array(value.buffer, value.byteOffset, value.byteLength)
      : null;
  }
  return null;
}

export function validatedNcf1EquipmentPayload(value, expectedDesignHash) {
  const bytes = equipmentPayloadBytes(value);
  const designHash = Math.trunc(Number(expectedDesignHash) || 0) >>> 0;
  if (!bytes
    || !designHash
    || bytes.length < NCF1_EQUIPMENT_MIN_RAW_BYTES
    || bytes.length > NCF1_EQUIPMENT_MAX_RAW_BYTES
    || !isSupportedNcf1EquipmentVersion(bytes[0] >> 4)
    || forgePayloadHash(bytes) !== designHash) return null;
  return bytes;
}

function isSupportedNcf1EquipmentVersion(version) {
  return version === NCF1_EQUIPMENT_VERSION;
}

The validator requires a nonzero design hash, 14-640 bytes, the current version-15 nibble, and exact FNV-1a equality. Version 14 is intentionally rejected because this testnet build has no legacy fallback.

1. Lines 1–15

   Declare the final NCF1 envelope and normalize supported byte-container types without inventing replacement payload bytes.

2. Lines 17–26

   Reject missing hashes, out-of-range lengths, non-v15 bytes, and any payload whose computed design hash differs.

3. Lines 28–30

   Accept only the current version nibble, with no historical-version fallback.

export function guardianEquipmentFromAvatarEquipment(equipment = {}) {
  const rightHand = String(equipment?.rightHand || "empty");
  if (rightHand === "pickaxe") {
    const designHash = Math.trunc(Number(equipment.designHash) || 0) >>> 0;
    const forged = Boolean(equipment.forged || equipment.isForged || designHash);
    return {
      rightHandKind: forged ? EQUIPMENT_KIND.forged : EQUIPMENT_KIND.pickaxe,
      rightHandVariant: forged ? 2 : 1,
      flags: forged ? EQUIPMENT_FLAG_FORGED : 0,
      designHash: forged ? designHash : 0,
      payloadBytes: forged ? validatedNcf1EquipmentPayload(equipment.payloadBytes, designHash) : null,
    };
  }
  if (rightHand === "block") {
    const blockId = Math.trunc(equipment.blockId || 0);
    return { rightHandKind: EQUIPMENT_KIND.block, rightHandVariant: BLOCK_VARIANT_BY_ID.get(blockId) || clampByte(blockId), flags: 0, designHash: blockId >>> 0 };
  }
  return { rightHandKind: EQUIPMENT_KIND.empty, rightHandVariant: 0, flags: 0, designHash: 0 };
}

export function equipmentFromGuardianEvent(event = {}) {
  const kind = Math.trunc(event?.rightHandKind ?? EQUIPMENT_KIND.empty);
  if (kind === EQUIPMENT_KIND.pickaxe || kind === EQUIPMENT_KIND.forged) {
    const designHash = Math.trunc(Number(event.designHash) || 0) >>> 0;
    const forged = Boolean(
      kind === EQUIPMENT_KIND.forged
      || (Math.trunc(Number(event.flags) || 0) & EQUIPMENT_FLAG_FORGED)
      || designHash
      || Math.trunc(Number(event.rightHandVariant) || 0) === 2
    );
    return forged
      ? { rightHand: "pickaxe", forged: true, designHash, payloadBytes: validatedNcf1EquipmentPayload(event.payloadBytes, designHash) }
      : { rightHand: "pickaxe" };
  }
  if (kind === EQUIPMENT_KIND.block) return { rightHand: "block", blockId: Math.trunc(event.rightHandVariant || 0), color: [0.52, 0.72, 0.38, 1] };
  return { rightHand: "empty" };
}

Production encodes only right-hand kind and variant, a forged flag, design hash, and optional validated NCF1. Incoming forged bytes pass through the same validator. It embeds neither Profile equipment keys nor Backpack presentation fields and proves no custody.

1. Lines 1–18

   Encode current right-hand presentation and validate forged bytes before sending.

2. Lines 20–33

   Decode forged presentation while applying the same payload validation.

3. Lines 34–36

   Reduce block and empty messages to bounded presentation state.

    let mut backpack_source = None;
    let mut equipment_source = None;
    let source_slot = match args.source_type {
        SOURCE_BACKPACK => {
            let backpack = next_account_info(account_info_iter)?;
            let backpack_program = next_account_info(account_info_iter)?;
            require_key_eq(
                backpack_program.key,
                &NICECHUNK_BACKPACK_PROGRAM_ID,
                NicechunkMarketError::InvalidBackpackProgram,
            )?;
            let source_slot =
                read_backpack_slot_for_listing(backpack, seller.key, args.source_index)?;
            backpack_source = Some((backpack, backpack_program));
            source_slot
        }
        SOURCE_EQUIPMENT => {
            let player_profile = next_account_info(account_info_iter)?;
            let player_equipment = next_account_info(account_info_iter)?;
            let global_config = next_account_info(account_info_iter)?;
            let player_program = next_account_info(account_info_iter)?;
            require_key_eq(
                player_program.key,
                &NICECHUNK_PLAYER_PROGRAM_ID,
                NicechunkMarketError::InvalidPlayerProgram,
            )?;
            let source_slot = read_equipment_slot_for_listing(
                player_profile,
                player_equipment,
                seller.key,
                args.source_index,
                player_program.key,
                global_config.key,
            )?;
            equipment_source = Some((
                player_profile,
                player_equipment,
                global_config,
                player_program,
            ));
            source_slot
        }
        _ => return Err(NicechunkMarketError::InvalidInstruction.into()),
    };
    let market_user = next_account_info(account_info_iter)?;
    validate_transferable_source_slot(&source_slot)?;

    let clock = Clock::get()?;
    validate_existing_market_user(program_id, market_user, seller.key)?;
    if !market_user.is_writable {
        return Err(NicechunkMarketError::InvalidMarketUser.into());
    }
    {
        let mut data = market_user.try_borrow_mut_data()?;
        MarketUserState::validate(&data, seller.key)?;
        MarketUserState::increment_active(&mut data, clock.slot)?;
    }

    create_listing_pda(
        seller,
        listing,
        system_program_account,
        program_id,
        args.listing_id,
        bump,
    )?;

    {
        let mut data = listing.try_borrow_mut_data()?;
        ListingAccount::pack(
            &mut data,
            &ListingInitArgs {
                bump,
                seller: seller.key,
                listing_id: args.listing_id,
                currency: args.currency,
                source_type: args.source_type,
                source_index: args.source_index,
                price_base_units: args.price_base_units,
                source_slot,
                created_slot: clock.slot,
                created_at: clock.unix_timestamp,
            },
        )?;
    }

    if let Some((backpack, backpack_program)) = backpack_source {
        remove_backpack_resource(seller, backpack, backpack_program, args.source_index as u16)?;
    }
    if let Some((player_profile, player_equipment, global_config, player_program)) =
        equipment_source
    {
        release_player_equipment_to_market(
            seller,
            player_profile,
            player_equipment,
            global_config,
            listing,
            player_program,
        )?;
    }
    Ok(())

Backpack source copies one dense record; equipment source reads one custodied PlayerEquipment slot. Membership, Listing creation, and source removal all succeed or roll back together.

1. Lines 1–16

   For a Backpack source, validate the Backpack Program and copy the selected dense slot before mutation.

2. Lines 17–43

   For an equipment source, validate Player Program custody and snapshot the selected PlayerEquipment slot.

3. Lines 44–81

   Validate transferability and seller membership, increment active count, create the Listing PDA, and pack the copied source record.

4. Lines 83–99

   Remove exactly the chosen Backpack or equipment source; any later error rolls the entire Solana instruction back.

      const result = await module.createMarketListingOnChain({
        item: {
          source: marketSourceForSlot(item.slot),
          backpack: item.slot.chainBackpack,
          slotIndex: marketSourceIndexForSlot(item.slot),
          category,
        },
        currency,
        price,
        backpackAddress: item.slot.chainBackpack,
      });

The caller derives source type and index from the selected slot. Backpack records remain Backpack sources; custodied toolbar records use PlayerEquipment slot indexes.

1. Lines 1–5

   Build the item descriptor from the selected UI slot, preserving its chain source family and source index.

2. Lines 6–9

   Pass currency, price, and Backpack context to the chain module without rewriting equipment custody as Backpack custody.

      const result = await module.cancelMarketListingOnChain({
        listing: listing.listing,
        listingId: listing.listingId,
      });
      if (!result?.submitted) {
        handleMarketAccessReason(result?.reason);
        const message = ui("main.market.cancelFailed", "Cancel transaction failed: {reason}", {
          reason: marketSubmissionReason(result?.reason, ui, "cancel"),
        });
        showMarketStatus(message, "warn");
        showTradeToast(message, "error");
        return result;
      }

The UI supplies Listing identity. The chain helper resolves the equipped Backpack when needed, validates membership, and builds the final eight-account cancellation instruction.

1. Lines 1–4

   Submit only the Listing address and ID from the UI, leaving destination custody resolution to the chain helper.

2. Lines 5–13

   Convert a rejected submission into localized status and toast feedback, then stop without claiming cancellation succeeded.

    try {
      const module = await loadPlayChainModule();
      if (typeof module.setPlayerEquipmentSlotsOnChain !== "function") {
        throw new Error("equipment-save-unavailable");
      }
      const result = await module.setPlayerEquipmentSlotsOnChain(batch.map((change) => ({
        slot: change.index,
        beforeReference: change.beforeReference || null,
        reference: change.reference || null,
      })));
      if (!result?.submitted) throw new Error(String(result?.reason || "equipment-not-submitted"));
      mutation.lastSubmittedAt = Date.now();
      mutation.lastSignature = String(result.signature || "");
      mutation.lastReason = "saved";
      mutation.lastError = "";
      state.equipment = result.equipment?.initialized ? result.equipment : state.equipment;
      state.equipmentReadKnown = true;
      await refreshBackpack({ force: true, quiet: true });
      if (!pendingEquipmentChanges.size) applyEquipmentSnapshot({ force: true });
      appendEvent(ui("main.equipment.chainSaved", "Equipment saved on chain ({signature}).", {
        signature: shortSignature(mutation.lastSignature),
      }));
    } catch (error) {
      mutation.lastError = readableError(error);
      mutation.lastReason = "error";
      const rollback = batch.filter((change) => !pendingEquipmentChanges.has(change.index));
      getGameState()?.restoreEquipmentMutation?.(rollback);

The production player controller calls the chain equipment writer, adopts the returned PlayerEquipment account, refreshes Backpack state, and reapplies the authoritative snapshot. A failed batch restores local mutations instead of presenting them as saved.

1. Lines 1–10

   Load the production chain module and submit exact before/after references for each changed hotbar slot.

2. Lines 11–22

   Require submission success, adopt returned equipment, refresh Backpack custody, and render the authoritative snapshot.

3. Lines 23–27

   On failure, retain the error and restore local slot mutations that were not superseded.

async function hydrateForgedItemSlots(slots, conn, reportScope) {
  const candidates = (slots ?? []).filter((slot) => (
    slot?.kindCode === backpackSlotKindItem
    && slot.category === backpackItemCategoryForged
    && slot.itemCode === backpackForgedItemCode
    && slot.itemPda
    && slot.itemPda !== PublicKey.default.toBase58()
  ));
  if (!candidates.length) return slots;

  const addresses = Array.from(new Set(candidates.map((slot) => slot.itemPda))).map(
    (address) => new PublicKey(address),
  );
  let accounts;
  try {
    accounts = await getMultipleAccountsInfoBatched(conn, addresses, 100);
  } catch (error) {
    reportRpcError(error, reportScope);
    return slots;
  }
  const decodedByAddress = new Map();
  for (let index = 0; index < addresses.length; index += 1) {
    const account = accounts[index];
    if (!account?.data?.length || !account.owner.equals(gameContext.backpackProgramId)) continue;
    try {
      const decoded = decodeForgedItem(account.data);
      const [expected] = deriveForgedItemPda(
        new PublicKey(decoded.creator),
        decoded.itemId,
        gameContext.backpackProgramId,
      );
      if (!expected.equals(addresses[index])) continue;
      decodedByAddress.set(addresses[index].toBase58(), decoded);
    } catch {
      // Invalid immutable model accounts are ignored and cannot be equipped.
    }
  }

  for (const slot of candidates) {
    const forgedItem = decodedByAddress.get(slot.itemPda);
    if (
      !forgedItem
      || forgedItem.itemId !== slot.itemId
      || forgedItem.designHash !== (Number(slot.metadata) >>> 0)
    ) {
      continue;
    }
    slot.forgedItem = forgedItem;
    slot.modelBytes = Array.from(forgedItem.codeBytes);
  }
  return slots;
}

Backpack and Listing hydration loads unique item_pda accounts in batches, validates program ownership and PDA derivation, and attaches model bytes only when item ID and design hash also match the containing record.

1. Lines 1–19

   Select current forged records, deduplicate their item_pda addresses, and batch-fetch account data.

2. Lines 20–34

   Require the configured program owner, decode the final layout, and rederive each PDA from creator and item ID.

3. Lines 36–49

   Match item ID and design hash before exposing canonical NCF1 bytes to rendering or equip.

  function toolReachSphere({ yaw = null, swing = null } = {}) {
    const geometry = selectedToolGeometry();
    if (!geometry?.avatarMesh || !geometry.collisionParts.length) return fallbackToolReachSphere(toolYaw(yaw, swing));
    const pivot = geometry.avatarMesh.pivots?.right_hand_item ?? geometry.avatarMesh.pivots?.right_arm;
    if (!Array.isArray(pivot)) return fallbackToolReachSphere(toolYaw(yaw, swing));
    if (reachCacheMesh !== geometry.avatarMesh || reachCacheEquipmentId !== geometry.equipmentId) {
      reachCacheMesh = geometry.avatarMesh;
      reachCacheEquipmentId = geometry.equipmentId;
      reachCacheRadius = toolReachRadius(geometry.collisionParts, pivot);
    }
    const center = avatarLocalToWorld(pivot, toolYaw(yaw, swing));
    return {
      x: center[0],
      y: center[1],
      z: center[2],
      centerX: center[0],
      centerY: center[1],
      centerZ: center[2],
      radius: reachCacheRadius,
      radiusSquared: reachCacheRadius * reachCacheRadius,
      equipmentId: geometry.equipmentId,
    };
  }

The resolver takes collision parts from the selected avatar tool and its right-hand pivot, calculates a radius, and places that sphere in world space. Forged geometry is attached only after local runtime and grip restoration, so this is presentation logic rather than a Profile-slot check.

1. Lines 1–5

   Resolve selected geometry and its right-hand pivot, with a basic fallback only when geometry is unavailable.

2. Lines 6–10

   Recalculate reach when mesh or equipment identity changes.

3. Lines 11–22

   Transform the hand pivot into world space and return the geometry-derived sphere.

  function toolCollisionHitForProgress(swing, toProgress) {
    const endProgress = clamp01(toProgress);
    const startProgress = Math.max(collisionStartProgress, Math.min(endProgress, Number(swing.previousToolProgress) || collisionStartProgress));
    let previousBoxes = swing.previousToolBoxes;
    let previousCount = swing.previousToolBoxCount || 0;
    if (!previousBoxes || !previousCount) {
      const startFrame = getToolCollisionFrame?.({ progress: startProgress, swing });
      const startBoxes = Array.isArray(startFrame?.boxes) ? startFrame.boxes : [];
      const startHit = toolCollisionHit(swing.hit, startBoxes, null, 0);
      if (startHit.hit) return startHit;
      previousBoxes = copyToolBoxes(startBoxes, previousBoxes);
      previousCount = startBoxes.length;
    }

    const stepCount = Math.max(1, Math.ceil(Math.max(0.001, endProgress - startProgress) / 0.10));
    for (let step = 1; step <= stepCount; step += 1) {
      const progress = startProgress + (endProgress - startProgress) * (step / stepCount);
      const frame = getToolCollisionFrame?.({ progress, swing });
      const boxes = Array.isArray(frame?.boxes) ? frame.boxes : [];
      if (!boxes.length) {
        previousBoxes = null;
        previousCount = 0;
        continue;
      }
      const hitResult = toolCollisionHit(swing.hit, boxes, previousBoxes, previousCount);
      if (hitResult.hit) return hitResult;
      previousBoxes = copyToolBoxes(boxes, previousBoxes);
      previousCount = boxes.length;
    }
    swing.previousToolBoxes = copyToolBoxes(previousBoxes ?? [], swing.previousToolBoxes);
    swing.previousToolBoxCount = previousCount;
    swing.previousToolProgress = endProgress;
    return { hit: false };
  }

The active swing does not accept its initial reach result as final contact. It subdivides animation progress, samples tool boxes, and carries each previous frame forward for swept testing.

1. Lines 1–13

   Establish and directly test the first collision frame.

2. Lines 15–29

   Subdivide elapsed animation progress and test every sampled frame.

3. Lines 30–34

   Retain the latest boxes and progress for the next update.

  function toolCollisionHit(hit, boxes, previousBoxes, previousBoxCount) {
    const targetBox = createBlockAabb(hit.worldX, hit.worldY, hit.worldZ, blockCollisionPadding, scratchTargetBox);
    for (let index = 0; index < boxes.length; index += 1) {
      const box = boxes[index];
      if (aabbIntersectsAabb(box, targetBox)) {
        return collisionResultFromBox(box, targetBox, 1);
      }
      const previous = previousBoxes?.[index];
      if (!previous || index >= previousBoxCount) continue;
      const result = sweptAabbIntersection(previous, box, targetBox, scratchCollisionResult);
      if (result.hit) return { hit: true, pointX: result.x, pointY: result.y, pointZ: result.z, time: result.time };
    }
    return { hit: false };
  }

A current tool box may overlap the block directly. Otherwise the controller sweeps from the previous box to the current box so a fast-moving tool cannot skip through the target between samples.

1. Lines 1–6

   Build the target block AABB and accept direct overlap.

2. Lines 7–11

   Sweep the corresponding previous tool box toward the current one.

3. Lines 12–14

   Reject contact when neither direct nor swept testing hits.

    const key = damageKey(hit);
    const now = performance.now();
    prunePartialDamage(now, key);
    const damageState = partialDamageState(key, now);
    const nextDamage = damageState.damage + 1;
    const requiredDamage = Math.max(1, swing.requiredDamage || requiredDamageForBlock(hit.blockId, def));
    damageState.damage = nextDamage;
    damageState.lastTouchedAt = now;
    damageState.toolDamageBySlot.set(
      swing.selectedToolIndex,
      (damageState.toolDamageBySlot.get(swing.selectedToolIndex) ?? 0) + 1,
    );
    selectedTool.durability = Math.max(0, Math.trunc(selectedTool.durability || 0) - 1);
    gameState.saveHotbarSlots();

After target and physical-contact checks, the controller records and displays tentative wear immediately. When the break becomes pending, the accumulated wear for a custodied forged slot is converted into chainToolDamage for atomic PlayerEquipment settlement.

1. Lines 1–8

   Update partial damage for the target.

2. Lines 9–12

   Attribute one local durability point to the selected hotbar slot.

3. Lines 13–14

   Decrement and persist browser hotbar durability.

  function rollbackPendingAt(index) {
    const pending = index >= 0 ? pendingTx.splice(index, 1)[0] : null;
    if (!pending) {
      onStatus("No pending delta to rollback.");
      return null;
    }
    const damageEntries = Array.isArray(pending.toolDamageBySlot) && pending.toolDamageBySlot.length
      ? pending.toolDamageBySlot
      : Number.isInteger(pending.toolSlotIndex) && Number(pending.toolDamage) > 0
        ? [{ slotIndex: pending.toolSlotIndex, amount: pending.toolDamage }]
        : [];
    for (const entry of damageEntries) {
      gameState.restoreToolDamage(entry.slotIndex, entry.amount);
    }
    gameState.playerProfile.rolledBackMines += 1;
    gameState.playerProfile.minedBlocks = Math.max(0, gameState.playerProfile.minedBlocks - Math.max(1, Math.trunc(pending.minedBlockCount || 1)));
    gameState.savePlayerProfile();
    onRollback(pending);
    onChanged();
    return pending;
  }

A pending mine retains a per-slot damage ledger. Rollback restores every recorded local slot before updating browser statistics. Production calls this when mining submission is disabled, unavailable, rejected, or throws; it is not an on-chain durability refund.

1. Lines 1–6

   Remove the matching pending action or stop if it was already resolved.

2. Lines 7–13

   Recover the per-slot damage ledger, including the older single-slot fallback.

3. Lines 14–21

   Restore local tool damage and update rollback state.

    const mineOptions = mineShouldSavePlayerPosition(block)
      ? { ...backpackOptions, durabilityDamage: pending.chainToolDamage, playerPosition: playerPositionProof(getPlayerPosition) }
      : { ...backpackOptions, durabilityDamage: pending.chainToolDamage };

The adapter carries the normalized equipment-slot damage ledger into every supported production mine helper through options.durabilityDamage. This is the authoritative durability input; the separate legacy local toolSlot argument is not used for chain selection.

1. Lines 1–3

   Attach chainToolDamage whether or not this mine also carries a player-position proof.

function addEquipmentDurabilityInstructions(transaction, { authority, owner, damage = [] } = {}) {
  for (const entry of normalizeEquipmentDurabilityDamage(damage)) {
    transaction.add(createConsumePlayerEquipmentDurabilityInstruction({
      authority,
      owner,
      equipmentSlot: entry.equipmentSlot,
      amount: entry.amount,
    }));
  }
  return transaction;
}

function normalizeEquipmentDurabilityDamage(damage = []) {
  const totals = new Map();
  for (const entry of Array.isArray(damage) ? damage : []) {
    const equipmentSlot = Math.trunc(Number(entry?.equipmentSlot));
    const amount = Math.trunc(Number(entry?.amount));
    if (!Number.isInteger(equipmentSlot) || equipmentSlot < 0 || equipmentSlot >= playerEquipmentSlotCount) continue;
    if (!Number.isInteger(amount) || amount < 1) continue;
    totals.set(equipmentSlot, Math.min(0xffffffff, (totals.get(equipmentSlot) ?? 0) + amount));
  }
  return Array.from(totals, ([equipmentSlot, amount]) => ({ equipmentSlot, amount }));
}

function createConsumePlayerEquipmentDurabilityInstruction({ authority, owner, equipmentSlot, amount }) {
  const [playerProfile] = derivePlayerProfilePda(owner);
  const [playerSession] = derivePlayerSessionPda(owner, authority);
  const [playerEquipment] = derivePlayerEquipmentPda(owner);
  const data = Buffer.alloc(6);
  data.writeUInt8(15, 0);
  data.writeUInt8(equipmentSlot, 1);
  data.writeUInt32LE(amount, 2);
  return new TransactionInstruction({
    programId: playerProgramId,
    keys: [
      { pubkey: authority, isSigner: true, isWritable: true },
      { pubkey: owner, isSigner: false, isWritable: false },
      { pubkey: playerProfile, isSigner: false, isWritable: false },
      { pubkey: playerSession, isSigner: false, isWritable: false },
      { pubkey: playerEquipment, isSigner: false, isWritable: true },
      { pubkey: deriveGlobalConfigPda(), isSigner: false, isWritable: false },
    ],
    data,
  });
}

Damage is grouped by PlayerEquipment slot, invalid or zero entries are discarded, and each accepted total becomes a six-account Player instruction whose tag byte is 15 and whose amount is little-endian u32.

1. Lines 1–10

   Append one durability instruction for each normalized equipment-slot total.

2. Lines 12–22

   Reject invalid entries, group duplicate slots, and cap the accumulated u32 amount.

3. Lines 24–44

   Derive Profile, Session, and PlayerEquipment, encode tag 15, and mark only PlayerEquipment writable.

    pub fn consume_forged_durability(
        dst: &mut [u8],
        slot: u8,
        amount: u32,
        updated_slot: u64,
    ) -> ProgramResult {
        if amount == 0 {
            return Err(NicechunkPlayerError::InvalidDurabilityAmount.into());
        }
        let offset = Self::slot_offset(slot)?;
        Self::validate_layout(dst)?;
        let record_offset = offset + Self::RECORD_BACKPACK_SLOT_OFFSET;
        if dst[offset + Self::RECORD_STATE_OFFSET] != 1
            || dst[offset + Self::RECORD_FLAGS_OFFSET] & PLAYER_EQUIPMENT_FLAG_CUSTODY == 0
            || dst[record_offset] != BACKPACK_SLOT_KIND_ITEM
            || dst[record_offset + 1] != BACKPACK_ITEM_CATEGORY_FORGED
            || read_u16(dst, record_offset + 18) != BACKPACK_FORGED_ITEM_CODE
        {
            return Err(NicechunkPlayerError::EquipmentNotCustodied.into());
        }
        let durability_offset = record_offset + BACKPACK_SLOT_DURABILITY_CURRENT_OFFSET;
        let max_offset = record_offset + BACKPACK_SLOT_DURABILITY_MAX_OFFSET;
        let current = read_u32(dst, durability_offset);
        let maximum = read_u32(dst, max_offset);
        if current == 0 || maximum == 0 || current > maximum || amount > current {
            return Err(NicechunkPlayerError::EquipmentBroken.into());
        }
        dst[durability_offset..durability_offset + 4]
            .copy_from_slice(&(current - amount).to_le_bytes());
        dst[Self::UPDATED_SLOT_OFFSET..Self::UPDATED_SLOT_OFFSET + 8]
            .copy_from_slice(&updated_slot.to_le_bytes());
        Ok(())
    }

The on-chain writer requires active custody, forged category, item code 8, valid current and maximum durability, and enough remaining durability. It changes the record and PlayerEquipment updated slot, but it does not receive or rewrite PlayerProfile, which creates the documented post-wear identity mismatch.

1. Lines 1–11

   Reject zero damage, invalid slot, or an invalid PlayerEquipment layout.

2. Lines 12–20

   Require active custody and the exact forged item category and code.

3. Lines 21–33

   Validate bounds, subtract the amount, and update PlayerEquipment without touching Profile.