### Install @ponziland/account Package

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/EXAMPLE.md

This command installs the necessary @ponziland/account package using npm. Ensure you have Node.js and npm installed on your system.

```bash
npm install @ponziland/account
```

--------------------------------

### Quick Start: Clone and Run PonziLand Client (Bash)

Source: https://github.com/runelabsxyz/ponziland/blob/main/readme.md

This snippet shows how to clone the PonziLand repository, navigate to the client directory, install dependencies using Bun, and start the mainnet client locally. It's intended for developers who want to quickly set up and play the game.

```bash
git clone git@github.com:RuneLabsxyz/PonziLand.git
cd PonziLand/client
bun install
bun dev:mainnet
```

--------------------------------

### Develop Svelte Project with npm

Source: https://github.com/runelabsxyz/ponziland/blob/main/client/README.md

This snippet shows how to start a development server for a Svelte project after installing dependencies. The `npm run dev` command starts the server, and the `-- --open` flag can be added to automatically open the application in a new browser tab. This assumes Node.js and npm are installed.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Install Project Dependencies using Bun

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Installs all necessary project dependencies using the Bun package manager. This command should be run after cloning the repository and navigating into the client directory. It ensures all required libraries are available for development.

```bash
bun install
```

--------------------------------

### Setup @ponziland/account in SvelteKit Root Layout

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/EXAMPLE.md

This Svelte code snippet shows how to initialize the @ponziland/account setup in the root layout of a SvelteKit application. It utilizes the `setupAccount` function from the package and the `onMount` lifecycle hook to ensure the setup runs when the component is mounted.

```svelte
<!-- src/routes/+layout.svelte -->
<script lang="ts">
  import { setupAccount } from '@ponziland/account';
  import { onMount } from 'svelte';

  onMount(async () => {
    await setupAccount();
  });
</script>

<slot />
```

--------------------------------

### Clone PonziLand Repository using Bash

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Clones the PonziLand repository from GitHub and navigates into the client directory. This is the first step to set up the project locally. No specific inputs are required beyond having git installed.

```bash
git clone git@github.com:RuneLabsxyz/PonziLand.git
cd PonziLand/client
```

--------------------------------

### Dojo Project Build and Deployment Commands

Source: https://github.com/runelabsxyz/ponziland/blob/main/contracts/README.md

A sequence of commands to build the Dojo project, inspect the game world's state, migrate the world's schema and data, and finally start the Torii client to interact with the deployed world. The Torii command requires the world address obtained from the migration step.

```bash
sozo build

sozo inspect

sozo migrate

torii --world <WORLD_ADDRESS> --http.cors_origins "*"
```

--------------------------------

### Run Katana for Local Development

Source: https://github.com/runelabsxyz/ponziland/blob/main/contracts/README.md

Starts the Katana, a Starknet development network, in development mode with fees disabled. This is the first terminal to run for local development.

```bash
katana --dev --dev.no-fee
```

--------------------------------

### Setup Nix Development Environment

Source: https://github.com/runelabsxyz/ponziland/blob/main/CLAUDE.md

Commands to enter the Nix development shell and manage database migrations. This ensures all necessary tools are available for development.

```bash
nix develop
nix run .#migrate
nix run .#new-migration <migration_name>
```

--------------------------------

### Run PonziLand Front End Locally using Bun

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Starts the PonziLand front-end development server for the mainnet environment. After running this command, the application will be accessible at https://localhost:3000. This is crucial for local testing and development.

```bash
bun dev:mainnet
```

--------------------------------

### CSS Example of Non-Working Relative Paths

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/ASSETS.md

Demonstrates CSS usage of relative paths for background images and fonts that will break when the package is installed via npm. This is an example of what NOT to do.

```css
/* This will NOT work in npm packages */
background-image: url('../static/image.png');
@font-face {
  src: url('../static/fonts/font.ttf');
}
```

--------------------------------

### Subscribe to All Lands Data (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Shows how to subscribe to updates from the `landStore` in Svelte to retrieve all land data. It includes lifecycle methods `onMount` and `onDestroy` to manage the subscription.

```typescript
import { landStore } from '$lib/stores/store.svelte';
```

```svelte
<script lang="ts">
  import { onMount, onDestroy } from 'svelte';
  let lands = [];
  let unsubscribe;

  onMount(() => {
    const subscription = landStore.getAllLands().subscribe(data => {
      lands = data || [];
    });
    unsubscribe = subscription;
  });

  onDestroy(() => unsubscribe && unsubscribe());
</script>
```

--------------------------------

### Use @ponziland/account Interface in Svelte

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/EXAMPLE.md

This Svelte code demonstrates how to obtain the account manager using the `useAccount` hook from '@ponziland/account'. It then shows how to get the provider and account instances to potentially perform transactions. The `account.execute(...)` line is a placeholder for actual transaction logic.

```svelte
<script lang="ts">
  import { useAccount } from '@ponziland/account';
  
  async function performTransaction() {
    const accountManager = useAccount();
    const provider = accountManager?.getProvider();
    const account = provider?.getAccount();
    
    if (account) {
      // Use the Starknet account interface
      // await account.execute(...);
    }
  }
</script>
```

