Transaction Fees, Account Rent, and Recovery: Who Pays and What Can Return

async function signAndSendWalletTransaction(provider, transaction, conn = getNicechunkConnection(), extraSigners = []) {
  transaction.feePayer = provider.publicKey;

  if (typeof conn.prepareTransaction === "function") {
    await conn.prepareTransaction(transaction, { commitment: "confirmed" });
  } else {
    const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash("confirmed");
    transaction.recentBlockhash = blockhash;
    transaction.lastValidBlockHeight = lastValidBlockHeight;
  }

  for (const signer of extraSigners) transaction.partialSign(signer);

  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;
  }

  if (typeof provider.signAndSendTransaction !== "function") {
    throw new Error("Wallet does not support transaction signing.");
  }
  const result = await provider.signAndSendTransaction(transaction);
  const signature = typeof result === "string" ? result : result?.signature;
  if (!signature) throw new Error("Wallet did not return a transaction signature.");
  await confirmTransactionByHttpPolling(conn, {
    signature,
    blockhash: transaction.recentBlockhash,
    lastValidBlockHeight: transaction.lastValidBlockHeight,
  }, "confirmed");
  return signature;
}

async function signAndSendKeypairTransaction(signer, transaction, conn = getNicechunkConnection()) {
  transaction.feePayer = signer.publicKey;
  const { blockhash, lastValidBlockHeight } = await conn.getLatestBlockhash("confirmed");
  transaction.recentBlockhash = blockhash;
  transaction.lastValidBlockHeight = lastValidBlockHeight;
  transaction.sign(signer);
  const signature = await sendRawTransactionWithLogs(conn, transaction.serialize(), "keypair");
  await confirmTransactionByHttpPolling(conn, { signature, blockhash, lastValidBlockHeight }, "confirmed");
  return signature;
}

The outer helper makes the wallet provider or supplied Keypair the fee payer. An extra signer can co-sign without becoming fee payer.

1. Lines 1–12

   The wallet public key is assigned as fee payer before blockhash preparation and any extra partial signatures.

2. Lines 13–36

   The wallet signs, sends, and waits for confirmed commitment.

3. Lines 38–46

   The keypair path instead assigns the supplied signer as fee payer and signs directly.

  const keypair = stored?.keypair ?? Keypair.generate();
  const expiresAt = nowSeconds + sessionDurationSeconds;
  const [playerProfile] = derivePlayerProfilePda(owner);
  const [playerSession] = derivePlayerSessionPda(owner, keypair.publicKey);
  const tx = new Transaction();
  const [profileAccount, sessionAccount] = await conn.getMultipleAccountsInfo(
    [playerProfile, keypair.publicKey],
    "confirmed",
  );
  const sessionBalance = accountLamports(sessionAccount);

  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,
  }));

  await signAndSendWalletTransaction(provider, tx, conn, [keypair]);

One owner-fee-paid transaction may initialize Profile, top up the ordinary temporary address, and create or refresh its Session PDA. The keypair is an extra signer.

1. Lines 1–10

   Reuse or generate the Session key, derive its accounts, and read Profile existence plus ordinary authority balance.

2. Lines 12–24

   Optionally add Profile initialization and an owner-to-authority System Program transfer.

3. Lines 25–33

   Add Session setup and send with the wallet as fee payer plus the Session key as co-signer.

  const promise = fetch(rpcUrl, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "getMinimumBalanceForRentExemption",
      params: [bytes, { commitment: "processed" }],
    }),

The client sends the byte length to the configured RPC rather than deriving a permanent SOL number from source constants.

1. Lines 1–3

   Send a JSON-RPC POST request.

2. Lines 4–9

   Request the rent-exempt minimum for this byte length at processed commitment.

    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,
        );
        invoke_signed(
            &create,
            &[
                payer.clone(),
                player_session.clone(),
                system_program_account.clone(),
            ],
            &[&[
                PLAYER_SESSION_SEED,
                payer.key.as_ref(),
                session_authority.as_ref(),
                &[bump],
            ]],
        )?;
        return Ok(());
    }

The program queries rent for the fixed 184-byte layout and places that amount in the Session PDA using payer.key.

