A unique name, an invite entry, and a spawn hint are three different results

export function parseInviteParams(input = typeof window !== "undefined" ? window.location.search : "") {
  const params = input instanceof URLSearchParams ? input : new URLSearchParams(String(input || ""));
  const referrer = firstParam(params, [inviteRefParam, "invite", "inviter"]);
  const guardianId = firstParam(params, [inviteGuardianParam, "guardianId"]) || "genesis";
  const region = parseGuardianRegionParams(params);
  return {
    referrer: normalizeParam(referrer),
    guardianId: normalizeParam(guardianId) || "genesis",
    region,
    hasInvite: Boolean(normalizeParam(referrer) || normalizeParam(guardianId) || region),
  };
}

guardianId is already genesis when the URL contains no Guardian field, so the Boolean expression is true on an empty query. Nothing in this function verifies an inviter signature or capability.

1. 1-4

   Normalize URL input, read public referrer aliases, and replace a missing Guardian with genesis.

2. 5-11

   Return normalized fields; the already-nonempty default makes hasInvite true even without supplied invite text.

function parseGuardianRegionParams(params) {
  const explicit = firstParam(params, [inviteGuardianRegionParam, "region"]);
  const parsedExplicit = parseRegionPair(explicit);
  if (parsedExplicit) return parsedExplicit;
  const guardian = firstParam(params, [inviteGuardianParam, "guardianId"]);
  const parsedGuardian = parseRegionPair(guardian);
  if (parsedGuardian) return parsedGuardian;
  const x = Number(firstParam(params, ["guardianX", "regionX"]));
  const y = Number(firstParam(params, ["guardianY", "regionY"]));
  if (Number.isInteger(x) && Number.isInteger(y)) return { regionX: x, regionY: y };
  return null;
}

firstParam returns an empty string for each missing coordinate. JavaScript Number converts that empty string to zero, and zero is an integer, so a plain visit currently returns Region 0:0.

1. 1-7

   Prefer explicit pair text, then a coordinate-looking Guardian value.

2. 8-11

   Convert separate coordinate fields; the missing-string conversion is the empty-query defect.

export function guardianSpawnStateForRegion(region, { surfaceHeight, yaw = Math.PI * 0.25, cameraPitch = -0.42 } = {}) {
  const normalized = normalizeGuardianRegion(region) ?? genesisGuardianRegion();
  const centerChunkX = normalized.regionX * GUARDIAN_REGION_SIZE + GUARDIAN_REGION_SIZE / 2;
  const centerChunkZ = normalized.regionY * GUARDIAN_REGION_SIZE + GUARDIAN_REGION_SIZE / 2;
  const x = centerChunkX * chunkSize;
  const z = centerChunkZ * chunkSize;
  const ground = typeof surfaceHeight === "function" ? surfaceHeight(x, z) : 0;
  const y = Number.isFinite(ground) ? ground + 1.01 : 1.01;
  return {
    position: { x, y, z },
    yaw,
    cameraPitch,
    guardianRegion: normalized,
  };
}

The helper returns an ordinary JavaScript object from public Region input and local terrain math. It does not read an InviteIndex, sign a transaction, or update PlayerProfile position.

1. 1-6

   Normalize or fall back to Genesis, choose the Region center in Chunks, then convert to block coordinates.

2. 7-14

   Resolve local ground height and return position plus camera hints.

async function canonicalPlayerNameHash(playerName) {
  const { normalized } = encodePlayerName(playerName);
  const canonical = normalized.replace(/[A-Z]/g, (char) => char.toLowerCase());
  const bytes = Buffer.from(canonical, "utf8");
  const subtle = globalThis.crypto?.subtle;
  if (!subtle) throw new Error("WebCrypto SHA-256 is unavailable.");
  const digest = await subtle.digest("SHA-256", bytes);
  return Buffer.from(new Uint8Array(digest));
}

The browser and program use the same narrow case rule. SHA-256 produces the 32-byte seed, but hashing does not reserve an account or reveal who owns it.

1. 1-4

   Validate and trim the name, lower only ASCII uppercase letters, and encode UTF-8 bytes.

2. 5-8

   Require WebCrypto, calculate SHA-256, and return the digest bytes used for PDA derivation.

export async function deriveUsernameIndexPdaForName(playerName) {
  const nameHash = await canonicalPlayerNameHash(playerName);
  return PublicKey.findProgramAddressSync(
    [Buffer.from(usernameIndexSeed), nameHash],
    playerProgramId,
  );
}

Every caller derives the same Player Program address from the fixed seed and canonical name hash. The owner relationship must therefore be validated from account contents.