--------------------------------

### Smart Contract Development Commands (Cairo/Dojo)

Source: https://github.com/runelabsxyz/ponziland/blob/main/CLAUDE.md

Commands for local development of Cairo smart contracts using the Dojo framework. Includes starting a local blockchain, building, testing, and running the Torii indexer. Also covers code formatting.

```bash
cd contracts

katana --dev --dev.fee  # Start local blockchain
sozo build                 # Build contracts
sozo test                  # Run tests

torii --world <WORLD_ADDRESS> --http.cors_origins "*"

scarb fmt            # Format Cairo code
scarb fmt --check    # Check formatting
```

--------------------------------

### Build Svelte Project for Production

Source: https://github.com/runelabsxyz/ponziland/blob/main/client/README.md

This command generates a production-ready build of the Svelte application. After running this, you can preview the production build using `npm run preview`. Deployment may require installing a Svelte adapter.

```bash
npm run build
```

--------------------------------

### Set Default State for New Widget in TypeScript

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Defines the default state for a new widget in the `widget.store.ts` file. This includes setting the initial position, dimensions, and open/minimized status of the widget when it's first registered or loaded. This ensures a consistent starting point for the widget's UI elements.

```typescript
export const DEFAULT_WIDGETS_STATE: Record<string, WidgetState> = {
  'your-widget': {
    id: 'your-widget',
    type: 'your-widget',
    position: { x: 100, y: 100 },
    dimensions: { width: 400, height: 300 },
    isMinimized: false,
    isOpen: false,
  },
};
```

--------------------------------

### Create Svelte Library Project with 'sv'

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/README.md

These commands are used to initialize a new Svelte library project. The 'npx sv create' command can be used to create a project in the current directory or a specified new directory. Ensure you have Node.js and npm installed.

```shell
npx sv create

# create a new project in my-app
npx sv create my-app
```

--------------------------------

### Use @ponziland/account Components in SvelteKit Pages

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/EXAMPLE.md

This Svelte code demonstrates using various components and hooks from the @ponziland/account package within a SvelteKit page. It includes importing components like `SelectWalletModal` and `OnboardingWalletInfo`, using reactive declarations for wallet state (`address`, `isConnected`), and implementing functions for connecting and disconnecting the wallet.

```svelte
<!-- src/routes/+page.svelte -->
<script lang="ts">
  import { 
    SelectWalletModal, 
    OnboardingWalletInfo,
    accountDataProvider,
    useAccount,
    shortenHex,
    padAddress
  } from '@ponziland/account';

  $: address = accountDataProvider.address;
  $: isConnected = accountDataProvider.isConnected;
  
  function handleConnect() {
    console.log('Wallet connected!');
  }
</script>

<!-- The wallet selection modal -->
<SelectWalletModal />

<!-- Simple connection button -->
<OnboardingWalletInfo onconnect={handleConnect} />

<!-- Or build your own UI -->
{#if isConnected && address}
  <div>
    <p>Connected: {shortenHex(padAddress(address), 4)}</p>
    <button onclick={() => useAccount()?.disconnect()}>
      Disconnect
    </button>
  </div>
{:else}
  <button onclick={() => useAccount()?.promptForLogin()}>
    Connect Wallet
  </button>
{/if}
```

--------------------------------

### JavaScript Example of Non-Working Direct Asset Imports

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/ASSETS.md

Shows a JavaScript import statement using '?url' for an image asset. This method does not resolve correctly when the package is distributed via npm.

```javascript
/* This will NOT work when distributed */
import imageUrl from '../../static/image.png?url';
```

--------------------------------

### Fetch On-Chain Land Data (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Provides a list of methods available on a land object obtained from `selectedLandWithActions`. These methods allow fetching various on-chain data points related to taxes, claims, auctions, yield, and land status.

```plaintext
| Method                     | Description                    |
| -------------------------- | ------------------------------ |
| `getPendingTaxes()`        | Fetch pending taxes            |
| `getNextClaim()`           | Get information on next claim  |
| `getNukable()`             | Time until land can be nuked   |
| `getCurrentAuctionPrice()` | Current auction price          |
| `getYieldInfo()`           | Yield information for the land |
| `getEstimatedNukeTime()`   | Estimated time to nuke         |
| `getNeighbors()`           | Neighboring land data          |
| `getLevelInfo()`           | Details on current land level  |
```

--------------------------------

### Configure Account After Initialization (TypeScript)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Updates the account configuration, such as the chain ID and RPC URL, after the initial setup. This function allows for dynamic changes to the connection parameters without re-initializing the entire account manager.

```typescript
import { configureAccount } from '@ponziland/account';

configureAccount({
  chainId: 'sepolia',
  rpcUrl: 'https://your-rpc-url.com'
});
```

--------------------------------

### Access Selected Land Data and Actions (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Demonstrates how to import and use the `selectedLandWithActions` store in Svelte components. It shows how to derive owner status and access land details, and lists available on-chain methods for modifying land properties and claiming rewards.

```typescript
import { selectedLandWithActions } from '$lib/stores/store.svelte';
```