1. Lines 1–2

   Read the current Rent sysvar and calculate the minimum for PlayerSession::LEN.

2. Lines 4–10

   Build account creation using the instruction payer as funding source.

3. Lines 11–25

   Sign for the PDA with owner and Session-authority derivation seeds.

async function sendRawTransactionWithLogs(conn, serializedTransaction, context) {
  try {
    return await conn.sendRawTransaction(serializedTransaction, { skipPreflight: false });
  } catch (error) {
    await attachSendTransactionLogs(error, conn, context);
    throw error;
  }
}

A send error on this path is accompanied by preflight-enabled submission. It does not by itself demonstrate accepted execution.

1. Lines 1–3

   Submit the signed bytes with preflight enabled.

2. Lines 4–7

   Attach available diagnostic logs and preserve the failure.

  while (true) {
    const statusResponse = await conn.getSignatureStatuses([signature]);
    const status = statusResponse?.value?.[0] ?? null;
    if (status?.err) throw createTransactionStatusError(signature, status.err);
    if (hasReachedSignatureCommitment(status, commitment)) {
      return {
        context: statusResponse.context,
        value: { err: null },
      };
    }

The helper checks the submitted signature and keeps successful commitment distinct from a status that contains an execution error.

1. Lines 1–4

   Poll the signature and throw a status error that retains the signature when execution failed.

2. Lines 5–10

   Return success only after the requested commitment is reached without an error.

function transactionSolSpendFromMeta(transaction, payerKey, signature) {
  const meta = transaction?.meta;
  const preBalances = meta?.preBalances;
  const postBalances = meta?.postBalances;
  if (!Array.isArray(preBalances) || !Array.isArray(postBalances)) return null;
  const accountKeys = transactionAccountKeys(transaction);
  let payerIndex = accountKeys.findIndex((key) => key === payerKey);
  if (payerIndex < 0) payerIndex = 0;
  const pre = Number(preBalances[payerIndex]);
  const post = Number(postBalances[payerIndex]);
  const balanceDelta = Number.isFinite(pre) && Number.isFinite(post) ? Math.max(0, pre - post) : 0;
  const fee = Number(meta?.fee);
  const lamports = Math.max(balanceDelta, Number.isFinite(fee) ? fee : 0);
  if (!Number.isFinite(lamports) || lamports <= 0) return null;
  return {
    signature,
    payer: payerKey,
    lamports: Math.floor(lamports),
    feeLamports: Number.isFinite(fee) ? Math.floor(fee) : null,
  };
}

lamports is a broad payer-decrease measure; feeLamports is the actual processing-fee field when transaction metadata is available.

1. Lines 1–8

   Find the payer inside the transaction balance arrays.

2. Lines 9–13

   Calculate positive payer decrease and read meta.fee separately.

3. Lines 14–20

   Return both the broad spend number and the narrower fee field.

    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()),
    }

The complete dispatch exposes Appearance close at tag 9, equipment-to-Market release at tag 16, and no Profile, Session, Equipment, UsernameIndex, or InviteIndex close.

1. Lines 1–8

   Dispatch ordinary Player initialization, position, Backpack style, Session setup, equipment selection, XP, name, and Appearance updates.

2. Lines 9–12

   Expose the sole account-close handler at tag 9 for PlayerAppearance, followed by invitation-index operations that do not close accounts.

3. Lines 13–17

   Handle equipment transfer, swap, durability, and Market release, then reject unknown tags without another Player account close.

    match tag {
        0 => initialize_backpack(program_id, accounts, payload),
        1 => append_mined_resource(program_id, accounts, payload),
        2 => remove_resource(program_id, accounts, payload),
        3 => append_market_resource(program_id, accounts, payload),
        4 => remove_resources(program_id, accounts, payload),
        5 => append_smelting_item(program_id, accounts, payload),
        6 => append_mined_resources_batch(program_id, accounts, payload),
        7 => Err(NicechunkBackpackError::UnverifiedForgeInstructionDisabled.into()),
        8 => forge_equipment_with_material_verification(program_id, accounts, payload),
        9 => issue_blueprint(program_id, accounts, payload),
        10 => transfer_backpack_item_to_equipment(program_id, accounts, payload),
        11 => transfer_equipment_item_to_backpack(program_id, accounts, payload),
        12 => configure_material_physics(program_id, accounts, payload),
        13 => record_mining_action(program_id, accounts, payload),
        14 => consume_smelting_resources(program_id, accounts, payload),
        _ => Err(NicechunkBackpackError::InvalidInstruction.into()),
    }
}

