Session Funding and Expiry: A Target Is Not a Balance, and Browser Time Is Not Chain Time

    elements.sessionFundingForm?.addEventListener("submit", (event) => {
      event.preventDefault();
      const sol = Math.max(MINIMUM_SESSION_SOL, Number(elements.sessionFundingAmount?.value) || MINIMUM_SESSION_SOL);
      state.sessionLamports = Math.trunc(sol * LAMPORTS_PER_SOL);
      saveSessionLamports(state.walletAddress, state.sessionLamports);
      saveSessionAcknowledged(state.walletAddress);
      closeSessionPanel(true);
      render();
      appendChainEvent(`Session funding target set to ${formatSol(state.sessionLamports)} SOL for ${ownerLabel()}.`);
      setStatus(`Session funding target set to ${formatSol(state.sessionLamports)} SOL. It is a top-up target, not a spending cap or authorization limit.`);
    });

Submitting this form clamps and stores a browser number, updates presentation, and explicitly calls it a target. This continuous range contains no transfer or RPC balance read.

1. Lines 1–4

   Turn the selected SOL policy into an integer lamport target no lower than 0.1 SOL.

2. Lines 5–8

   Save owner-scoped browser preferences and redraw the panel without constructing a transaction.

3. Lines 9–11

   Tell the player that the value is a top-up target rather than a cap or authorization limit.

    const sessionText = state.sessionLamports > 0 ? `Session: ${formatSol(state.sessionLamports)} SOL` : "Session: not funded";
    const rpcText = state.rpcMode === "custom"
      ? ui("main.profile.rpcCustom", "Custom Devnet RPC")
      : state.rpcMode === "helius"
        ? ui("main.profile.rpcHelius", "Helius RPC")
        : ui("main.profile.rpcPublic", "Public RPC");
    if (elements.accountName) elements.accountName.textContent = identity.name || profile.name || "Local Miner";
    if (elements.accountLevel) elements.accountLevel.textContent = `Lv. ${levelFromProfile(profile)}`;
    if (elements.accountTitle) elements.accountTitle.textContent = identity.title || chainModeLabel(state.chainMode);
    renderWalletBalance();
    if (elements.accountSessionBalance) elements.accountSessionBalance.textContent = sessionText;

The visible Session text is formatted directly from state.sessionLamports, while the owner wallet balance is rendered by a separate function. This is literal evidence that “Session: X SOL” is the local target presentation rather than either RPC balance.

1. Line 1

   Build the visible Session label directly from the in-memory sessionLamports target or show not funded when it is zero.

2. Lines 2–7

   Select Public, Helius, or Custom Devnet RPC presentation, then prepare name, level, and title without changing the Session target value.

3. Lines 11–12

   Render the owner wallet balance separately, then place the prebuilt target-derived Session text in its own HUD element.

      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "nicechunk-wallet-balance",
        method: "getBalance",
        params: [walletAddress, { commitment: "confirmed" }],
      }),
      signal: controller?.signal,
      cache: "no-store",

The Play balance request is tied to walletAddress and confirmed commitment. In plugin mode that connected owner address can differ from the stored session authority.

1. Lines 1–5

   Build one JSON-RPC getBalance request for the connected wallet address at confirmed commitment.