```svelte
<script lang="ts">
  import account from '$lib/account.svelte';
  import { selectedLandWithActions } from '$lib/stores/store.svelte';

  const address = $derived(account.address);
  const landWithActions = $derived(selectedLandWithActions());

  const isOwner = $derived(
    landWithActions?.value?.owner === padAddress(address ?? '')
  );

  const land = $derived(landWithActions?.value);
</script>

<div>
  Pending taxes: {$land.getPendingTaxes()}
</div>
```

--------------------------------

### Initialize Account Manager (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Initializes the account manager for Starknet wallet connection. It can be configured with a specific chain ID (mainnet or sepolia) and an RPC URL. This setup function must be called once before utilizing other library features.

```svelte
<script lang="ts">
  import { setupAccount } from '@ponziland/account';
  import { onMount } from 'svelte';

  onMount(async () => {
    // Using default configuration (mainnet)
    await setupAccount();
    
    // Or with custom configuration
    await setupAccount({
      chainId: 'sepolia', // 'mainnet' or 'sepolia'
      rpcUrl: 'https://your-custom-rpc-url.com'
    });
  });
</script>
```

--------------------------------

### Embedded Base64 Font Assets in JavaScript

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/ASSETS.md

Illustrates how to embed font assets as base64 strings within JavaScript files. This approach ensures assets are self-contained and work across different project setups after npm installation. It includes the font data and CSS styles for its usage.

```javascript
// src/lib/assets/fonts-embedded.js
export const fonts = {
  myFont: 'data:font/truetype;base64,AAEAAAALAIAAAwAwR1NVQrD+...'
};

export const fontStyles = "
@font-face {
  font-family: 'MyFont';
  src: url('${fonts.myFont}');
}
";
```

--------------------------------

### GET /tokens

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Lists all authorized tokens that can be used for land purchases and staking.

```APIDOC
## GET /tokens

### Description
Lists all authorized tokens that can be used for land purchases and staking.

### Method
GET

### Endpoint
`/tokens`

### Parameters

#### Query Parameters
None

### Request Example
```bash
curl http://localhost:3000/tokens
```

### Response
#### Success Response (200)
- An array of token objects.
  - **symbol** (string) - The symbol of the token (e.g., ETH, STRK).
  - **address** (string) - The contract address of the token.

#### Response Example
```json
[
  {
    "symbol": "ETH",
    "address": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
  },
  {
    "symbol": "STRK",
    "address": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
  },
  {
    "symbol": "USDC",
    "address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8"
  }
]
```
```

--------------------------------

### Registering a New Widget in Svelte Provider

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Demonstrates how to register a new widget within the main widget provider component in Svelte. It involves importing the widget component and conditionally rendering it based on its type. This code snippet is part of the `widget-provider.svelte` file.

```svelte
<script lang="ts">
  import WidgetYour from './your-widget/WidgetYour.svelte';
  // ...other imports
</script>

{#each Object.entries($widgetsStore) as [id, widget]}
  {#if widget.isOpen}
    <Draggable {id} type={widget.type} initialPosition={widget.position}
               initialDimensions={widget.dimensions}
               bind:isMinimized={widget.isMinimized}
               disableResize={widget.disableResize}>

      {#if widget.type === 'your-widget'}
        <WidgetYour />
      {/if}

    </Draggable>
  {/if}
{/each}
```

--------------------------------

### Svelte Component Structure for PonziLand Widgets

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Defines the basic structure of a Svelte component for a PonziLand widget. It includes a script section for TypeScript logic, a div for the widget's UI markup, and a style section for scoped CSS. This serves as a template for creating new custom widgets.

```svelte
<script lang="ts">
  // Widget logic
</script>

<div class="widget-container">
  <!-- UI markup -->
</div>

<style>
  /* Scoped styles (Tailwind supported) */
</style>
```

--------------------------------

### Query Neighbor Information

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Get information about adjacent lands for tax and yield calculations.

```APIDOC
## Query Neighbor Information

### Description
Get information about adjacent lands for tax and yield calculations.

### Method
(Implied action within smart contract, not a direct HTTP endpoint)

### Endpoint
(N/A - Smart Contract Action)

### Parameters
(N/A - Smart Contract Action)

### Request Example
```cairo
// Get all 8 potential neighbors (or fewer for edge positions)
let neighbors = actions.get_neighbors(100_u16);
```

### Response
#### Neighbors Response
Returns Array<LandOrAuction>:
- LandOrAuction::Land(land) - neighbor is owned
- LandOrAuction::Auction(auction) - neighbor in auction
- LandOrAuction::None - no neighbor at position

#### Unclaimed Taxes
```cairo
// Calculate total unclaimed taxes from all neighbors
let total_unclaimed = actions.get_unclaimed_taxes_per_neighbors_total(100_u16);

// Get unclaimed taxes from specific neighbor
let unclaimed_from_101 = actions.get_unclaimed_taxes_per_neighbor(
    claimer_location: 100_u16,
    payer_location: 101_u16
);
```
```

--------------------------------

### Svelte Example of Overriding Default Image Prop

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/ASSETS.md

