dapp

Files (11)

• SKILL.md
• connect-button.tsx · components/
• invoke-contract.tsx · components/
• send-payment.tsx · components/
• dashboard-page.tsx · examples/
• use-stellar-data-example.tsx · examples/
• use-contract.ts · hooks/
• use-stellar-data.ts · hooks/
• use-stellar-wallet.ts · hooks/
• stellar-config.ts · lib/
• wallet-provider.tsx · providers/

SKILL.md (first lines)

# dApp — Agentic Kit Frontend

All blockchain queries go through `useStellarData()`. Never write raw RPC or curl.

## Wallet Setup (one-time)

```ts
// providers/wallet-provider.tsx
import { WalletProvider } from "@/providers/wallet-provider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <WalletProvider>
      {children}
    </WalletProvider>
  );
}
```

## Hooks API

### `useStellarData()` — Blockchain queries

```ts
import { useStellarData } from "@/hooks/use-stellar-data";

const {
  getBalances,     // (address: string) => { asset, balance }[]
  queryContract,   // (id: string, method: string, args: ScVal[]) => ScVal | null
  getContractData, // (id: string, key: ScVal) => ScVal | null
  getEvents,       // (id: string, limit?: number) => Event[]
  getTransaction,  // (hash: string) => TxResponse | null
  loading,         // boolean
  error,           // string | null
  rpc,             // raw RPC client (fallback only)
} = useStellarData();
```

### `useContract(contractId)` — Contract read/write

```ts
import { useContract } from "@/hooks/use-contract";

const c = useContract("CA3...");
await c.read("name");                              // simulation-only, no tx
await c.read("balance_of", [addressArg]);          // any read method
await c.write(sender, "transfer", args, signFn);   // full sign+submit
// c.data exposes the underlying useStellarData()
```

### `useStellarWallet()` — Wallet connection + data

```ts
import { useStellarWallet } from "@/hooks/use-stellar-wallet";

const {
  address,      // string | null
  network,      // string | null
  connect,      // () => Promise<void>
  disconnect,   // () => void
  sign,         // (xdr: string) => Promise<string>
  getBalances,  // () => Promise<{asset, balance}[]>
  data,         // useStellarData()
} = useStellarWallet();
```

### `useWallet()` — From WalletProvider context

```ts
import { useWallet, useContract, useStellarData } from "@/providers/wallet-provider";

const { address, sign, data, getBalances } = useWallet();
// Same as useStellarWallet() but from context — no need to call connect()
```

## Source Files (published with this skill)

| File | Location | Contents |
|------|----------|----------|
| Hook source | `hooks/use-stellar-data.ts` | `getBalances`, `queryContract`, `getContractData`, `getEvents`, `getTransaction` |
| Hook source | `hooks/use-contract.ts` | `read()` (simulation), `write()` (sign+submit) |
| Hook source | `hooks/use-stellar-wallet.ts` | `connect`, `disconnect`, `sign`, `getBalances` |
| Provider | `providers/wallet-provider.tsx` | React context + `useWallet()` export |
| Components | `components/connect-button.tsx` | Connect + disconnect + XLM balance badge |
| Components | `components/invoke-contract.tsx` | Read/write any contract method from UI |
| Components | `components/send-payment.tsx` | Send XLM with balance refresh after send |
| Config | `lib/stellar-config.ts` | RPC config, network config, helper ScVal functions |
| Examples | `examples/use-stellar-data-example.tsx` | BalanceViewer, ContractReader, EventList, UsdcBalance, XlmBalanceBadge |
| Examples | `examples/dashboard-page.tsx` | Full dashboard layout with ConnectButton + InvokeContract |

## Working Examples

### Balance viewer
```tsx
function Balances({ address }: { address: string }) {
  const { data } = useWallet();
  const [bals, setBals] = useState<{asset:string,balance:string}[]>([]);
  useEffect(() => { data.getBalances(address).then(setBals); }, [address]);
  return <ul>{bals.map(b => <li key={b.asset}>{b.asset}: {b.balance}</li>)}</ul>;
}
```

### Contract name reader
```tsx
function ContractName({ id }: { id: string }) {
  const { read } = useContract(id);
  const [name, setName] = useState("...");
  useEffect(() => { read("name").then(r => r && setName(scvalToString(r))); }, [id]);
  return <p>{name}</p>;
}
```

### Contract write + balance refresh
```tsx
function Transfer({ id, to }: { id: string; to: string }) {
  const { address, sign } = useWallet();
  const { write } = useContract(id);
  const [status, setStatus] = useState("");

From rylsherdamz-rgb/stellar-forge, MIT.

More from rylsherdamz-rgb/stellar-forge