2. Lines 6–8

   Attach the request-abort signal and disable HTTP response caching; the separate in-memory UI cache still exists.

    let rent = Rent::get()?;
    let lamports = rent.minimum_balance(PlayerSession::LEN);

    if player_session.lamports() == 0 {
        let create = system_instruction::create_account(
            payer.key,
            player_session.key,
            lamports,
            PlayerSession::LEN as u64,
            program_id,
        );

The Player Program calculates rent for the fixed Session data length and creates the PDA with that lamport allocation. This is not a transfer to sessionAuthority.

1. Lines 1–2

   Ask the chain Rent sysvar for the minimum balance of the PlayerSession allocation.

2. Lines 4–11

   When the PDA has no lamports, build a payer-funded account creation for the program-owned data account.

export function setConfiguredGameplaySessionFundingSol(value, owner = null) {
  const parsed = Number(value);
  const lamports = Number.isFinite(parsed)
    ? Math.max(minimumSessionFundingLamports, Math.ceil(parsed * lamportsPerSol))
    : minimumSessionFundingLamports;
  if (hasLocalStorage()) localStorage.setItem(sessionFundingStorageKey(owner), String(lamports));
  return lamports / lamportsPerSol;
}

The setter normalizes a browser preference and stores it when localStorage exists. It neither reads nor changes the authority address balance.

1. Lines 1–5

   Convert finite SOL input to rounded-up lamports and clamp it to the 0.1 SOL minimum.

2. Lines 6–7

   Save the target under the selected suffix and return the normalized SOL display value.

function getConfiguredGameplaySessionFundingLamports(owner = null) {
  if (!hasLocalStorage()) return minimumSessionFundingLamports;
  const ownerValue = localStorage.getItem(sessionFundingStorageKey(owner));
  const defaultValue = localStorage.getItem(sessionFundingStorageKey(null));
  const parsed = Number(ownerValue ?? defaultValue);
  return Number.isFinite(parsed) && parsed >= minimumSessionFundingLamports
    ? Math.floor(parsed)
    : minimumSessionFundingLamports;
}

The nullish operator selects the owner value when present and otherwise the default; the final branch rejects invalid or below-minimum values.

1. Lines 1–4

   Use the minimum without storage, otherwise read owner-specific and default browser keys.

2. Lines 5–8

   Select one value and accept it only when finite and at least the minimum.

async function fundGameplaySessionIfNeeded(provider, sessionAuthority, sessionBalance, conn) {
  if (sessionBalance >= minimumSessionFundingLamports) return;
  const targetLamports = getConfiguredGameplaySessionFundingLamports(provider.publicKey);
  if (sessionBalance >= targetLamports) return;
  const lamports = targetLamports - sessionBalance;
  if (lamports <= 0) return;
  const tx = new Transaction();
  tx.add(SystemProgram.transfer({
    fromPubkey: provider.publicKey,
    toPubkey: sessionAuthority,
    lamports,
  }));
  await signAndSendWalletTransaction(provider, tx, conn);
}

Operation order is decisive: a balance at or above 0.1 SOL returns before a higher target is considered. A lower balance may request the positive difference from owner to authority.

1. Lines 1–4

   Exit at the minimum threshold; only a lower balance loads and compares the configured target.

2. Lines 5–6

   Calculate and validate a strictly positive difference.

3. Lines 7–13

   Build the owner-to-authority System transfer and ask the wallet helper to submit it.

function createLocalGameWalletStatus(owner, balanceLamports = null, expiresAt = null) {
  const ownerKey = owner?.toBase58?.() ?? String(owner ?? "");
  const normalizedBalance = Number.isFinite(balanceLamports) ? Math.floor(balanceLamports) : null;
  return {
    walletAvailable: true,
    owner: ownerKey,
    acknowledged: true,
    configuredFundingLamports: 0,
    minimumFundingLamports: 0,
    balanceLamports: normalizedBalance,
    balanceSol: normalizedBalance === null ? null : normalizedBalance / lamportsPerSol,
    publicKey: ownerKey,
    sessionAuthority: ownerKey,
    expiresAt,
    usesGameplaySession: false,
    walletMode: "localGameWallet",
  };
}

The status object uses ownerKey for owner, publicKey, and sessionAuthority, while reporting zero for the separate-session funding policy fields. Zero target does not mean zero wallet balance.

1. Lines 1–3

   Normalize the one Local Game Wallet address and an optional fresh balance.

2. Lines 4–10

   Report no separate funding target while retaining the actual one-address balance.

3. Lines 11–17

   Put the same key in public and authority roles and label the wallet mode explicitly.

  tx.add(createOrRefreshPlayerSessionInstruction({
    owner,
    sessionAuthority: owner,
    playerProfile,
    playerSession,
    expiresAt,
  }));

  await signAndSendKeypairTransaction(keypair, tx, conn);

The same public key occupies owner and sessionAuthority, and the persistent Local Game Wallet Keypair signs the transaction directly.

1. Lines 1–7

   Construct Session setup with owner repeated in the authority role.

2. Line 9

   Sign and submit using that same long-lived browser Keypair.

function storeLocalGameWalletKeypair(keypair, source = "created") {
  const address = keypair.publicKey.toBase58();
  const secretKey = bs58.encode(keypair.secretKey);
  const createdAt = String(Date.now());
  if (!hasLocalStorage()) throw new Error("Browser local storage is unavailable.");
  localStorage.setItem(localGameWalletKeys.address, address);
  localStorage.setItem(localGameWalletKeys.secretKey, secretKey);

Base58 changes representation but does not encrypt the full long-lived key. Its funding exposure therefore follows the one owner-and-authority address.

1. Lines 1–4

   Derive the address, reversible Base58 secret text, and browser creation time.

2. Lines 5–7

   Require localStorage and save both public address and private signing bytes.

const sessionDurationSeconds = 8 * 60 * 60;
const sessionRefreshSkewSeconds = 15 * 60;
const lamportsPerSol = 1_000_000_000;
const minimumSessionFundingLamports = 100_000_000;
const sessionMinimumMiningLamports = 8_000_000;
const sessionAllowedActions = (1 << 1) | (1 << 2);
const sessionMaxActions = 10_000;
const miningComputeUnitLimit = 1_400_000;
const fallbackTransactionFeeLamports = 5_000;
const transactionConfirmationPollMs = 500;
const transactionBlockHeightPollMs = 1_000;
const transactionConfirmationTimeoutMs = 60_000;
const treeFellMaxChunkCount = 4;
const treeFellLeafRadius = 2;
const supportCollapseMaxOnChainBlocks = 48;
const bulkMiningModeDebug = 1;
const chunkDeltaCacheTtlMs = 60_000;
const gameplaySessionStatusCacheTtlMs = 60_000;
const gameplaySessionReadyCacheTtlMs = 5 * 60_000;

The relevant declarations set eight-hour duration, fifteen-minute skew, sixty-second status cache, and five-minute ready cache. The nearby sixty-second confirmation fallback is a different policy and must not be confused with Session lifetime.

1. Lines 1–4

   Declare requested duration, refresh skew, SOL conversion, and funding minimum.

2. Lines 5–16

   Declare unrelated action, fee, polling, and gameplay constants that share the same module.

3. Lines 17–19

   Declare independent sixty-second Session status and five-minute readiness cache lifetimes.

const LAMPORTS_PER_SOL = 1_000_000_000;
const MINIMUM_SESSION_SOL = 0.1;
const BALANCE_CACHE_TTL_MS = 30_000;
const BALANCE_REFRESH_INTERVAL_MS = 30_000;
const BALANCE_REQUEST_TIMEOUT_MS = 12_000;
let localWalletModulePromise = null;
let localWalletModuleManifestPromise = null;
const walletBalanceCache = new Map();

The HUD's thirty-second cache and refresh interval are independent of the chain module's Session status and readiness caches. The twelve-second HTTP abort is yet another timer.

1. Lines 1–2

   Declare UI unit conversion and the displayed minimum target.

2. Lines 3–5

   Set the owner-balance cache, refresh interval, and request-abort policies.

3. Lines 6–8

   Keep module-loading state and balance-cache data in separate in-memory values.

    let clock = Clock::get()?;
    if expires_at <= clock.unix_timestamp {
        return Err(NicechunkPlayerError::InvalidInstruction.into());
    }

Setup accepts only a strictly future expiry at instruction execution. Browser Date.now and cache age are not used inside this contract decision.

1. Line 1

   Read Solana's Clock sysvar during the program instruction.

2. Lines 2–4

   Reject an expiry equal to or earlier than the chain Unix timestamp.

function loadStoredGameplaySession(owner) {
  try {
    if (!hasLocalStorage()) return null;
    const raw = localStorage.getItem(sessionStorageKey(owner));
    if (!raw) return null;
    const parsed = JSON.parse(raw);
    if (!parsed?.secretKey || !Number.isFinite(parsed.expiresAt)) return null;
    const secretKey = base64ToBytes(parsed.secretKey);
    const keypair = Keypair.fromSecretKey(secretKey);
    if (parsed.publicKey && keypair.publicKey.toBase58() !== parsed.publicKey) return null;
    return { keypair, expiresAt: Number(parsed.expiresAt) };
  } catch {
    return null;
  }
}

Missing storage, malformed JSON, invalid fields, invalid secret bytes, or a mismatching public key all leave the caller with null rather than an accessible old Keypair.

1. Lines 1–5

   Require readable localStorage and an owner-scoped serialized record.

2. Lines 6–10

   Decode JSON and secret bytes, then reject an optional saved-public-key mismatch.

3. Lines 11–14

   Return the recovered key and expiry, or null for any thrown decoding or storage error.

  const keypair = stored?.keypair ?? Keypair.generate();
  const expiresAt = nowSeconds + sessionDurationSeconds;
  const [playerProfile] = derivePlayerProfilePda(owner);
  const [playerSession] = derivePlayerSessionPda(owner, keypair.publicKey);
  const tx = new Transaction();

A decoded stored record keeps its exact authority even when the fast reuse branch was not taken. Only null storage causes Keypair.generate and therefore a different authority seed.

1. Line 1

   Prefer the recovered Keypair and generate only when no usable stored record exists.

2. Lines 2–5

   Request a new browser expiry and derive Profile and Session addresses from owner and selected key.

async function getOrCreateLocalGameWalletGameplaySession(provider) {
  const owner = provider.publicKey;
  const keypair = getLocalGameWalletKeypair();
  if (!keypair?.publicKey?.equals?.(owner)) {
    throw new Error("Local game wallet is unavailable.");
  }

  const nowSeconds = Math.floor(Date.now() / 1000);
  const expiresAt = nowSeconds + sessionDurationSeconds;
  if (isGameplaySessionReadyCached(owner, owner)) {
    return { keypair, expiresAt, localGameWallet: true };
  }

  const conn = getNicechunkConnection();
  const [playerProfile] = derivePlayerProfilePda(owner);
  const [playerSession] = derivePlayerSessionPda(owner, owner);

This branch requires the persistent Local Game Wallet key to match owner, queries readiness with owner in both positions, and derives the same-key PDA. It has no separate authority generator.

1. Lines 1–6

   Load the persistent key and refuse to continue if its public key differs from the provider owner.

2. Lines 8–12

   Compute browser time and allow the five-minute same-key ready shortcut.

3. Lines 14–16

   On a cache miss, derive the Profile and owner-owner Session addresses for RPC checks.

  if (!profileAccount?.data?.length) {
    tx.add(createInitializePlayerInstruction(owner, playerProfile, ""));
  }
  const targetLamports = sessionBalance < minimumSessionFundingLamports
    ? getConfiguredGameplaySessionFundingLamports(owner)
    : sessionBalance;
  if (sessionBalance < targetLamports) {
    tx.add(SystemProgram.transfer({
      fromPubkey: owner,
      toPubkey: keypair.publicKey,
      lamports: targetLamports - sessionBalance,
    }));
  }
  tx.add(createOrRefreshPlayerSessionInstruction({
    owner,
    sessionAuthority: keypair.publicKey,
    playerProfile,
    playerSession,
    expiresAt,
  }));

The optional Profile initialization, optional target difference transfer, and create-or-refresh instruction are appended to the same transaction object before submission.

1. Lines 1–3

   Add Profile initialization only when the fetched Profile has no data.

2. Lines 4–13

   Select target by the minimum-entry rule and append an owner-to-new-authority transfer only for a positive shortfall.

3. Lines 14–20

   Append Session setup for the exact selected authority and expiry to that same transaction.

  await signAndSendWalletTransaction(provider, tx, conn, [keypair]);
  const session = { keypair, expiresAt };
  storeGameplaySession(owner, session);
  markGameplaySessionReady(owner, keypair.publicKey, targetLamports);

The wallet helper first observes its requested confirmed commitment. Only then does the source call browser-storage persistence and mark the in-memory ready cache, making the private-key copy a second commit outside the transaction; confirmed is not relabeled finalized.

1. Line 1

   Apply the extra authority signature, owner approval, broadcast, and helper observation at confirmed commitment before returning.

2. Lines 2–3

   Assemble the local browser record and attempt to persist its private key after that confirmed observation.

3. Line 4

   Mark readiness only after storeGameplaySession returns without throwing.

  if (typeof provider.signTransaction === "function") {
    const signed = await provider.signTransaction(transaction);
    const signature = await sendRawTransactionWithLogs(conn, signed.serialize(), "wallet");
    await confirmTransactionByHttpPolling(conn, {
      signature,
      blockhash: transaction.recentBlockhash,
      lastValidBlockHeight: transaction.lastValidBlockHeight,
    }, "confirmed");
    return signature;
  }

In this provider branch the raw transaction is already submitted before status polling completes. The helper asks for confirmed, which can accept a confirmed or finalized status but does not require finalized specifically. A later error therefore needs reconciliation rather than an assumption that nothing landed.

1. Lines 1–3

   Obtain the owner signature and broadcast serialized transaction bytes, receiving a signature string.

2. Lines 4–8

   Poll that signature and blockhash lifetime while explicitly requesting confirmed commitment rather than finalized.

3. Line 9

   Return the signature only after the helper's confirmed predicate succeeds; this wording does not upgrade it to finalized.

    } catch (error) {
      state.chainMode = "adapter-error";
      const reason = readableError(error);
      logSubmissionFailure(action, pending, {
        stage: "exception",
        reason,
        error,
      });
      state.chainResults.set(pending.txId, { reason });
      const rolledBack = action === "mine" ? controls.rollbackTx?.(pending.txId) : null;
      if (!rolledBack) {
        appendSubmissionState(
          action,
          pending,
          `${pending.txId} chain adapter error: ${reason}.`,
          "error",
          { reason },
        );
      }
      render();
    }

The player-facing event text contains the local pending ID and readable reason. A separate structured console report may contain more when the error carries it, but this visible branch does not guarantee a signature, attempted authority, derived PDA, or sweep control.

1. Lines 1–8

   Convert the thrown value into a readable reason and send richer details to the separate structured failure logger.

2. Lines 9–18

   Store and display the reason around local rollback state without promising a transaction signature or authority address in the visible message.

3. Lines 19–20

   Render the updated error state; this range exposes no PDA derivation or session-balance sweep action.

  const owner = provider.publicKey;
  const ownerKey = owner.toBase58();
  const cached = gameplaySessionStatusCache.get(ownerKey);
  if (!force && cached && Date.now() - cached.loadedAt < gameplaySessionStatusCacheTtlMs) {
    return { ...cached.status };
  }

The status cache is owner-keyed and bypassed by force. Without force, a valid cached object can be returned without a new balance or Session read.

1. Lines 1–3

   Normalize the connected owner and retrieve its in-memory Session-status entry.

2. Lines 4–6

   Return a copy when force is false and the entry remains within its declared TTL.

      .catch((error) => {
        if (requestSerial === state.walletBalanceRequestSerial) {
          state.walletBalanceStatus = hadBalance ? "stale" : "error";
          renderWalletBalance();
          console.warn("NiceChunk wallet balance refresh failed", error);
        }
        return { ok: false, reason: readableError(error) };
      })

When a previous balance exists, a refresh failure marks it stale instead of clearing it. The number can remain useful on screen but is not a fresh RPC observation.

1. Lines 1–3

   Handle only the newest request and choose stale when an earlier known balance exists.

2. Lines 4–5

   Redraw that state and record the refresh error in the console.

3. Lines 7–8

   Return a structured failure without changing it into a successful fresh read.

  let balanceLamports = null;
  try {
    balanceLamports = await getNicechunkConnection().getBalance(stored.keypair.publicKey, "confirmed");
  } catch (error) {
    reportRpcError(error, "session-balance");
    throw error;
  }

  const status = {
    walletAvailable: true,
    owner: ownerKey,
    acknowledged: hasAcknowledgedGameplaySessionFunding(owner),
    configuredFundingLamports,
    minimumFundingLamports: minimumSessionFundingLamports,
    balanceLamports,
    balanceSol: balanceLamports / lamportsPerSol,
    publicKey: stored.keypair.publicKey.toBase58(),
    expiresAt: stored.expiresAt,
    usesGameplaySession: true,
    walletMode: "pluginWallet",
  };

This read targets stored.keypair.publicKey, then returns owner and authority-related fields together. The object must not be interpreted as one merged wallet.

1. Lines 1–7

   Read the stored authority's balance at confirmed commitment or surface the RPC failure.

2. Lines 9–14

   Keep the owner identity and configured browser funding policy as separate status fields.

3. Lines 15–21

   Attach the authority balance, copied expiry, public key, and explicit plugin mode.

    match tag {
        0 => initialize_player(program_id, accounts, payload),
        1 => update_position(program_id, accounts, payload),
        3 => set_backpack_style(program_id, accounts, payload),
        4 => create_or_refresh_player_session(program_id, accounts, payload),
        5 => set_equipped_backpack(program_id, accounts),
        6 => add_forging_xp(program_id, accounts, payload),
        7 => set_player_name(program_id, accounts, payload),
        8 => upsert_player_appearance(program_id, accounts, payload),
        9 => close_player_appearance(program_id, accounts),
        10 => initialize_invite_index_page(program_id, accounts, payload),
        11 => append_invite_registration(program_id, accounts, payload),
        13 => transfer_equipment_slot(program_id, accounts, payload),
        14 => swap_equipment_slots(program_id, accounts, payload),
        15 => consume_equipment_durability(program_id, accounts, payload),
        16 => release_equipment_to_market(program_id, accounts, payload),
        _ => Err(NicechunkPlayerError::InvalidInstruction.into()),
    }

Tag 4 creates or refreshes PlayerSession. Tags 13-15 manage equipment and durability; tag 16 releases equipment to Market. None closes a Session, while tag 9 closes Appearance only.

1. Lines 1–6

   The first dispatch group initializes and updates Player state, with tag 4 as the sole PlayerSession create-or-refresh entry.

2. Lines 7–12

   Name, appearance, and invitation operations occupy their own tags; tag 9 closes only PlayerAppearance.

3. Lines 13–14

   Tags 13 and 14 transfer one equipment slot or swap two equipment slots without adding a PlayerSession lifecycle instruction.

4. Lines 15–17

   Durability and Market release complete the current map, after which every unknown tag is rejected without a PlayerSession close path.

export function clearWalletSession(storage = globalThis.localStorage) {
  for (const key of Object.values(walletSessionKeys)) remove(storage, key);
  const keys = [];
  try {
    for (let index = 0; index < storage.length; index += 1) {
      const key = storage.key(index);
      if (key) keys.push(key);
    }
  } catch {
    return;
  }
  for (const key of keys) {
    if (runtimeCachePrefixes.some((prefix) => key.startsWith(prefix))) remove(storage, key);
  }
}

Cleanup first attempts identity fields and then every matching prefix without restricting the owner suffix. Enumeration failure exits early, and this function sends no chain transaction.

1. Lines 1–2

   Attempt removal of the fixed wallet-identity browser keys.

2. Lines 3–11

   Enumerate storage keys, but abandon the prefix pass when enumeration throws.

3. Lines 12–15

   Attempt removal for every recognized runtime prefix across all suffixes on the origin.

function remove(storage, key) {
  try {
    storage?.removeItem?.(key);
  } catch {
    // Logout still redirects even when browser storage is unavailable.
  }
}

The helper does not read back the key or report removal failure. Logout can continue even when a secret or target remains in browser storage.

1. Lines 1–3

   Attempt one optional localStorage removal for the supplied key.

2. Lines 4–7

   Catch and ignore an exception so redirect flow continues without a deletion guarantee.