Demonstrates how a consuming project can override default image assets in a Svelte component by passing a custom image URL via a prop. This provides flexibility for consumers of the npm package.

```svelte
<Button defaultImage="/my-custom-button.png" />
```

--------------------------------

### GET /lands/distribution

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Returns distribution of lands by token type with caching. Shows how many lands use each token.

```APIDOC
## GET /lands/distribution

### Description
Returns distribution of lands by token type with caching. Shows how many lands use each token.

### Method
GET

### Endpoint
`/lands/distribution`

### Parameters

#### Query Parameters
None

### Request Example
```bash
curl http://localhost:3000/lands/distribution
```

### Response
#### Success Response (200)
- **total_lands** (integer) - Total number of lands.
- **distributions** (array) - An array of land distribution objects.
  - **token_address** (string) - The address of the token.
  - **land_count** (integer) - The number of lands using this token.
  - **percentage** (number) - The percentage of lands using this token.
- **cached_at** (string) - The timestamp when the cache was last updated (ISO 8601 format).

#### Response Example
```json
{
  "total_lands": 1523,
  "distributions": [
    {
      "token_address": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "land_count": 892,
      "percentage": 58.57
    },
    {
      "token_address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
      "land_count": 631,
      "percentage": 41.43
    }
  ],
  "cached_at": "2024-10-18T12:34:56.789Z"
}
```
```

--------------------------------

### Get Current Account Configuration (TypeScript)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Retrieves the current configuration settings for the account manager, including the chain ID and RPC URL. This is useful for inspecting the active settings or for conditional logic based on the current configuration.

```typescript
import { getAccountConfig } from '@ponziland/account';

const config = getAccountConfig();
console.log(config.chainId); // 'mainnet' or 'sepolia'
console.log(config.rpcUrl);
```

--------------------------------

### Access @ponziland/account State in Svelte Components

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/EXAMPLE.md

This Svelte code snippet illustrates how to access the wallet connection state and address from the `accountDataProvider` imported from '@ponziland/account'. It uses a reactive statement (`$:` ) to log the wallet address and provider name whenever the connection state changes.

```svelte
<!-- src/lib/components/MyComponent.svelte -->
<script lang="ts">
  import { accountDataProvider } from '@ponziland/account';
  
  $: if (accountDataProvider.isConnected) {
    console.log('Wallet address:', accountDataProvider.address);
    console.log('Provider:', accountDataProvider.providerName);
  }
</script>
```

--------------------------------

### Svelte Component Using Embedded Font Styles

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/ASSETS.md

A Svelte component example that imports and applies embedded font styles. It utilizes the `{@html}` tag within `<svelte:head>` to inject the CSS containing the base64 encoded font.

```svelte
<!-- Component using embedded assets -->
<script>
  import { fontStyles } from './assets/fonts-embedded.js';
</script>

<svelte:head>
  {@html `<style>${fontStyles}</style>`}
</svelte:head>
```

--------------------------------

### Modular UI Widgets using Svelte

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Implements a modular UI system using Svelte components for various game interactions. Widgets manage their own state and communicate via Svelte stores, allowing for a reactive and organized user interface. This example shows a `LandInfos` widget that fetches and displays land details based on location from URL parameters.

```svelte
<!-- client/src/lib/components/+game-ui/widgets/land-info/widget-land-info.svelte -->
<script lang="ts">
  import { landStore } from '$lib/stores/store.svelte';
  import { createLandWithActions } from '$lib/utils/land-actions';

  // Widget receives location from URL or state
  let { data } = $props<{ data: { location?: string } }>();
  let land = $state(null);

  $effect(() => {
    if (data?.location) {
      const [x, y] = parseLocation(data.location);
      const landReadable = landStore.getLand(x, y);

      landReadable.subscribe((value) => {
        if (value && BuildingLand.is(value)) {
          land = createLandWithActions(value, () => landStore.getAllLands());
        }
      });
    }
  });
</script>

{#if land}
  <LandInfos {land} />
{/if}
```

--------------------------------

### Get Lands Distribution - Rust Indexer API

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Retrieves the distribution of lands based on the token type used. This API endpoint caches results for 10 seconds, providing efficient access to land ownership distribution data.

```bash
curl http://localhost:3000/lands/distribution

# Response (cached for 10 seconds):
{
  "total_lands": 1523,
  "distributions": [
    {
      "token_address": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d",
      "land_count": 892,
      "percentage": 58.57
    },
    {
      "token_address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8",
      "land_count": 631,
      "percentage": 41.43
    }
  ],
  "cached_at": "2024-10-18T12:34:56.789Z"
}
```

--------------------------------

### Configure Widget Toggle Button in TypeScript

Source: https://github.com/runelabsxyz/ponziland/blob/main/GAMEJAM.md

Adds a new widget configuration to the `widget.config.ts` file, enabling a toggle button in the HUD for the widget. It defines the widget's ID, type, label, and icon. This allows users to open and close the new widget from the game's interface.

```typescript
export const availableWidgets: Widget[] = [
  // ...existing widgets
  {
    id: 'your-widget',
    type: 'your-widget',
    label: 'Your Widget',
    icon: '/ui/icons/Icon_Thin_Your.png',
  },
];
```