The unified Game program routes a namespace to this dispatch. It initializes and mutates Backpack custody but exposes no account close.

1. Lines 1–8

   Initialization and inventory append or removal actions are listed.

2. Lines 9–15

   Forging, blueprint, custody transfers, material physics, mining snapshots, and quantity-aware smelting consumption complete the map without a close tag.

    let clock = Clock::get()?;
    {
        let mut data = listing.try_borrow_mut_data()?;
        ListingAccount::mark_canceled(&mut data, clock.slot, clock.unix_timestamp)?;
    }
    decrement_market_user_active(market_user, seller.key, clock.slot)?;
    Ok(())

After restoring the item, cancellation marks the Listing and decrements seller active count. It does not clear data, drain lamports, or close the account, so rent remains allocated.

1. Lines 1–6

   Read chain time, borrow Listing data, and persist the canceled state with its slot and timestamp.

2. Lines 7–8

   Decrease the seller's active Listing count and return without draining or closing the Listing account.

    append_market_slot_to_backpack(
        program_id,
        market_authority,
        buyer,
        buyer_backpack,
        backpack_program,
        material_physics,
        &source_slot,
    )?;

    let clock = Clock::get()?;
    {
        let mut data = listing.try_borrow_mut_data()?;
        ListingAccount::mark_sold(&mut data, buyer.key, clock.slot, clock.unix_timestamp)?;
    }
    decrement_market_user_active(seller_market_user, seller.key, clock.slot)?;
    Ok(())

The item enters the buyer Backpack, the Listing records buyer and sale time, and seller active count decreases. No lamport drain or account close occurs.

1. Lines 1–9

   Append the escrowed source record to the buyer's validated Backpack before changing Listing status.

2. Lines 11–17

   Record buyer, sale slot, and sale time, then decrement seller active count without draining or closing the Listing.

    if !treasury_authority.is_signer || !treasury_authority.is_writable || !recipient.is_writable {
        return Err(NicechunkPlayerError::InvalidTreasuryAuthority.into());
    }
    require_key_eq(
        treasury_authority.key,
        &NICECHUNK_TREASURY_AUTHORITY,
        NicechunkPlayerError::InvalidTreasuryAuthority,
    )?;
    require_key_eq(
        recipient.key,
        treasury_authority.key,
        NicechunkPlayerError::InvalidTreasuryAuthority,
    )?;
    require_key_eq(
        appearance.owner,
        program_id,
        NicechunkPlayerError::InvalidAppearanceOwner,
    )?;

    {
        let data = appearance.try_borrow_data()?;
        PlayerAppearance::validate_treasury_authority(&data, treasury_authority.key)?;
        let owner = PlayerAppearance::owner(&data)?;
        let (expected_appearance, _) =
            Pubkey::find_program_address(&[PLAYER_APPEARANCE_SEED, owner.as_ref()], program_id);
        require_key_eq(
            appearance.key,
            &expected_appearance,
            NicechunkPlayerError::InvalidAppearancePda,
        )?;
    }
    {
        let mut data = appearance.try_borrow_mut_data()?;
        data.fill(0);
    }
    let reclaimed_lamports = appearance.lamports();
    **recipient.try_borrow_mut_lamports()? = recipient
        .lamports()
        .checked_add(reclaimed_lamports)
        .ok_or(NicechunkPlayerError::InvalidAppearanceData)?;
    **appearance.try_borrow_mut_lamports()? = 0;

Both signing authority and recipient must be the configured treasury. The player's owner key is not accepted as the reclaim recipient.

1. Lines 1–19

   Require writable treasury signer, treasury recipient equality, and Player ownership of Appearance.

2. Lines 21–33

   Validate stored treasury policy and the owner-derived Appearance PDA.

