starkzap-starter 0.1.0

package/src/hooks/useWallet.ts

@@ -0,0 +1,88 @@
+"use client";
+
+/**
+ * hooks/useWallet.ts
+ *
+ * Manages Starkzap wallet connection lifecycle.
+ *
+ * Usage:
+ *   const { wallet, address, isConnecting, connect, disconnect } = useWallet();
+ */
+
+import { useState, useCallback, useRef } from "react";
+import { StarkSigner } from "starkzap";
+import { sdk } from "@/lib/starkzap";
+
+export type WalletState = {
+  wallet: Awaited<ReturnType<typeof sdk.connectWallet>> | null;
+  address: string | null;
+  isConnecting: boolean;
+  isReady: boolean;
+  error: string | null;
+  connect: () => Promise<void>;
+  disconnect: () => void;
+};
+
+/**
+ * Connect via a browser-injected wallet (Argent X, Braavos).
+ * For social/email login, swap StarkSigner for PrivySigner — see README.
+ */
+export function useWallet(): WalletState {
+  const [wallet, setWallet] = useState<WalletState["wallet"]>(null);
+  const [address, setAddress] = useState<string | null>(null);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [isReady, setIsReady] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const walletRef = useRef<WalletState["wallet"]>(null);
+
+  const connect = useCallback(async () => {
+    setIsConnecting(true);
+    setError(null);
+
+    try {
+      // Detect injected Starknet wallet (Argent X / Braavos)
+      const starknetWindow = (window as unknown as { starknet?: { enable: () => Promise<string[]>; account: { address: string; privateKey?: string } } }).starknet;
+
+      if (!starknetWindow) {
+        throw new Error(
+          "No Starknet wallet detected. Please install Argent X or Braavos."
+        );
+      }
+
+      await starknetWindow.enable();
+      const userAddress = starknetWindow.account.address;
+
+      // Build a signer from the injected provider
+      // In production with Privy, replace with: new PrivySigner(privyClient)
+      const signer = new StarkSigner(
+        starknetWindow.account.privateKey ?? "0x0" // placeholder — injected wallets handle signing internally
+      );
+
+      const connectedWallet = await sdk.connectWallet({
+        account: { signer },
+      });
+
+      await connectedWallet.ensureReady({ deploy: "if_needed" });
+
+      walletRef.current = connectedWallet;
+      setWallet(connectedWallet);
+      setAddress(userAddress);
+      setIsReady(true);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Connection failed";
+      setError(message);
+    } finally {
+      setIsConnecting(false);
+    }
+  }, []);
+
+  const disconnect = useCallback(() => {
+    walletRef.current = null;
+    setWallet(null);
+    setAddress(null);
+    setIsReady(false);
+    setError(null);
+  }, []);
+
+  return { wallet, address, isConnecting, isReady, error, connect, disconnect };
+}

package/src/lib/starkzap.ts

@@ -0,0 +1,22 @@
+/**
+ * lib/starkzap.ts
+ *
+ * Central Starkzap SDK configuration.
+ * Import `sdk` anywhere you need to interact with Starknet.
+ */
+
+import { StarkZap } from "starkzap";
+
+const network =
+  (process.env.NEXT_PUBLIC_STARKNET_NETWORK as "mainnet" | "sepolia") ??
+  "sepolia";
+
+const rpcUrl = process.env.NEXT_PUBLIC_STARKNET_RPC_URL;
+
+export const sdk = new StarkZap({
+  network,
+  ...(rpcUrl ? { rpcUrl } : {}),
+});
+
+export type Network = typeof network;
+export { network };

package/src/lib/utils.ts

@@ -0,0 +1,54 @@
+/**
+ * lib/utils.ts — shared utility functions
+ */
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/** Merge Tailwind class names safely */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+/**
+ * Truncate a Starknet address for display.
+ * e.g. 0x049d...a3f2
+ */
+export function formatAddress(address: string, chars = 4): string {
+  if (!address) return "";
+  const clean = address.startsWith("0x") ? address : `0x${address}`;
+  return `${clean.slice(0, chars + 2)}...${clean.slice(-chars)}`;
+}
+
+/**
+ * Format a raw token amount (bigint) to a human-readable string.
+ * @param raw  - Raw base units (e.g. 1_000_000_000_000_000_000n for 1 ETH)
+ * @param decimals - Token decimals (default 18)
+ * @param precision - Display decimal places (default 4)
+ */
+export function formatAmount(
+  raw: bigint,
+  decimals = 18,
+  precision = 4
+): string {
+  const divisor = 10n ** BigInt(decimals);
+  const whole = raw / divisor;
+  const fraction = raw % divisor;
+  const fractionStr = fraction
+    .toString()
+    .padStart(decimals, "0")
+    .slice(0, precision);
+  return `${whole}.${fractionStr}`;
+}
+
+/** Return the Starknet explorer URL for an address or tx hash */
+export function explorerUrl(
+  value: string,
+  type: "address" | "tx" = "address",
+  network: "mainnet" | "sepolia" = "sepolia"
+): string {
+  const base =
+    network === "mainnet"
+      ? "https://starkscan.co"
+      : "https://sepolia.starkscan.co";
+  return `${base}/${type}/${value}`;
+}

package/tailwind.config.js

@@ -0,0 +1,43 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
+    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
+    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        stark: {
+          50:  "#f0f4ff",
+          100: "#dce6ff",
+          200: "#b9cdff",
+          300: "#86a8ff",
+          400: "#4d78ff",
+          500: "#1a47fb",
+          600: "#0c2ef0",
+          700: "#0920d4",
+          800: "#0d1dac",
+          900: "#111d87",
+          950: "#0a1152",
+        },
+        accent: "#ff6b35",
+      },
+      fontFamily: {
+        mono: ["'IBM Plex Mono'", "monospace"],
+        sans: ["'DM Sans'", "sans-serif"],
+      },
+      animation: {
+        "fade-in": "fadeIn 0.4s ease forwards",
+        pulse: "pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite",
+      },
+      keyframes: {
+        fadeIn: {
+          from: { opacity: "0", transform: "translateY(6px)" },
+          to:   { opacity: "1", transform: "translateY(0)" },
+        },
+      },
+    },
+  },
+  plugins: [],
+};

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}