--------------------------------

### Land Store Management with Reactivity

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Manages land state across the application using a reactive Svelte store system. This store automatically syncs with blockchain events, providing real-time updates for land ownership, price, level, stake amounts, and auction states. It offers methods to get specific lands by coordinates or all lands, and a general subscription for any land changes.

```typescript
// client/src/lib/stores/store.svelte.ts
import { landStore } from '$lib/stores/store.svelte';

// Get specific land
const landReadable = landStore.getLand(10, 20); // x, y coordinates
landReadable.subscribe((land) => {
  if (land) {
    console.log(`Land at (10, 20): ${land.owner}`);
  }
});

// Get all lands
const allLands = landStore.getAllLands();
allLands.forEach((land) => {
  console.log(`${land.location}: ${land.sellPrice}`);
});

// Listen for land updates
landStore.subscribe((storeState) => {
  // Called when any land changes
  console.log('Land state updated');
});

// Store automatically updates from Dojo events:
// - Land model changes (ownership, price, level)
// - LandStake model changes (amount, neighbors)
// - Auction state changes
```

--------------------------------

### Level Up Land - Cairo Smart Contract

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Allows leveling up a land after a specified holding period, which reduces the tax rate. The level progression affects the tax rate, starting from 100% at Level::Zero and decreasing with subsequent levels.

```cairo
// Attempt to level up land after holding period
let leveled_up = actions.level_up(land_location: 100_u16);

if leveled_up {
    let (land, _) = actions.get_land(100_u16);
    // land.level is now First or Second
    // Tax rate reduced by level multiplier
}

// Level progression:
// - Level::Zero (default) - 100% tax rate
// - Level::First - Reduced tax rate after time threshold
// - Level::Second - Further reduced tax rate after longer threshold
```

--------------------------------

### Rust Backend Development Commands

Source: https://github.com/runelabsxyz/ponziland/blob/main/CLAUDE.md

Commands for building, formatting, linting, and testing the Rust backend services. Supports building all crates or specific binaries, and includes options for standard testing and nextest.

```bash
# Building

cargo build          # Build all crates
cargo build --bin indexer  # Build specific binary

# Code Quality

cargo fmt            # Format Rust code
cargo fmt --check    # Check formatting
cargo clippy         # Run linter

# Testing

cargo test           # Run tests
cargo nextest run    # Run tests with nextest (faster)
```

--------------------------------

### Frontend Development Commands (SvelteKit/TypeScript)

Source: https://github.com/runelabsxyz/ponziland/blob/main/CLAUDE.md

Commands for running the SvelteKit frontend in development and build modes across different networks, along with testing and code quality checks. Uses Bun as the package manager.

```bash
cd client

bun dev              # Local development
bun dev:sepolia      # Sepolia testnet
bun dev:mainnet      # Mainnet

bun build            # Standard build
bun build:sepolia    # Build for Sepolia
bun build:mainnet    # Build for Mainnet

bun test             # Run tests
bun test:watch       # Run tests in watch mode

bun run check        # Type check
bun run check:watch  # Type check in watch mode
bun prettier --write .   # Format code
bun prettier --check .   # Check formatting
```

--------------------------------

### Initialization and Configuration

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Functions for initializing, configuring, and retrieving the account manager configuration.

```APIDOC
## Initialization and Configuration Functions

### setupAccount(config?)

Initializes the account manager. Must be called once before using any other features.

- **Parameters**:
  - `config?` (object) - Optional configuration
    - `chainId` (string) - The Starknet chain to connect to (default: 'mainnet')
    - `rpcUrl` (string) - Custom RPC URL (default: 'https://api.cartridge.gg/x/starknet/mainnet')

### configureAccount(config)

Updates the account configuration after initialization.

- **Parameters**:
  - `config` (object) - Configuration object to update.
    - `chainId` (string) - The Starknet chain to connect to ('mainnet' or 'sepolia').
    - `rpcUrl` (string) - Custom RPC URL.

### getAccountConfig()

Returns the current configuration.

- **Returns**:
  - (object) - An object containing the current `chainId` and `rpcUrl`.
```

--------------------------------

### Build Svelte Library and Showcase App

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/README.md

Commands for building the Svelte library and its production showcase application. 'npm run package' builds the library, while 'npm run build' creates a production-ready version of the showcase app. 'npm run preview' can be used to preview the production build.

```shell
# To build your library:
npm run package

# To create a production version of your showcase app:
npm run build

You can preview the production build with 'npm run preview'.
```

--------------------------------

### Create Svelte Project with sv CLI

Source: https://github.com/runelabsxyz/ponziland/blob/main/client/README.md

These commands demonstrate how to create a new Svelte project using the sv CLI. The first command creates a project in the current directory, while the second creates a project named 'my-app'. No external dependencies are explicitly required beyond Node.js and npm/pnpm/yarn.

```bash
npx sv create

npx sv create my-app
```

--------------------------------

### Components

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Reusable Svelte components for wallet selection and displaying connection status.