1. 1-2

   Calculate the canonical name hash.

2. 3-6

   Derive under the Player Program with only the fixed name seed and hash.

    pub fn validate_owner_or_available(
        data: &[u8],
        owner: &Pubkey,
        player_profile: &Pubkey,
        global_config: &Pubkey,
        name_hash: &[u8; 32],
    ) -> ProgramResult {
        if data.len() != Self::LEN || data[0..8] != USERNAME_INDEX_MAGIC {
            return Err(NicechunkPlayerError::InvalidUsernameIndexData.into());
        }
        if read_u16(data, 8) != USERNAME_INDEX_VERSION {
            return Err(NicechunkPlayerError::InvalidUsernameIndexData.into());
        }
        if &data[Self::NAME_HASH_OFFSET..Self::NAME_HASH_OFFSET + 32] != name_hash {
            return Err(NicechunkPlayerError::InvalidUsernameIndexData.into());
        }
        if &data[Self::GLOBAL_CONFIG_OFFSET..Self::GLOBAL_CONFIG_OFFSET + 32]
            != global_config.as_ref()
        {
            return Err(NicechunkPlayerError::InvalidUsernameIndexData.into());
        }
        if &data[Self::OWNER_OFFSET..Self::OWNER_OFFSET + 32] != owner.as_ref() {
            return Err(NicechunkPlayerError::UsernameAlreadyTaken.into());
        }
        if &data[Self::PLAYER_PROFILE_OFFSET..Self::PLAYER_PROFILE_OFFSET + 32]
            != player_profile.as_ref()
        {
            return Err(NicechunkPlayerError::UsernameAlreadyTaken.into());
        }
        Ok(())
    }

A program-owned index is accepted only when its format, hash, configuration, owner, and Profile relationship all match. The function validates; it does not rewrite spelling, release a prior index, or inspect invitations.

1. 1-16

   Check the fixed account identity, version, canonical hash, and GlobalConfig.

2. 17-29

   Treat a different stored owner or PlayerProfile as taken; accept only the matching relationship.

    let clock = Clock::get()?;
    let mut data = player_profile.try_borrow_mut_data()?;
    PlayerProfile::write_name(&mut data, player_name, clock.slot)?;
    drop(data);
    if let (Some(system_program_account), Some(username_index)) =
        (system_program_account, username_index)
    {
        ensure_username_index_current(
            authority,
            username_index,
            system_program_account,
            program_id,
            authority.key,
            player_profile.key,
            global_config.key,
            player_name,
            &clock,
        )?;
    }
    Ok(())

The instruction writes the current Profile name and then ensures the supplied new-name index. Solana rolls both back if the later check fails. On success, this path never receives or closes the earlier UsernameIndex, so its lamports and ownership remain.

1. 1-4

   Write the proposed current name and update slot in the borrowed Profile data.

2. 5-18

   For a nonempty name, create or validate only the supplied current-name index.

3. 19

   Return without any earlier-name account or close operation in this instruction.

pub const INVITE_INDEX_MAGIC: [u8; 8] = *b"NCKINV01";
pub const INVITE_INDEX_VERSION: u16 = 1;
pub const INVITE_INDEX_SEED: &[u8] = b"invite-index-v1";
pub const INVITE_INDEX_CAPACITY: usize = 64;
pub const INVITE_INDEX_HEADER_LEN: usize = 128;
pub const INVITE_INDEX_RECORD_LEN: usize = 40;

The constants define the identity and exact storage math. A visual cabinet is only a metaphor; the implemented page is 128 header bytes plus 64 fixed records.

1. 1-3

   Name the on-chain format, version, and PDA seed.

2. 4-6

   Fix capacity, header length, and record length used by pack, validate, and append.

    pub fn append(dst: &mut [u8], invited: &Pubkey, updated_slot: u64) -> ProgramResult {
        if dst.len() != Self::LEN || dst[0..8] != INVITE_INDEX_MAGIC {
            return Err(NicechunkPlayerError::InvalidInviteIndexData.into());
        }
        let count = read_u16(dst, Self::COUNT_OFFSET) as usize;
        if count >= INVITE_INDEX_CAPACITY {
            return Err(NicechunkPlayerError::InviteIndexPageFull.into());
        }
        let offset = Self::RECORDS_OFFSET + count * INVITE_INDEX_RECORD_LEN;
        dst[offset..offset + 32].copy_from_slice(invited.as_ref());
        dst[offset + 32..offset + 40].copy_from_slice(&updated_slot.to_le_bytes());
        dst[Self::COUNT_OFFSET..Self::COUNT_OFFSET + 2]
            .copy_from_slice(&((count + 1) as u16).to_le_bytes());
        dst[Self::UPDATED_SLOT_OFFSET..Self::UPDATED_SLOT_OFFSET + 8]
            .copy_from_slice(&updated_slot.to_le_bytes());
        Ok(())
    }

