npm - starkzap-starter - Versions diffs - 0.1.0 - Mend

starkzap-starter 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/.env.example +23 -0
package/README.md +164 -0
package/cli-package.json +31 -0
package/next.config.mjs +8 -0
package/package.json +33 -0
package/postcss.config.js +6 -0
package/scripts/create-starkzap-app.mjs +1749 -0
package/src/app/globals.css +46 -0
package/src/app/layout.tsx +21 -0
package/src/app/page.tsx +159 -0
package/src/components/payment/PaymentForm.tsx +158 -0
package/src/components/wallet/TokenBalanceCard.tsx +79 -0
package/src/components/wallet/WalletButton.tsx +59 -0
package/src/hooks/useGaslessTransfer.ts +88 -0
package/src/hooks/useTokenBalance.ts +66 -0
package/src/hooks/useWallet.ts +88 -0
package/src/lib/starkzap.ts +22 -0
package/src/lib/utils.ts +54 -0
package/tailwind.config.js +43 -0
package/tsconfig.json +22 -0

package/src/app/globals.css ADDED Viewed

@@ -0,0 +1,46 @@
+@import url('https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap');
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+:root {
+  --stark-glow: 0 0 40px rgba(26, 71, 251, 0.15);
+}
+* {
+  box-sizing: border-box;
+}
+html {
+  scroll-behavior: smooth;
+}
+body {
+  background-color: #04060f;
+  color: #e2e8ff;
+  font-family: 'DM Sans', sans-serif;
+  -webkit-font-smoothing: antialiased;
+}
+/* Subtle animated grid background */
+.grid-bg {
+  background-image:
+    linear-gradient(rgba(26, 71, 251, 0.04) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(26, 71, 251, 0.04) 1px, transparent 1px);
+  background-size: 40px 40px;
+}
+/* Glowing border on focus */
+.glow-border:focus-within {
+  box-shadow: 0 0 0 2px rgba(26, 71, 251, 0.4);
+}
+@layer utilities {
+  .text-gradient {
+    background: linear-gradient(135deg, #86a8ff 0%, #ffffff 50%, #ff6b35 100%);
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent;
+    background-clip: text;
+  }
+}

package/src/app/layout.tsx ADDED Viewed

@@ -0,0 +1,21 @@
+import type { Metadata } from "next";
+import "./globals.css";
+export const metadata: Metadata = {
+  title: "Starkzap Starter",
+  description:
+    "Next.js 14 starter kit for building on Starknet with the Starkzap SDK — wallet connect, gasless transactions, token balances, and payment UI out of the box.",
+  keywords: ["starknet", "starkzap", "web3", "blockchain", "defi", "nextjs"],
+};
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body className="min-h-screen grid-bg antialiased">{children}</body>
+    </html>
+  );
+}

package/src/app/page.tsx ADDED Viewed