3. Lines 34–43

   Clear data, transfer all current lamports to treasury, and drain Appearance.

    {
        let mut data = build_site.try_borrow_mut_data()?;
        BuildSiteState::cancel_building(
            &mut data,
            &context.owner,
            global_config.key,
            revision,
            context.clock.slot,
        )?;
    }
    for account in shard_accounts {
        if account.owner == program_id {
            close_program_account(account, session_authority)?;
        }
    }
    close_program_account(manifest, session_authority)
}

fn close_program_account(account: &AccountInfo, recipient: &AccountInfo) -> ProgramResult {
    let account_lamports = account.lamports();
    let recipient_lamports = recipient.lamports();
    **recipient.try_borrow_mut_lamports()? = recipient_lamports
        .checked_add(account_lamports)
        .ok_or(NicechunkBuildingError::InvalidSystemAccount)?;
    **account.try_borrow_mut_lamports()? = 0;
    account.try_borrow_mut_data()?.fill(0);
    Ok(())
}

The BuildSite is updated, each existing program-owned shard is drained, and the manifest is drained. The recipient passed by this instruction is session_authority.

1. Lines 1–10

   Clear only the pending revision on the persistent BuildSite.

2. Lines 11–16

   Close existing shards and then the manifest to the current Session authority.

3. Lines 19–28

   The close helper adds all account lamports to the recipient, zeros lamports, and clears data.

async function fundBuildingUploadSession(provider, sessionAuthority, accountLengths, conn) {
  if (provider.publicKey.equals(sessionAuthority)) return;
  const lengths = (accountLengths ?? []).map((value) => Math.max(0, Math.trunc(Number(value) || 0))).filter(Boolean);
  const uniqueLengths = [...new Set(lengths)];
  const rentValues = await Promise.all(uniqueLengths.map((length) => conn.getMinimumBalanceForRentExemption(length)));
  const rentByLength = new Map(uniqueLengths.map((length, index) => [length, rentValues[index]]));
  const required = lengths.reduce((sum, length) => sum + (rentByLength.get(length) || 0), 0) + 1_000_000;
  const balance = await conn.getBalance(sessionAuthority, "confirmed");
  if (balance >= required) return;
  const transaction = new Transaction().add(SystemProgram.transfer({
    fromPubkey: provider.publicKey,
    toPubkey: sessionAuthority,
    lamports: required - balance,
  }));
  await signAndSendWalletTransaction(provider, transaction, conn);
}

Plugin mode estimates rent for missing account lengths and tops the Session authority up to that total plus one million lamports. The buffer is ordinary Session SOL, not PDA rent.

1. Lines 1–6

   Skip when owner and Session are one address, then query rent once per unique account length.

2. Lines 7–9

   Sum each account requirement, add the buffer, and compare the ordinary Session balance.

3. Lines 10–16

   Transfer only the missing amount from owner with an owner-fee-paid transaction.

    let rent = Rent::get()?;
    let lamports = rent.minimum_balance(PLAYER_PROGRESS_LEN);
    if player_progress.lamports() == 0 {
        let create = system_create_account(
            payer.key,
            player_progress.key,
            lamports,
            PLAYER_PROGRESS_LEN as u64,
            program_id,
        );
        invoke_signed(
            &create,
            &[
                payer.clone(),
                player_progress.clone(),
                system_program_account.clone(),
            ],
            &[seeds],
        )?;
    } else {

The mining flow passes Session authority as payer into this helper, which creates the 128-byte progress account at the runtime minimum.

1. Lines 1–2

   Calculate current rent for PLAYER_PROGRESS_LEN.

2. Lines 3–10

   Create the PDA using payer.key as lamport source.

3. Lines 11–19

   Invoke with payer, progress, and System Program accounts plus PDA seeds.

    let (tag, payload) = instruction_data
        .split_first()
        .ok_or(NicechunkGameError::InvalidInstruction)?;

    match *tag {
        NS_BACKPACK => nicechunk_backpack::process_instruction(program_id, accounts, payload),
        NS_CHUNK => nicechunk_chunk::process_instruction(program_id, accounts, payload),
        NS_SMELTING => nicechunk_smelting::process_instruction(program_id, accounts, payload),
        NS_MARKET => nicechunk_market::process_instruction(program_id, accounts, payload),
        _ => Err(NicechunkGameError::InvalidInstruction.into()),
    }

Current configuration uses this Game program for Backpack, Market, and Smelting. The namespace dispatcher adds no separate close behavior; each module's own dispatch remains decisive.

1. Lines 1–3

   Read the first byte as a namespace tag.

2. Lines 5–10

   Delegate to one module or reject an unknown namespace.

pub fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    if instruction_data != [0] {
        return Err(NicechunkError::InvalidInstruction.into());
    }

    initialize_global_config(program_id, accounts)
}