After format and capacity checks, append writes directly at the count-selected offset. No line scans the current or other pages for the invited public key.

1. 1-8

   Validate page identity, read count, and stop only when capacity is exhausted.

2. 9-15

   Write the 32-byte wallet and 8-byte slot, increment count, and update the page slot.

3. 16-17

   Return success without a duplicate-wallet branch.

    if !payer.is_signer || !payer.is_writable {
        return Err(NicechunkPlayerError::InvalidPayer.into());
    }
    if !invite_index.is_writable {
        return Err(NicechunkPlayerError::InvalidWritableAccount.into());
    }
    if page_index == 0 && payer.key != inviter.key {
        return Err(NicechunkPlayerError::InviteFirstPageRequiresInviter.into());
    }
    require_key_eq(
        system_program_account.key,
        &system_program::ID,
        NicechunkPlayerError::InvalidSystemProgram,
    )?;
    require_key_eq(
        global_config.owner,
        &NICECHUNK_CORE_PROGRAM_ID,
        NicechunkPlayerError::InvalidGlobalConfigOwner,
    )?;

    let (expected_invite_index, bump) = invite_index_pda(program_id, inviter.key, page_index);
    require_key_eq(
        invite_index.key,
        &expected_invite_index,
        NicechunkPlayerError::InvalidInviteIndexPda,
    )?;
    if invite_index.owner == program_id {
        let data = invite_index.try_borrow_data()?;
        return InviteIndex::validate(&data, inviter.key, global_config.key, page_index);
    }

The payer signs, and page zero alone binds payer to inviter. For a correct higher-page PDA, this excerpt has no previous-page check. An already-created page is simply validated and returned.

1. 1-9

   Require a signing payer and writable page; require inviter self-funding only for page zero.

2. 10-26

   Validate system, config owner, and the inviter-plus-page PDA.

3. 27-30

   If the page already exists under the Player Program, validate it without any continuity test.

    if !invited.is_signer || !invited.is_writable {
        return Err(NicechunkPlayerError::InvalidPayer.into());
    }
    if invited.key == inviter.key {
        return Err(NicechunkPlayerError::InvalidInviteSelf.into());
    }
    if !invite_index.is_writable {
        return Err(NicechunkPlayerError::InvalidWritableAccount.into());
    }

The wallet being recorded must sign and can pay for rollover. The inviter is compared as a public key for self-invite but is not required to be a signer in this account check.

1. 1-3

   Require the invited account to sign and be writable.

2. 4-9

   Reject self-invite and require the target page to be writable.

    if invite_index.owner != program_id {
        if page_index == 0 {
            return Err(NicechunkPlayerError::InviteFirstPageRequiresInviter.into());
        }
        if accounts.len() != 6 {
            return Err(NicechunkPlayerError::InvitePreviousPageRequired.into());
        }
        let previous_invite_index = next_account_info(account_info_iter)?;
        let previous_page_index = page_index.saturating_sub(1);
        let (expected_previous, _) = invite_index_pda(program_id, inviter.key, previous_page_index);
        require_key_eq(
            previous_invite_index.key,
            &expected_previous,
            NicechunkPlayerError::InvalidInviteIndexPda,
        )?;
        require_key_eq(
            previous_invite_index.owner,
            program_id,
            NicechunkPlayerError::InvalidInviteIndexData,
        )?;
        let previous_data = previous_invite_index.try_borrow_data()?;
        if !InviteIndex::is_full(
            &previous_data,
            inviter.key,
            global_config.key,
            previous_page_index,
        )
        .map_err(|_| NicechunkPlayerError::InvalidInviteIndexData)?
        {
            return Err(NicechunkPlayerError::InvitePreviousPageNotFull.into());
        }
        drop(previous_data);
        if invite_index.owner != &system_program::ID || invite_index.data_len() != 0 {
            return Err(NicechunkPlayerError::InvalidSystemAccount.into());
        }
        create_or_allocate_invite_index_pda(
            invited,
            invite_index,
            system_program_account,
            program_id,
            inviter.key,
            page_index,
            bump,
        )?;
        let clock = Clock::get()?;
        {
            let mut data = invite_index.try_borrow_mut_data()?;
            InviteIndex::pack_empty(
                &mut data,
                &InviteIndexInitArgs {
                    bump,
                    inviter: inviter.key,
                    global_config: global_config.key,
                    page_index,
                    created_slot: clock.slot,
                },
            )?;
        }
    }

    let clock = Clock::get()?;
    let mut data = invite_index.try_borrow_mut_data()?;
    InviteIndex::validate(&data, inviter.key, global_config.key, page_index)?;
    InviteIndex::append(&mut data, invited.key, clock.slot)

