# ⚡ ARAYA Forge Economy — Developer Onboarding Kit

Add **ARAYA Energy** as the payment + economy layer of your app in about 2 minutes.
You get the *exact* secure method behind
[ARAYA Forge Economy](https://barbrickdesign.github.io/forge-hire.html) — wallet
connect, on-chain-verified purchases, one shared balance, and gated cash-out —
without building any backend. Your app points at the shared ARAYA Forge backend,
which is your **one-stop shop for crypto integration**.

---

## What's in this kit

| File | Purpose |
|------|---------|
| `install-araya.bat` | One-click installer (Windows) — double-click it |
| `install-araya.ps1` | The installer it runs (PowerShell) |
| `install-araya.sh` | One-click installer (macOS / Linux) |
| `test-araya.html` | Open in a browser to verify everything works |
| `ARAYA-SETUP.md` | This guide |

---

## Quick start (one click)

1. Copy this whole `araya-kit` folder's files into your **project root** (next to
   your `index.html`).
2. **Windows:** double-click **`install-araya.bat`**.
   **macOS/Linux:** run `bash install-araya.sh`.
3. Pick the page to add ARAYA to (it defaults to `index.html`).
4. Done. Open that page — you'll see an **ARAYA balance** card and a **Buy** widget.

> Want local copies of the scripts instead of hot-linking? Run with `-Local`
> (`install-araya.bat index.html -Local`) — it downloads them into `./js`.

---

## What the installer adds

```html
<script src="https://barbrickdesign.github.io/js/runtime-config.js"></script>
<script src="https://barbrickdesign.github.io/js/araya-wallet.js"></script>
<script src="https://barbrickdesign.github.io/js/araya-economy.js"></script>
<div id="araya-balance"></div>   <!-- shows credits + earned + wallet -->
<div id="araya-buy"></div>       <!-- secure purchase widget -->
```

Optional mounts you can add anywhere:

```html
<div id="araya-cashout"></div>   <!-- 100k market-cap-gated cash-out -->
<div id="araya-ledger"></div>    <!-- audit feed: where/when/what -->
```

---

## Use it in your own code

```js
// read the one ARAYA balance and show it in your UI
const b = await ArayaEconomy.balance();   // { credits, earned, wallet }
myHud.setCoins(b.credits);

// send a user to buy/manage ARAYA (uses the same verified flow)
ArayaEconomy.openCheckout(10);            // 10 credits

// log gameplay/earn events with full provenance (where/when/what)
ArayaEconomy.logEvent('earn', 'gameplay', { context:{ reward:'level-up' }, xp:25 });
```

---

## Test your integration

Open **`test-araya.html`** in a browser. It runs a self-check (scripts loaded,
wallet detected, balance call works) and shows the live widgets. Connect your
wallet and try a small purchase to confirm the on-chain flow end-to-end.

---

## How it stays secure

- Your app never grants value. Credits/balance are only ever granted **server-side**
  after the shared `araya-verify` function confirms the payment **on-chain**
  (treasury received ARAYA, unique signature, sender + amount matched to a
  per-user payment intent). A copied or faked transaction can't be claimed.
- Cash-out is gated by a **market-cap lock + daily caps**, so no integrating app
  can dump and hurt the token price.

---

## FAQ

**Do I need my own Supabase / server?** No. The kit hot-links the shared config and
verifies against the shared ARAYA Forge backend.

**Which token?** ARAYA Energy — `FwHB1xfXJWRz4ogkEdrt3LX7j9tQYkVwmN8Wi7eupump`.

**My app used a different coin.** Remove its wallet/payment code, run the installer,
and point your currency display at `ArayaEconomy.balance()`.

**Does it work on mobile?** Yes. A normal mobile browser has no wallet extension,
so the Buy widget automatically shows **"Open in Phantom / Solflare / Backpack"**
buttons — these deep-link the page into the wallet's in-app browser, where the user
connects and signs natively, then stays in your app. No extra setup.

**It says "All Solana read endpoints are blocked"?** Add a CORS RPC: set
`window.RUNTIME_CONFIG.SOLANA_RPC_CORS` to a Helius/QuickNode URL before the
scripts load. Payments still work without it; this only affects live balance reads.

---

Questions or want a hand? The full economy + dashboard lives at
**https://barbrickdesign.github.io/forge-hire.html**.