```APIDOC
## Components

### SelectWalletModal

A modal that displays available Starknet wallets for connection. It automatically appears when `promptForLogin()` is called.

### OnboardingWalletInfo

A component that shows the current connection status and provides a connect button when disconnected.

- **Props**:
  - `onconnect?` (function) - Callback function called after successful connection.
  - `enablePhantom?` (boolean) - Enable Phantom (Solana) wallet connection button (default: false).
```

--------------------------------

### Add Wallet Components (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Includes UI components for wallet selection and connection status. `SelectWalletModal` displays available Starknet wallets, and `OnboardingWalletInfo` shows the connection status and a connect button. The latter can be configured to enable Phantom (Solana) wallet support.

```svelte
<script lang="ts">
  import { SelectWalletModal, OnboardingWalletInfo } from '@ponziland/account';
</script>

<!-- Wallet selection modal -->
<SelectWalletModal />

<!-- Connection button/status (Starknet only) -->
<OnboardingWalletInfo onconnect={() => console.log('Connected!')} />

<!-- Or with Phantom wallet support -->
<OnboardingWalletInfo 
  enablePhantom={true}
  onconnect={() => console.log('Connected!')} 
/>
```

--------------------------------

### Account Manager and Data Provider

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Provides access to the account manager instance for wallet interactions and a reactive data provider for wallet state.

```APIDOC
## Account Manager and Data Provider

### useAccount()

Returns the account manager instance with methods for wallet interaction.

- **Methods**:
  - `promptForLogin(): Promise<void>` - Shows the wallet selection modal.
  - `disconnect(): void` - Disconnects the current wallet.
  - `getAvailableWallets()` - Returns a list of available wallets.
  - `getProvider()` - Returns the current wallet provider.
  - `setupSession()` - Sets up session for supported wallets.

### accountDataProvider

Reactive state object containing wallet information.

- **Properties**:
  - `isConnected` (boolean) - Connection status.
  - `address` (string, optional) - Connected wallet address.
  - `walletAccount` (AccountInterface, optional) - Starknet account interface.
  - `providerName` (string, optional) - Name of the connected wallet.
```

--------------------------------

### Phantom Wallet (Solana) Integration

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Provides access to Phantom wallet state and methods for connection/disconnection.

```APIDOC
## Phantom Wallet (Solana) Integration

### phantomWalletStore

Reactive store for Phantom wallet state and actions.

- **Properties**:
  - `isConnected` (boolean) - Connection status of the Phantom wallet.
  - `walletAddress` (string, optional) - The address of the connected Phantom wallet.

- **Methods**:
  - `connect(): Promise<void>` - Connects to the Phantom wallet.
  - `disconnect(): Promise<void>` - Disconnects from the Phantom wallet.
```

--------------------------------

### Accessing a Custom Land Store (JavaScript)

Source: https://github.com/runelabsxyz/ponziland/blob/main/client/src/lib/api/UPDATE.md

This snippet demonstrates how to access a land store for a specific coordinate (x, y) and then derive its state using Svelte's $derived directive. This allows for efficient, localized updates to individual tiles.

```javascript
let landStore = getLand(x, y);
let land = $derived($landStore);
```

--------------------------------

### Rust Event Dispatcher and Consumer Implementation

Source: https://github.com/runelabsxyz/ponziland/blob/main/scraps/EVENT_STREAM.md

Implements an event dispatching system with multiple consumers in Rust. The EventDispatcher handles event persistence and distribution, while Consumers process events and update their cursors. It uses asynchronous channels (mpsc) for communication and sqlx for database interaction. Limitations include potential memory usage with unbounded channels.

```rust
// Event Dispatcher
pub struct EventDispatcher {
    channels: HashMap<ConsumerId, mpsc::Sender<EventData>>,
    db_pool: PgPool,
}

impl EventDispatcher {
    // Register a new consumer
    pub async fn register_consumer(&mut self, consumer_id: ConsumerId) -> mpsc::Receiver<EventData> {
        let (tx, rx) = mpsc::channel(100);  // Initial buffer size, will grow as needed
        self.channels.insert(consumer_id, tx);
        rx
    }
    
    // Dispatch an event to all consumers
    pub async fn dispatch(&self, event: EventData) -> Result<(), Error> {
        // First ensure event is persisted in database
        // ...
        
        // Then dispatch to all channels
        for (consumer_id, channel) in &self.channels {
            let cloned_event = event.clone();
            if let Err(e) = channel.send(cloned_event).await {
                log::error!("Failed to send event to consumer {}: {}", consumer_id, e);
                // Handle channel failure
            }
        }
        Ok(())
    }
    
    // Recovery function called at startup
    pub async fn recover(&self) -> Result<(), Error> {
        // For each consumer, get last processed event ID
        // Fetch all events after that ID
        // Send them to the consumer's channel
        // ...
        Ok(())
    }
}

// Consumer implementation
pub struct Consumer {
    id: ConsumerId,
    db_pool: PgPool,
    receiver: mpsc::Receiver<EventData>,
}

impl Consumer {
    pub async fn run(&mut self) {
        while let Some(event) = self.receiver.recv().await {
            // Process the event
            self.process_event(event).await;
            
            // Update cursor position
            self.update_cursor(event.id).await;
        }
    }
    
    async fn update_cursor(&self, event_id: EventId) {
        // Update the cursor in the unlogged table
        sqlx::query!(
            r#"
            INSERT INTO consumer_cursors (consumer_id, last_event_id, updated_at)
            VALUES ($1, $2, NOW())
            ON CONFLICT (consumer_id) 
            DO UPDATE SET last_event_id = $2, updated_at = NOW()
            "#,
            self.id.as_uuid(),
            event_id.as_uuid()
        )
        .execute(&self.db_pool)
        .await
        .expect("Failed to update cursor");
    }
}

```