Core accepts only tag 0 GlobalConfig initialization in this revision. There is no update or close dispatch.

1. Lines 1–8

   Reject every instruction payload other than one byte containing zero.

2. Line 10

   Run GlobalConfig initialization as the only action.

    match tag {
        0 => initialize_registry(program_id, accounts),
        1 => register_genesis_guardian(program_id, accounts, payload),
        2 => register_guardian(program_id, accounts, payload),
        5 => update_guardian_endpoint(program_id, accounts, payload),
        6 => update_guardian_blueprint(program_id, accounts, payload),
        8 => update_guardian_operator(program_id, accounts, payload),
        _ => Err(NicechunkGuardianError::InvalidInstruction.into()),
    }

Registry and Region records can be created or updated, but no current tag closes them or returns their account lamports.

1. Lines 1–4

   Initialize registry and register genesis or later Regions.

2. Lines 5–8

   Update endpoint, blueprint, or operator and reject every other tag.

    match tag {
        0 => publish_rule_book(program_id, accounts, payload),
        1 => sign_rule(program_id, accounts, payload),
        2 => finalize_rule_tally(program_id, accounts),
        3 => execute_rule_receipt(program_id, accounts),
        4 => publish_power_snapshot(program_id, accounts, payload),
        5 => settle_citizen_power(program_id, accounts, payload),
        _ => Err(NicechunkCivilizationError::InvalidInstruction.into()),
    }

Publishing, signing, finalizing, executing, and settling all leave their program accounts allocated.

1. Lines 1–4

   Create a rule, signature, tally, or receipt transition.

2. Lines 5–8

   Create power records or reject an unrecognized action; no close appears.

    match tag {
        0 => initialize_recipe_table(program_id, accounts, payload),
        1 => upsert_recipe(program_id, accounts, payload),
        2 => execute_smelting(program_id, accounts, payload),
        4 => apply_civilization_recipe_receipt(program_id, accounts, payload),
        _ => Err(NicechunkSmeltingError::InvalidInstruction.into()),
    }

The Smelting map exposes treasury-controlled initialization and upsert, owner execution, and Civilization receipt application. Tag 3 authority transfer is absent, and no branch closes RecipeTable or PlayerProgress accounts.

1. Lines 1–4

   Initialize or update recipes and execute a player Smelting action.

2. Lines 5–6

   Apply a Civilization receipt or reject every other tag; no authority-transfer or close branch exists.

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);
  }
}

This function deletes local identity and runtime-cache keys. It constructs no transaction, calls no RPC, and invokes no program close.

1. Lines 1–2

   Remove saved wallet identity values.

2. Lines 3–11

   Enumerate browser storage, returning early if enumeration fails.

3. Lines 12–14

   Remove keys matching plugin Session and related runtime prefixes.

export function getLocalGameWalletProvider() {
  const keypair = loadLocalGameWalletKeypair();
  if (!keypair) return null;
  return {
    isNiceChunkLocalGameWallet: true,
    isConnected: true,
    publicKey: keypair.publicKey,
    async connect() {
      return { publicKey: keypair.publicKey };
    },
    async disconnect() {
      return undefined;
    },
    async signTransaction(transaction) {
      transaction.partialSign(keypair);
      return transaction;
    },

The Local Game Wallet provider stays backed by the same loaded keypair, and disconnect returns without removing it.

1. Lines 1–7

   Load the persistent key and expose its public address.

2. Lines 8–13

   Connect returns the address, while disconnect performs no deletion.

3. Lines 14–17

   The same keypair remains able to sign transactions.