@@ -0,0 +1,159 @@
+"use client";
+import { useWallet } from "@/hooks/useWallet";
+import { WalletButton } from "@/components/wallet/WalletButton";
+import { TokenBalanceCard } from "@/components/wallet/TokenBalanceCard";
+import { PaymentForm } from "@/components/payment/PaymentForm";
+import { formatAddress } from "@/lib/utils";
+import { network } from "@/lib/starkzap";
+export default function Home() {
+  const walletState = useWallet();
+  const { wallet, address, error: walletError } = walletState;
+  return (
+    <div className="min-h-screen flex flex-col">
+      {/* ── Header ─────────────────────────────────────────── */}
+      <header className="border-b border-stark-900/80 bg-stark-950/50 backdrop-blur-md sticky top-0 z-50">
+        <div className="mx-auto flex max-w-5xl items-center justify-between px-6 py-4">
+          <div className="flex items-center gap-3">
+            <span className="text-xl">⚡</span>
+            <span className="font-mono font-semibold text-white tracking-tight">
+              starkzap<span className="text-stark-400">-starter</span>
+            </span>
+            <span className="rounded-full bg-stark-900 border border-stark-800 px-2.5 py-0.5 text-xs font-mono text-stark-400">
+              {network}
+            </span>
+          </div>
+          <WalletButton walletState={walletState} />
+        </div>
+      </header>
+      {/* ── Hero ───────────────────────────────────────────── */}
+      <section className="mx-auto max-w-5xl px-6 py-16 text-center animate-fade-in">
+        <p className="mb-3 text-xs font-mono uppercase tracking-[0.2em] text-stark-500">
+          Next.js 14 · App Router · TypeScript
+        </p>
+        <h1 className="text-5xl font-bold leading-tight text-gradient mb-5">
+          Build on Starknet.
+          <br />
+          Ship in minutes.
+        </h1>
+        <p className="mx-auto max-w-xl text-stark-400 text-lg leading-relaxed">
+          A production-ready starter kit powered by the{" "}
+          <a
+            href="https://docs.starknet.io/build/starkzap/overview"
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-stark-300 underline decoration-stark-700 hover:decoration-stark-400 transition-colors"
+          >
+            Starkzap SDK
+          </a>
+          . Wallet connect, gasless transactions, token balances, and a payment UI — all wired up.
+        </p>
+        {walletError && (
+          <div className="mx-auto mt-6 max-w-md rounded-xl border border-red-900 bg-red-950/40 px-4 py-3 text-sm text-red-400">
+            {walletError}
+          </div>
+        )}
+      </section>
+      {/* ── Main Demo ──────────────────────────────────────── */}
+      <main className="mx-auto w-full max-w-5xl flex-1 px-6 pb-20">
+        {!address ? (
+          /* ── Not connected state ── */
+          <div className="rounded-2xl border border-dashed border-stark-800 bg-stark-950/40 p-12 text-center">
+            <p className="text-4xl mb-4">🔌</p>
+            <p className="font-semibold text-stark-300 mb-2">Connect your wallet to get started</p>
+            <p className="text-sm text-stark-600 mb-6">
+              Supports Argent X and Braavos. Social login via Privy available — see README.
+            </p>
+            <WalletButton walletState={walletState} className="mx-auto" />
+          </div>
+        ) : (
+          /* ── Connected state ── */
+          <div className="animate-fade-in space-y-6">
+            {/* Address banner */}
+            <div className="flex items-center gap-3 rounded-xl border border-stark-800 bg-stark-900/40 px-4 py-3">
+              <span className="h-2 w-2 rounded-full bg-emerald-400 shadow-[0_0_8px_rgba(52,211,153,0.6)]" />
+              <span className="text-sm text-stark-400">Connected as</span>
+              <span className="font-mono text-sm text-white">{address}</span>
+              <a
+                href={`https://${network === "mainnet" ? "" : "sepolia."}starkscan.co/address/${address}`}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="ml-auto text-xs text-stark-600 hover:text-stark-300 transition-colors"
+              >
+                View on explorer ↗
+              </a>
+            </div>
+            {/* Balances + Payment side by side */}
+            <div className="grid gap-6 md:grid-cols-2">
+              {/* Left: token balances */}
+              <div className="space-y-4">
+                <h2 className="text-xs font-mono uppercase tracking-widest text-stark-500">
+                  Token Balances
+                </h2>
+                <TokenBalanceCard wallet={wallet} symbol="STRK" />
+                <TokenBalanceCard wallet={wallet} symbol="ETH" />
+                <TokenBalanceCard wallet={wallet} symbol="USDC" />
+              </div>
+              {/* Right: gasless payment form */}
+              <div className="space-y-4">
+                <h2 className="text-xs font-mono uppercase tracking-widest text-stark-500">
+                  Gasless Payment
+                </h2>
+                <PaymentForm wallet={wallet} />
+              </div>
+            </div>
+            {/* Guides / code snippets */}
+            <div className="rounded-2xl border border-stark-800 bg-stark-950/60 p-6 space-y-4">
+              <h2 className="text-sm font-mono uppercase tracking-widest text-stark-500">
+                What's included
+              </h2>
+              <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+                {[
+                  { icon: "🔑", title: "Wallet Connect", desc: "Argent X, Braavos, or Privy social login" },
+                  { icon: "⛽", title: "Gasless Transfers", desc: "AVNU paymaster sponsors user gas fees" },
+                  { icon: "💰", title: "Token Balances", desc: "STRK, ETH, USDC with live refresh" },
+                  { icon: "💸", title: "Payment UI", desc: "Ready-to-use send form with status flow" },
+                ].map((item) => (
+                  <div
+                    key={item.title}
+                    className="rounded-xl border border-stark-800 bg-stark-900/40 p-4"
+                  >
+                    <div className="text-2xl mb-2">{item.icon}</div>
+                    <p className="font-semibold text-stark-200 text-sm mb-1">{item.title}</p>
+                    <p className="text-xs text-stark-500 leading-relaxed">{item.desc}</p>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        )}
+      </main>
+      {/* ── Footer ─────────────────────────────────────────── */}
+      <footer className="border-t border-stark-900 py-6 text-center text-xs text-stark-700 font-mono">
+        Built with{" "}
+        <a
+          href="https://github.com/keep-starknet-strange/starkzap"
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-stark-500 hover:text-stark-300 transition-colors"
+        >
+          Starkzap SDK
+        </a>{" "}
+        · Deployed on Starknet {network}
+      </footer>
+    </div>
+  );
+}

package/src/components/payment/PaymentForm.tsx ADDED Viewed

@@ -0,0 +1,158 @@
+"use client";
+/**
+ * components/payment/PaymentForm.tsx
+ *
+ * A complete gasless payment form.
+ * Lets users send STRK / ETH / USDC to any Starknet address — no gas required.
+ */
+import { useState } from "react";
+import { useGaslessTransfer } from "@/hooks/useGaslessTransfer";
+import type { WalletState } from "@/hooks/useWallet";
+import { cn, explorerUrl } from "@/lib/utils";
+import { network } from "@/lib/starkzap";
+const TOKENS = ["STRK", "ETH", "USDC"] as const;
+type Props = {
+  wallet: WalletState["wallet"];
+  className?: string;
+};
+export function PaymentForm({ wallet, className }: Props) {
+  const [to, setTo] = useState("");
+  const [amount, setAmount] = useState("");
+  const [symbol, setSymbol] = useState<"STRK" | "ETH" | "USDC">("STRK");
+  const { send, txHash, isPending, isSuccess, error, reset } =
+    useGaslessTransfer(wallet);
+  const isValid =
+    to.startsWith("0x") && to.length >= 60 && Number(amount) > 0;
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!isValid) return;
+    await send({ to, amount, symbol });
+  };
+  if (isSuccess && txHash) {
+    return (
+      <div
+        className={cn(
+          "rounded-2xl border border-emerald-800 bg-emerald-950/40 p-6 text-center animate-fade-in",
+          className
+        )}
+      >
+        <div className="text-4xl mb-3">✓</div>
+        <p className="font-semibold text-emerald-300 mb-1">Payment sent!</p>
+        <p className="text-sm text-stark-400 mb-4">
+          {amount} {symbol} sent gaslessly
+        </p>
+        <a
+          href={explorerUrl(txHash, "tx", network)}
+          target="_blank"
+          rel="noopener noreferrer"
+          className="text-xs text-stark-400 underline hover:text-stark-200 font-mono"
+        >
+          View on Starkscan ↗
+        </a>
+        <button
+          onClick={reset}
+          className="mt-4 block w-full rounded-xl bg-stark-800 py-2 text-sm text-stark-300 hover:bg-stark-700 transition-colors"
+        >
+          Send another
+        </button>
+      </div>
+    );
+  }
+  return (
+    <form
+      onSubmit={handleSubmit}
+      className={cn(
+        "rounded-2xl border border-stark-800 bg-stark-950/60 p-5 backdrop-blur-sm space-y-4",
+        className
+      )}
+    >
+      <h3 className="text-sm font-mono uppercase tracking-widest text-stark-400">
+        Gasless Payment
+      </h3>
+      {/* Token selector */}
+      <div className="flex gap-2">
+        {TOKENS.map((t) => (
+          <button
+            key={t}
+            type="button"
+            onClick={() => setSymbol(t)}
+            className={cn(
+              "flex-1 rounded-xl py-2 text-sm font-semibold transition-all",
+              symbol === t
+                ? "bg-stark-500 text-white shadow"
+                : "bg-stark-900 text-stark-400 hover:bg-stark-800"
+            )}
+          >
+            {t}
+          </button>
+        ))}
+      </div>
+      {/* Amount input */}
+      <div>
+        <label className="mb-1.5 block text-xs text-stark-500">Amount</label>
+        <input
+          type="number"
+          min="0"
+          step="any"
+          placeholder="0.00"
+          value={amount}
+          onChange={(e) => setAmount(e.target.value)}
+          className="w-full rounded-xl bg-stark-900 border border-stark-800 px-4 py-2.5 font-mono text-lg text-white placeholder-stark-700 focus:border-stark-500 focus:outline-none transition-colors"
+        />
+      </div>
+      {/* Recipient address */}
+      <div>
+        <label className="mb-1.5 block text-xs text-stark-500">
+          Recipient Address
+        </label>
+        <input
+          type="text"
+          placeholder="0x..."
+          value={to}
+          onChange={(e) => setTo(e.target.value)}
+          className="w-full rounded-xl bg-stark-900 border border-stark-800 px-4 py-2.5 font-mono text-sm text-white placeholder-stark-700 focus:border-stark-500 focus:outline-none transition-colors"
+        />
+      </div>
+      {/* Error */}
+      {error && (
+        <p className="rounded-xl bg-red-950/60 border border-red-900 px-4 py-2 text-sm text-red-400">
+          {error}
+        </p>
+      )}
+      {/* Submit */}
+      <button
+        type="submit"
+        disabled={!isValid || isPending || !wallet}
+        className="w-full rounded-xl bg-stark-500 py-3 font-semibold text-white shadow-lg transition-all hover:bg-stark-400 active:scale-95 disabled:opacity-40 disabled:cursor-not-allowed"
+      >
+        {isPending ? (
+          <span className="flex items-center justify-center gap-2">
+            <span className="h-4 w-4 animate-spin rounded-full border-2 border-white border-t-transparent" />
+            Sending…
+          </span>
+        ) : (
+          `Send ${symbol} — No Gas Required`
+        )}
+      </button>
+      <p className="text-center text-xs text-stark-600">
+        Powered by AVNU Paymaster · Gas sponsored by this app
+      </p>
+    </form>
+  );
+}

package/src/components/wallet/TokenBalanceCard.tsx ADDED Viewed

@@ -0,0 +1,79 @@
+"use client";
+/**
+ * components/wallet/TokenBalanceCard.tsx
+ *
+ * Displays a single token balance with a refresh button.
+ * Supports STRK, ETH, and USDC out of the box.
+ */
+import { useTokenBalance, type TokenSymbol } from "@/hooks/useTokenBalance";
+import type { WalletState } from "@/hooks/useWallet";
+import { cn } from "@/lib/utils";
+const TOKEN_META: Record<TokenSymbol, { icon: string; color: string }> = {
+  STRK: { icon: "⚡", color: "text-stark-300" },
+  ETH:  { icon: "Ξ",  color: "text-indigo-300" },
+  USDC: { icon: "$",  color: "text-emerald-300" },
+};
+type Props = {
+  wallet: WalletState["wallet"];
+  symbol?: TokenSymbol;
+  className?: string;
+};
+export function TokenBalanceCard({ wallet, symbol = "STRK", className }: Props) {
+  const { formatted, isLoading, error, refetch } = useTokenBalance(wallet, symbol);
+  const meta = TOKEN_META[symbol];
+  return (
+    <div
+      className={cn(
+        "rounded-2xl border border-stark-800 bg-stark-950/60 p-5 backdrop-blur-sm",
+        className
+      )}
+    >
+      <div className="flex items-center justify-between mb-3">
+        <span className="text-xs font-mono uppercase tracking-widest text-stark-400">
+          {symbol} Balance
+        </span>
+        <button
+          onClick={refetch}
+          disabled={isLoading || !wallet}
+          className="rounded-full p-1.5 text-stark-500 hover:text-stark-200 hover:bg-stark-800 transition-colors disabled:opacity-40"
+          title="Refresh balance"
+        >
+          <svg
+            className={cn("h-3.5 w-3.5", isLoading && "animate-spin")}
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+            strokeWidth={2.5}
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15"
+            />
+          </svg>
+        </button>
+      </div>
+      {error ? (
+        <p className="text-sm text-red-400">{error}</p>
+      ) : (
+        <p className={cn("text-3xl font-mono font-bold", meta.color)}>
+          {isLoading || !wallet ? (
+            <span className="animate-pulse text-stark-700">——.————</span>
+          ) : (
+            <>
+              <span className="mr-1 text-xl opacity-70">{meta.icon}</span>
+              {formatted ?? "—"}
+            </>
+          )}
+        </p>
+      )}
+    </div>
+  );
+}

package/src/components/wallet/WalletButton.tsx ADDED Viewed

@@ -0,0 +1,59 @@
+"use client";
+/**
+ * components/wallet/WalletButton.tsx
+ *
+ * Drop-in connect/disconnect button.
+ * Shows a truncated address when connected.
+ */
+import { cn, formatAddress } from "@/lib/utils";
+import type { WalletState } from "@/hooks/useWallet";
+type Props = {
+  walletState: WalletState;
+  className?: string;
+};
+export function WalletButton({ walletState, className }: Props) {
+  const { address, isConnecting, connect, disconnect } = walletState;
+  if (address) {
+    return (
+      <button
+        onClick={disconnect}
+        className={cn(
+          "group flex items-center gap-2 rounded-full border border-stark-700 bg-stark-900 px-4 py-2 text-sm font-mono text-stark-200 transition-all hover:border-red-500 hover:text-red-400",
+          className
+        )}
+      >
+        {/* Green online dot */}
+        <span className="h-2 w-2 rounded-full bg-emerald-400 group-hover:bg-red-400 transition-colors" />
+        {formatAddress(address)}
+        <span className="opacity-0 group-hover:opacity-100 transition-opacity text-xs">
+          disconnect
+        </span>
+      </button>
+    );
+  }
+  return (
+    <button
+      onClick={connect}
+      disabled={isConnecting}
+      className={cn(
+        "flex items-center gap-2 rounded-full bg-stark-500 px-5 py-2 text-sm font-semibold text-white shadow-lg transition-all hover:bg-stark-400 active:scale-95 disabled:opacity-60 disabled:cursor-not-allowed",
+        className
+      )}
+    >
+      {isConnecting ? (
+        <>
+          <span className="h-3 w-3 animate-spin rounded-full border-2 border-white border-t-transparent" />
+          Connecting…
+        </>
+      ) : (
+        "Connect Wallet"
+      )}
+    </button>
+  );
+}

package/src/hooks/useGaslessTransfer.ts ADDED Viewed

@@ -0,0 +1,88 @@
+"use client";
+/**
+ * hooks/useGaslessTransfer.ts
+ *
+ * Sends ERC-20 tokens gaslessly using the AVNU paymaster.
+ * The user pays zero gas — your app (or the paymaster policy) covers it.
+ *
+ * Usage:
+ *   const { send, txHash, isPending, error } = useGaslessTransfer(wallet);
+ */
+import { useState, useCallback } from "react";
+import { getPresets, Amount } from "starkzap";
+import type { WalletState } from "./useWallet";
+export type TransferParams = {
+  to: string;       // Recipient Starknet address
+  amount: string;   // Human-readable amount, e.g. "1.5"
+  symbol: "STRK" | "ETH" | "USDC";
+};
+export type GaslessTransferState = {
+  send: (params: TransferParams) => Promise<void>;
+  txHash: string | null;
+  isPending: boolean;
+  isSuccess: boolean;
+  error: string | null;
+  reset: () => void;
+};
+export function useGaslessTransfer(
+  wallet: WalletState["wallet"]
+): GaslessTransferState {
+  const [txHash, setTxHash] = useState<string | null>(null);
+  const [isPending, setIsPending] = useState(false);
+  const [isSuccess, setIsSuccess] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const send = useCallback(
+    async ({ to, amount, symbol }: TransferParams) => {
+      if (!wallet) {
+        setError("Wallet not connected");
+        return;
+      }
+      setIsPending(true);
+      setError(null);
+      setIsSuccess(false);
+      setTxHash(null);
+      try {
+        const presets = getPresets(wallet.getChainId());
+        const token = presets[symbol as keyof typeof presets];
+        if (!token) throw new Error(`Token ${symbol} not available`);
+        const parsedAmount = Amount.parse(amount, token);
+        // feeMode: "sponsored" → AVNU paymaster covers gas (gasless for the user)
+        // feeMode: "default"   → user pays gas normally
+        const tx = await wallet.transfer(
+          { to, token, amount: parsedAmount },
+          { feeMode: "sponsored" }
+        );
+        setTxHash(tx.hash);
+        // Wait for onchain confirmation
+        await tx.wait();
+        setIsSuccess(true);
+      } catch (err) {
+        setError(err instanceof Error ? err.message : "Transaction failed");
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [wallet]
+  );
+  const reset = useCallback(() => {
+    setTxHash(null);
+    setIsPending(false);
+    setIsSuccess(false);
+    setError(null);
+  }, []);
+  return { send, txHash, isPending, isSuccess, error, reset };
+}

package/src/hooks/useTokenBalance.ts ADDED Viewed

@@ -0,0 +1,66 @@
+"use client";
+/**
+ * hooks/useTokenBalance.ts
+ *
+ * Fetches the balance of a given ERC-20 token for the connected wallet.
+ *
+ * Usage:
+ *   const { balance, formatted, isLoading, refetch } = useTokenBalance(wallet, token);
+ */
+import { useState, useEffect, useCallback } from "react";
+import { getPresets, Amount } from "starkzap";
+import type { WalletState } from "./useWallet";
+import { network } from "@/lib/starkzap";
+export type TokenSymbol = "STRK" | "ETH" | "USDC";
+export type TokenBalance = {
+  raw: bigint | null;
+  formatted: string | null;
+  symbol: TokenSymbol;
+  isLoading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+};
+export function useTokenBalance(
+  wallet: WalletState["wallet"],
+  symbol: TokenSymbol = "STRK"
+): TokenBalance {
+  const [raw, setRaw] = useState<bigint | null>(null);
+  const [formatted, setFormatted] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const fetchBalance = useCallback(async () => {
+    if (!wallet) return;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const presets = getPresets(wallet.getChainId());
+      const token = presets[symbol as keyof typeof presets];
+      if (!token) throw new Error(`Token ${symbol} not found for this network`);
+      const balanceRaw = await wallet.getBalance(token);
+      const amount = Amount.fromBase(balanceRaw, token);
+      setRaw(balanceRaw);
+      setFormatted(amount.toFixed(4));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch balance");
+    } finally {
+      setIsLoading(false);
+    }
+  }, [wallet, symbol]);
+  useEffect(() => {
+    fetchBalance();
+  }, [fetchBalance]);
+  return { raw, formatted, symbol, isLoading, error, refetch: fetchBalance };
+}