--------------------------------

### Access Wallet State and Manager (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Provides access to reactive wallet state variables like connection status and address, as well as the account manager instance for performing actions such as disconnecting. This allows for dynamic UI updates and user interaction based on the wallet's connection state.

```svelte
<script lang="ts">
  import { accountDataProvider, useAccount } from '@ponziland/account';

  // Access reactive state
  let isConnected = $derived(accountDataProvider.isConnected);
  let address = $derived(accountDataProvider.address);

  // Access account manager methods
  const accountManager = useAccount();
  
  async function disconnect() {
    accountManager?.disconnect();
  }
</script>

{#if isConnected}
  <p>Connected: {address}</p>
  <button onclick={disconnect}>Disconnect</button>
{/if}
```

--------------------------------

### Publish Svelte Library to npm

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/ui/README.md

Steps to publish a Svelte library to npm. This involves updating the 'name' and potentially adding a 'license' field in 'package.json'. The 'npm publish' command then uploads the library. Ensure your package is correctly configured and versioned.

```shell
# Go into the package.json and give your package the desired name through the "name" option.
# Also consider adding a "license" field and point it to a LICENSE file.

# To publish your library to [npm](https://www.npmjs.com):
npm publish
```

--------------------------------

### Manage Phantom Wallet State (Svelte)

Source: https://github.com/runelabsxyz/ponziland/blob/main/pkgs/account/README.md

Provides access to reactive state variables for the Phantom (Solana) wallet, such as connection status and wallet address. It also exposes methods for connecting to and disconnecting from the Phantom wallet.

```svelte
<script lang="ts">
  import { phantomWalletStore } from '@ponziland/account';
  
  // Access Phantom wallet state
  let phantomConnected = $derived(phantomWalletStore.isConnected);
  let phantomAddress = $derived(phantomWalletStore.walletAddress);
  
  // Connect/disconnect Phantom
  async function connectPhantom() {
    await phantomWalletStore.connect();
  }
  
  async function disconnectPhantom() {
    await phantomWalletStore.disconnect();
  }
</script>
```

--------------------------------

### SQL Schema for Consumer Cursor Tracking

Source: https://github.com/runelabsxyz/ponziland/blob/main/scraps/EVENT_STREAM.md

Defines the unlogged table 'consumer_cursors' in SQL for tracking the last processed event ID by each consumer. This table is crucial for crash recovery and ensures event ordering. An index on 'updated_at' is included for optimization.

```sql
CREATE UNLOGGED TABLE consumer_cursors (
    consumer_id UUID PRIMARY KEY,
    last_event_id UUID NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

-- Index for faster lookups
CREATE INDEX consumer_cursors_updated_at_idx ON consumer_cursors(updated_at);

```

--------------------------------

### List Authorized Tokens - Rust Indexer API

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Provides a list of all tokens that are authorized for use in land purchases and staking within the Ponziland ecosystem. Includes the symbol and contract address for each token.

```bash
curl http://localhost:3000/tokens

# Response:
[
  {
    "symbol": "ETH",
    "address": "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
  },
  {
    "symbol": "STRK",
    "address": "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
  },
  {
    "symbol": "USDC",
    "address": "0x053c91253bc9682c04929ca02ed00b3e423f6710d2ee7e0d5ebb06f3ecf368a8"
  }
]
```

--------------------------------

### BuildingLand Class for State Management

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Represents an owned land with full state management, providing typed access to land properties and stake information. It includes methods for creating land instances, updating stake information, and accessing properties like owner, level, sellPrice, stakeAmount, and token. It also offers a static `is` method for type checking.

```typescript
// client/src/lib/api/land/building_land.ts
import { BuildingLand } from '$lib/api/land/building_land';
import type { Land, LandStake } from '$lib/models.gen';

// Create from Dojo model
const land: Land = {
  location: 100,
  owner: '0x123...',
  sell_price: 1000n,
  token_used: '0xabc...',
  block_date_bought: 1697500000n,
  level: { Zero: {} }
};

const buildingLand = new BuildingLand(land);

// Update stake information
const landStake: LandStake = {
  location: 100,
  amount: 500n,
  neighbors_info_packed: 0n,
  accumulated_taxes_fee: 0n
};
buildingLand.updateStake(landStake);

// Access typed properties
console.log(buildingLand.owner); // '0x123...'
console.log(buildingLand.level); // 'Zero' | 'First' | 'Second'
console.log(buildingLand.sellPrice); // CurrencyAmount instance
console.log(buildingLand.stakeAmount); // CurrencyAmount instance
console.log(buildingLand.token); // Token { symbol, address, decimals }

// Check land type
if (BuildingLand.is(someLand)) {
  // TypeScript knows someLand is BuildingLand
  const owner = someLand.owner;
}
```