Normal rollover checks and funds a missing higher page only after the prior page is full. If tag 10 already made the target Player-owned, the outer if is false and execution jumps to validate and append, bypassing continuity.

1. 1-31

   For a missing page, forbid page zero, demand the previous page, validate it, and require it to be full.

2. 32-58

   Require an untouched System account, let the invited wallet fund it, and pack the new page.

3. 61-64

   For both new and already-existing pages, validate the target and append; an existing high page reached this point without the prior-full branch.

export async function fetchInviteIndexPages(inviterAddress, { maxPages = 16 } = {}) {
  if (!inviterAddress) return { inviter: "", pages: [], entries: [], capacity: inviteIndexCapacity };
  const inviter = typeof inviterAddress === "string" ? new PublicKey(inviterAddress) : inviterAddress;
  const pageCount = Math.max(1, Math.min(64, Math.floor(Number(maxPages) || 16)));
  const pageKeys = Array.from({ length: pageCount }, (_value, index) => deriveInviteIndexPda(inviter, index)[0]);
  const accounts = await getNicechunkConnection().getMultipleAccountsInfo(pageKeys, "confirmed");
  const pages = [];
  const entries = [];
  let sawMissingAfterData = false;
  for (let index = 0; index < pageKeys.length; index += 1) {
    const account = accounts[index];
    if (!account?.data?.length || !account.owner.equals(playerProgramId)) {
      if (pages.length) sawMissingAfterData = true;
      if (!pages.length || sawMissingAfterData) break;
      continue;
    }
    const page = decodeInviteIndex(account.data, {
      publicKey: pageKeys[index],
      inviter,
      pageIndex: index,
      programId: account.owner,
    });
    if (!page) break;
    pages.push(page);
    for (const entry of page.entries) entries.push(entry);
    if (page.count < inviteIndexCapacity) break;
  }

The default request derives only indexes 0 through 15 and stops at a missing, invalid, or not-full page. A valid page beyond that stopping point can exist without appearing in the returned ledger.

1. 1-6

   Clamp the requested count and fetch one predictable prefix at confirmed.

2. 7-16

   Walk in order and stop as soon as a missing boundary is observed.

3. 17-26

   Decode, accumulate, and stop again when the current page is not full.

  const current = await fetchInviteIndexPages(inviter, { maxPages: 16 });
  if (!current.pages.length) {
    return { submitted: false, reason: "invite-first-page-required", inviter: inviter.toBase58() };
  }
  const invitedWallet = provider.publicKey.toBase58();
  if (current.entries.some((entry) => String(entry.invitedWallet || entry.wallet || "") === invitedWallet)) {
    return {
      submitted: false,
      reason: "already-registered",
      invited: invitedWallet,
      inviter: inviter.toBase58(),
      capacity: inviteIndexCapacity,
    };
  }
  let targetPage = current.pages.find((page) => page.count < inviteIndexCapacity);
  if (!targetPage) {
    const nextIndex = current.pages.length;
    const [publicKey] = deriveInviteIndexPda(inviter, nextIndex);
    targetPage = { pageIndex: nextIndex, publicKey: publicKey.toBase58(), count: 0 };
  }

The browser checks only rows returned by the bounded read, then separately submits later. This avoids common repeats but cannot provide atomic or protocol-wide uniqueness, and nextIndex is based only on the number of visible pages.

1. 1-4

   Read at most sixteen pages and require a visible first page.

2. 5-14

   Return early when the invited wallet appears in the fetched prefix.

3. 15-20

   Use a visible partial page or derive the next index from visible page count.

  const entries = [];
  for (let index = 0; index < count; index += 1) {
    const offset = inviteIndexHeaderLength + index * inviteIndexRecordLength;
    const invited = new PublicKey(data.subarray(offset, offset + 32)).toBase58();
    entries.push({
      invitedWallet: invited,
      wallet: invited,
      pageIndex: storedPageIndex,
      index,
      createdSlot: data.readBigUInt64LE(offset + 32).toString(),
      status: "registered",
    });
  }

The bytes provide the wallet and slot. status is a JavaScript label attached during decoding, not a field that the program packed or a reward state that the account can enforce.

1. 1-4

   For each stored count, calculate the fixed record offset and read the public key.

2. 5-12

   Build a display object and add a registered label that was not stored in the row bytes.

export function storePendingInviteSpawn(walletAddress, payload) {
  const wallet = normalizeParam(walletAddress);
  if (!wallet || !payload) return;
  try {
    localStorage.setItem(inviteSpawnStorageKey(wallet), JSON.stringify({
      ...payload,
      storedAt: Date.now(),
    }));
  } catch {
    // Spawn still works from the chain PDA if local storage is unavailable.
  }
}

export function consumePendingInviteSpawn(walletAddress, { surfaceHeight } = {}) {
  const wallet = normalizeParam(walletAddress);
  if (!wallet) return null;
  const key = inviteSpawnStorageKey(wallet);
  try {
    const raw = localStorage.getItem(key);
    if (!raw) return null;
    localStorage.removeItem(key);
    const parsed = JSON.parse(raw);
    const state = parsed?.position
      ? {
          position: parsed.position,
          yaw: Number.isFinite(Number(parsed.yaw)) ? Number(parsed.yaw) : Math.PI * 0.25,
          cameraPitch: Number.isFinite(Number(parsed.cameraPitch)) ? Number(parsed.cameraPitch) : -0.42,
          guardianRegion: normalizeGuardianRegion(parsed.guardianRegion),
        }
      : guardianSpawnStateForRegion(parsed?.guardianRegion, { surfaceHeight });
    return state;
  } catch {
    localStorage.removeItem(key);
    return null;
  }
}

Saving catches failures and returns no persistence signal. A caller that uses the consumer removes before parsing and performs no storedAt age check; cleanup can itself throw if storage removal fails inside the catch.

1. 1-12

   Attempt a wallet-scoped JSON write with storedAt, then silently continue on failure.

2. 14-31

   Read once, remove immediately, parse a stored position or recalculate from Region, and return it.

3. 32-35

   Try removal again on failure; the second removal is not protected by another nested catch.

const queryPose = parsePoseText(params.get("pose") || "", { minViewDistance: 2, maxViewDistance: PLAYABLE_MAX_VIEW_DISTANCE });
const PLAYABLE_WORLD_SEED = "nicechunk-mainnet-001";
const PLAYABLE_TEXTURE_TILE_SIZE = 32;
const viewDistance = clampInt(Number(params.get("view")) || queryPose?.viewDistance || DEFAULT_PLAY_VIEW_DISTANCE, 2, PLAYABLE_MAX_VIEW_DISTANCE);
const meshBudgetMs = clampInt(Number(params.get("budget")) || DEFAULT_MESH_BUDGET_MS, 2, 14);
const POSITION_STORAGE_KEY = "nicechunk.chunkjs.playable.position.v2";
const POSITION_SAVE_INTERVAL_MS = 650;
const FRAME_MINIMAP_UPDATE_MS = 250;
const FRAME_ACTION_HIT_UPDATE_MS = 90;
const forceGuardianSpawn = params.get("guardianSpawn") === "1" || params.get("spawn") === "guardian";
const defaultGuardianSpawn = {
  worldX: (GENESIS_GUARDIAN_REGION_SIZE_CHUNKS / 2) * 16,
  worldY: undefined,
  worldZ: (GENESIS_GUARDIAN_REGION_SIZE_CHUNKS / 2) * 16,
  localOffsetX: 0.5,
  localOffsetY: 0,
  localOffsetZ: 0.5,
  controlYaw: Math.PI * 0.25,
  avatarYaw: Math.PI * 0.25,
  cameraPitch: -0.42,
};
const savedSpawn = (queryPose || hasSpawnParam(params) || forceGuardianSpawn) ? null : loadSavedPlayerPosition({ storageKey: POSITION_STORAGE_KEY, seed: PLAYABLE_WORLD_SEED });
const spawnState = queryPose ?? savedSpawn ?? defaultGuardianSpawn;
const spawnX = spawnCoord(params, "x", spawnState?.worldX ?? 0);
const spawnYOverride = spawnCoordOrNull(params, "y", spawnState?.worldY);
const spawnZ = spawnCoord(params, "z", spawnState?.worldZ ?? 0);
const spawnFlightEnabled = Boolean(spawnState?.flightEnabled || params.get("fly") === "1" || params.get("flight") === "1");

The active startup expression never references the wallet-scoped pending invite key or its consumer. Genesis X and Z resolve to 50 times 16, or 800, when no higher-priority state wins.

1. 1-10

   Parse optional pose and runtime controls, then define a separate Play position key and forced-default flag.

2. 11-21

   Construct the fixed Region-zero center and camera defaults.

3. 22-27

   Skip saved state for explicit queries or forced default, choose query then saved then Genesis, and finally apply axis and flight query values.