--------------------------------

### Query Land Information

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Retrieve comprehensive land and stake data for gameplay calculations.

```APIDOC
## Query Land Information

### Description
Retrieve comprehensive land and stake data for gameplay calculations.

### Method
(Implied action within smart contract, not a direct HTTP endpoint)

### Endpoint
(N/A - Smart Contract Action)

### Parameters
(N/A - Smart Contract Action)

### Request Example
```cairo
// Get complete land details
let (land, land_stake) = actions.get_land(100_u16);
```

### Response
#### Land Properties
- **location** (u16) - grid position
- **owner** (ContractAddress)
- **sell_price** (u256)
- **token_used** (ContractAddress) - stake/sale token
- **block_date_bought** (u64) - timestamp
- **level** (Level enum)

#### LandStake Properties
- **amount** (u256) - staked tokens
- **neighbors_info_packed** (u128) - packed neighbor data
- **accumulated_taxes_fee** (u128)

#### Yield Information
```cairo
// Get yield information
let yield_info = actions.get_neighbors_yield(100_u16);
// Returns LandYieldInfo with per-neighbor yield rates and remaining stake time
```
```

--------------------------------

### TypeScript Currency Amount Handling and Operations

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Demonstrates the creation and manipulation of currency amounts using the CurrencyAmount utility. It covers creating amounts from unscaled and scaled values, performing arithmetic operations like addition, subtraction, multiplication, and division, and conducting comparisons between amounts. Dependencies include the CurrencyAmount class itself.

```typescript
// client/src/lib/utils/CurrencyAmount.ts
import { CurrencyAmount } from '$lib/utils/CurrencyAmount';

const token = {
  symbol: 'ETH',
  address: '0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7',
  decimals: 18
};

// Create from unscaled (wei) amount
const amount = CurrencyAmount.fromUnscaled(1000000000000000000n, token);
console.log(amount.toFixed(4)); // "1.0000"
console.log(amount.toSignificant(3)); // "1.00"

// Create from scaled (human) amount
const amount2 = CurrencyAmount.fromScaled('1.5', token);
console.log(amount2.unscaled); // 1500000000000000000n

// Arithmetic operations
const sum = amount.add(amount2);
const diff = amount.subtract(amount2);
const product = amount.multiply(2);
const quotient = amount.divide(2);

// Comparisons
if (amount.greaterThan(amount2)) {
  console.log('Amount 1 is larger');
}
```

--------------------------------

### Wrapped Contract Actions with Auto Approval

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

Provides utility functions to execute game actions (buy, bid, increaseStake) with automatic ERC20 token approval. It simplifies contract interactions by handling the 'approve' call before executing the main action, ensuring tokens are approved for the required amounts. All methods return a transaction hash and wait for confirmation.

```typescript
// client/src/lib/api/contracts/approve.ts
import { wrappedActions } from '$lib/api/contracts/approve';
import { DojoProvider } from '@dojoengine/core';

const provider = new DojoProvider(/* ... */);
const { actions } = await wrappedActions(provider);

// Buy land with automatic token approval
// Approves currentToken for buy price and tokenForSale for stake
await actions.buy(
  account,
  100n, // land_location
  '0xabc...', // tokenForSale
  1000n, // sellPrice
  500n, // amountToStake
  '0xdef...', // currentToken (token to pay with)
  1000n // buyPrice (current price of land)
);

// Bid on auction with automatic approval
await actions.bid(
  account,
  50n, // land_location
  '0xabc...', // tokenForSale
  2000n,
  800n, // amountToStake
  '0xdef...', // buyingToken
  1500n // currentPrice (auction price)
);

// Increase stake with automatic approval
await actions.increaseStake(
  account,
  100n, // land_location
  '0xabc...', // stakingToken
  300n // amountToStake
);

// All methods return transaction hash and wait for confirmation
```

--------------------------------

### Proxy Paymaster Requests - Rust API

Source: https://context7.com/runelabsxyz/ponziland/llms.txt

This API endpoint proxies paymaster requests to the AVNU paymaster service using an API key. It forwards requests for gasless transactions and returns proxied responses or handles errors.

```bash
curl -X POST http://localhost:3000/api/paymaster \
  -H "Content-Type: application/json" \
  -d '{ \
    "method": "pm_getPaymasterData", \
    "params": { \
      "calls": [{ \
        "to": "0x...", \
        "selector": "0x...", \
        "calldata": ["0x1", "0x2"] \
      }] \
    } \
  }'

# Response proxied from AVNU paymaster:
{
  "paymasterData": {
    "paymaster": "0x...",
    "paymasterDataLength": 2,
    "paymasterData": ["0x...", "0x..."]
  }
}

# Error handling:
# - 500 if proxy request fails
# - Preserves original status codes from paymaster
```