create-nightkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# create-nightkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Start a Midnight app with [NightKit](https://nightkit.1am.xyz) in one command. By [1AM](https://1am.xyz), built by [Webisoft](https://webisoft.com).
+
+> **Beta.** Midnight testnets only (ledger 9 and later). It has had no outside security audit; do not put real funds behind it.
+
+```bash
+npm create nightkit@latest my-app
+cd my-app
+npm install
+npm run vault     # the vault, on http://localhost:5174 (leave it running)
+npm run dev       # your app, on http://localhost:5173
+```
+
+You get a Vite + React app with NightKit's connect button (1AM, MetaMask, Phantom, Coinbase Wallet and more) and RainbowKit for the Ethereum side.
+
+## Who makes this
+
+NightKit is made by [1AM](https://1am.xyz), the wallet for Midnight, and built by [Webisoft](https://webisoft.com).
+Site and docs: [nightkit.1am.xyz](https://nightkit.1am.xyz). Licence: Apache-2.0.

package/index.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// npm create nightkit@latest my-app
+//
+// Copies the NightKit starter (Vite + React, NightKit's connect button, and
+// RainbowKit for the Ethereum side) into a new folder as a standalone project.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const bundled = path.join(here, "template");
+const inRepo = path.join(here, "..", "..", "templates", "starter");
+const skip = (src) => !/(^|[\\/])(node_modules|dist|\.env)([\\/]|$)/.test(path.relative(inRepo, src)) || src === inRepo;
+
+// At publish time: put the starter inside this package.
+if (process.argv.includes("--bundle-template")) {
+  rmSync(bundled, { recursive: true, force: true });
+  cpSync(inRepo, bundled, { recursive: true, filter: skip });
+  console.log("template bundled");
+  process.exit(0);
+}
+
+const VERSION = JSON.parse(readFileSync(path.join(here, "package.json"), "utf8")).version;
+const args = process.argv.slice(2).filter((a) => !a.startsWith("-"));
+const name = args[0] ?? "my-midnight-app";
+if (!/^[a-z0-9][a-z0-9._-]*$/.test(path.basename(name))) {
+  console.error(`"${name}" is not a usable project name: lower-case letters, digits, dashes.`);
+  process.exit(1);
+}
+const target = path.resolve(name);
+if (existsSync(target) && readdirSync(target).length > 0) {
+  console.error(`${target} already exists and is not empty.`);
+  process.exit(1);
+}
+
+const source = existsSync(bundled) ? bundled : inRepo;
+mkdirSync(target, { recursive: true });
+cpSync(source, target, { recursive: true, filter: (src) => !/(^|[\\/])(node_modules|dist)([\\/]|$)/.test(path.relative(source, src)) });
+
+// A standalone project: real versions instead of workspace links, its own
+// TypeScript settings, and the vault as a dev dependency it can serve.
+const pkgPath = path.join(target, "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+pkg.name = path.basename(target);
+pkg.version = "0.1.0";
+for (const group of ["dependencies", "devDependencies"]) {
+  for (const [dep, range] of Object.entries(pkg[group] ?? {})) if (String(range).startsWith("workspace:")) pkg[group][dep] = `^${VERSION}`;
+}
+pkg.devDependencies["nightkit-vault"] = `^${VERSION}`;
+pkg.scripts.vault = "nightkit-vault --port 5174";
+writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+
+writeFileSync(
+  path.join(target, "tsconfig.json"),
+  `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2022",
+        lib: ["dom", "dom.iterable", "esnext"],
+        module: "esnext",
+        moduleResolution: "bundler",
+        allowImportingTsExtensions: true,
+        verbatimModuleSyntax: true,
+        strict: true,
+        skipLibCheck: true,
+        isolatedModules: true,
+        noEmit: true,
+        jsx: "react-jsx",
+        types: ["vite/client"],
+      },
+      include: ["src", "vite.config.ts"],
+    },
+    null,
+    2,
+  )}\n`,
+);
+if (existsSync(path.join(target, ".env.example"))) cpSync(path.join(target, ".env.example"), path.join(target, ".env"));
+writeFileSync(path.join(target, ".gitignore"), "node_modules/\ndist/\n.env\n.env.local\n");
+
+const rel = path.relative(process.cwd(), target) || ".";
+console.log(`
+  NightKit app created in ${rel}
+
+  Next:
+    cd ${rel}
+    npm install
+    npm run vault     # the vault, on http://localhost:5174 (leave it running)
+    npm run dev       # your app, on http://localhost:5173
+
+  Then press "Connect wallet". The vault must stay on a different
+  origin than your app: that separation is what keeps keys out of it.
+
+  Working with a coding agent? Point it at https://nightkit.1am.xyz/agent.md
+`);

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "create-nightkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Start a Midnight app with NightKit: `npm create nightkit@latest my-app`.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "create-nightkit": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "template",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://nightkit.1am.xyz",
+  "author": {
+    "name": "1AM",
+    "url": "https://1am.xyz"
+  },
+  "contributors": [
+    {
+      "name": "Webisoft",
+      "url": "https://webisoft.com"
+    }
+  ],
+  "keywords": [
+    "midnight",
+    "midnight-network",
+    "wallet",
+    "1am",
+    "nightkit",
+    "dapp-connector",
+    "web3",
+    "zero-knowledge"
+  ],
+  "scripts": {}
 }

package/template/.env.example

@@ -0,0 +1,7 @@
+# The Midnight network the app runs on. The vault must serve it too.
+VITE_NETWORK_ID=stagenet
+# Where the NightKit vault is served. It MUST be a different origin than the app:
+# in development the app is on :5173 and the vault on :5174.
+VITE_VAULT_URL=http://localhost:5174
+# Optional: a Reown (WalletConnect) project id, for mobile wallets on the Ethereum side.
+VITE_WALLETCONNECT_PROJECT_ID=

package/template/README.md

@@ -0,0 +1,42 @@
+# NightKit starter
+
+A Midnight dApp that connects **1AM**, or opens a Midnight account from
+**MetaMask, Coinbase Wallet, Phantom, Rabby** and other wallets, through
+NightKit. Vite + React, with RainbowKit for the Ethereum side.
+
+```bash
+cp .env.example .env     # network and vault URL
+pnpm dev                 # http://localhost:5173
+```
+
+The vault must be running on another origin (`pnpm vault` from the repo root
+serves it on http://localhost:5174).
+
+## Where things are
+
+- `src/main.tsx` — `NightKitProvider` with the network and vault URL. If an
+  Ethereum wallet is connected through RainbowKit, it is passed along so the
+  vault offers the same wallet first.
+- `src/App.tsx` — `ConnectButton`, and `useNightKit()` for the session.
+- `src/panels/` — three things every app does, written once for every wallet:
+  read balances, send tokens (`makeTransfer` + `submitTransaction`), sign a
+  message (`signData`).
+- `src/evm.tsx` — RainbowKit and wagmi, only for what your app does on Ethereum.
+
+## Adding a contract
+
+`session.api` is the DApp Connector API, so the usual midnight-js providers
+work unchanged: use `session.api.getProvingProvider`, `balanceUnsealedTransaction`
+and `submitTransaction` for your wallet and midnight providers, and
+`session.addresses.coinPublicKey` / `encryptionPublicKey` for the keys. Add
+`@midnightntwrk/ledger-v9` to your app's dependencies: proving a contract call
+needs it.
+
+For private state that should survive a new browser, derive its key from the
+account: `await session.vault?.appSecret("private-state")` returns 32 bytes
+only this account and your site can derive. (1AM has no equivalent; keep your
+existing fallback for it.)
+
+---
+
+NightKit is made by [1AM](https://1am.xyz), the wallet for Midnight, and built by [Webisoft](https://webisoft.com). Site: [nightkit.1am.xyz](https://nightkit.1am.xyz).

package/template/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>1AM NightKit starter</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "nightkit-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "A Midnight dApp starter: connect 1AM, or open a Midnight account from MetaMask, Coinbase, Phantom and friends, with NightKit.",
+  "scripts": {
+    "dev": "vite --port 5173 --strictPort",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview --port 5173 --strictPort",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "nightkit": "workspace:*",
+    "nightkit-react": "workspace:*",
+    "@rainbow-me/rainbowkit": "2.2.11",
+    "@tanstack/react-query": "5.100.0",
+    "react": "19.1.1",
+    "react-dom": "19.1.1",
+    "viem": "2.38.0",
+    "wagmi": "2.19.5"
+  },
+  "devDependencies": {
+    "@midnightntwrk/dapp-connector-api": "4.1.0-beta.1",
+    "@types/react": "19.1.12",
+    "@types/react-dom": "19.1.9",
+    "@vitejs/plugin-react": "5.0.4",
+    "typescript": "5.9.3",
+    "vite": "8.3.1"
+  }
+}

package/template/public/logo-1am-nightkit.svg

@@ -0,0 +1,8 @@
+<svg width="7994.1" height="1200" viewBox="0 0 7994.1 1200" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M1792.58 129.816V1052.53H1677.92V244.453H1516.13V129.816H1792.58Z" fill="white"/>
+<path d="M2442.88 129.816L2798.79 1052.53H2685.59L2602.06 835.553H2162.73L2079.21 1052.53H1965.99L2321.9 129.816H2442.88ZM2206.21 720.915H2557.88L2382.77 267.417L2206.21 720.915Z" fill="white"/>
+<path d="M3089.42 129.816L3454.69 852.165L3820.62 129.816H3951V1052.53H3837V371.571L3817.94 366.999L3468.9 1052.53H3441.15L3092.12 366.999L3073.05 371.571V1052.53H2958.4V129.816H3089.42Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M840.949 50.5786C1121.58 173.163 1267.77 491.622 1169.82 788.141C1065.91 1102.7 726.607 1273.47 411.979 1169.57C97.3508 1065.66 -73.4818 726.415 30.4242 411.858C128.279 115.619 434.916 -53.0965 733.097 15.0459L698.213 120.652C458.575 71.4357 214.031 208.779 135.488 446.555C50.8781 702.697 190.478 979.916 446.678 1064.53C702.877 1149.13 980.155 1009.55 1064.77 753.407C1143.4 515.352 1028.4 259.097 806.071 156.165L840.949 50.5786ZM753.58 135.436C771.671 141.41 789.181 148.346 806.071 156.165L635.934 671.226L528.107 635.616L698.213 120.652C716.724 124.454 735.206 129.368 753.58 135.436Z" fill="white"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M7994.1 1052H4470V130H7994.1V1052ZM4524 998H7940.1V184H4524V998Z" fill="white"/>
+<path d="M4769.8 805.2L4718 805.2L4718 380.4L4777.6 380.4L4913.6 647.2L4954.4 735.3L4955.7 735.3Q4954.4 703.5 4951.5 668.9Q4948.5 634.2 4948.5 600.6L4948.5 600.6L4948.5 380.4L5000.3 380.4L5000.3 805.2L4940.8 805.2L4804.8 538.4L4764.0 450.3L4762.7 450.3Q4764.0 482.7 4766.9 516.4Q4769.8 550.1 4769.8 583.1L4769.8 583.1L4769.8 805.2ZM5380.5 805.2L5115.0 805.2L5115.0 759.2L5220.5 759.2L5220.5 425.7L5115.0 425.7L5115.0 380.4L5380.5 380.4L5380.5 425.7L5274.9 425.7L5274.9 759.2L5380.5 759.2L5380.5 805.2ZM5660.2 813.0L5660.2 813.0Q5607.1 813.0 5565.4 786.7Q5523.6 760.5 5499.9 711.3Q5476.3 662.1 5476.3 592.8L5476.3 592.8Q5476.3 524.2 5500.6 474.9Q5524.9 425.7 5567.3 399.2Q5609.7 372.6 5664.8 372.6L5664.8 372.6Q5706.8 372.6 5735.3 389.1Q5763.8 405.6 5782.0 424.4L5782.0 424.4L5751.5 458.7Q5736.0 441.9 5715.6 430.9Q5695.2 419.9 5664.8 419.9L5664.8 419.9Q5625.3 419.9 5595.5 440.9Q5565.7 462.0 5549.2 500.2Q5532.7 538.4 5532.7 591.5L5532.7 591.5Q5532.7 671.8 5566.6 718.7Q5600.6 765.7 5663.5 765.7L5663.5 765.7Q5710.7 765.7 5737.3 740.4L5737.3 740.4L5737.3 629.7L5652.5 629.7L5652.5 585.0L5787.1 585.0L5787.1 763.8Q5767.1 783.8 5734.4 798.4Q5701.7 813.0 5660.2 813.0ZM5936.1 805.2L5881.7 805.2L5881.7 380.4L5936.1 380.4L5936.1 558.5L6113.5 558.5L6113.5 380.4L6167.9 380.4L6167.9 805.2L6113.5 805.2L6113.5 605.1L5936.1 605.1L5936.1 805.2ZM6440.6 805.2L6386.2 805.2L6386.2 425.7L6246.3 425.7L6246.3 380.4L6580.4 380.4L6580.4 425.7L6440.6 425.7L6440.6 805.2ZM6725.5 805.2L6671.1 805.2L6671.1 380.4L6725.5 380.4L6725.5 593.4L6727.4 593.4L6906.2 380.4L6967.7 380.4L6833.0 541.6L6983.2 805.2L6922.3 805.2L6798.7 582.4L6725.5 669.9L6725.5 805.2ZM7323.2 805.2L7057.7 805.2L7057.7 759.2L7163.2 759.2L7163.2 425.7L7057.7 425.7L7057.7 380.4L7323.2 380.4L7323.2 425.7L7217.6 425.7L7217.6 759.2L7323.2 759.2L7323.2 805.2ZM7606.2 805.2L7551.8 805.2L7551.8 425.7L7411.9 425.7L7411.9 380.4L7746.1 380.4L7746.1 425.7L7606.2 425.7L7606.2 805.2Z" fill="white"/>
+</svg>

package/template/src/App.tsx

@@ -0,0 +1,69 @@
+import { ConnectButton as EvmConnectButton } from "@rainbow-me/rainbowkit";
+import { ConnectButton, useNightKit } from "nightkit-react";
+
+import { Balances } from "./panels/Balances.tsx";
+import { Send } from "./panels/Send.tsx";
+import { SignMessage } from "./panels/SignMessage.tsx";
+
+export function App() {
+  const { session, sync, kit } = useNightKit();
+  return (
+    <>
+      <header className="top">
+        <span className="logo">
+          <span className="logo-1am" role="img" aria-label="1AM NightKit" /> <span className="product">Starter</span>
+        </span>
+        <span className="net">{kit.config.networkId}</span>
+        <span className="spacer" />
+        <EvmConnectButton showBalance={false} chainStatus="none" accountStatus="address" label="Ethereum wallet" />
+        <ConnectButton />
+      </header>
+
+      <main>
+        {!session ? (
+          <section className="hero">
+            <h1>One button. Any wallet. Midnight.</h1>
+            <p>
+              Connect 1AM, or open a Midnight account with the wallet you already have: MetaMask, Coinbase Wallet, Phantom, Rabby and more. Your Midnight keys stay
+              in a secure vault this page cannot read.
+            </p>
+            <ConnectButton label="Connect wallet" />
+          </section>
+        ) : (
+          <>
+            <section className="panel">
+              <h2>Account</h2>
+              <dl>
+                <dt>Wallet</dt>
+                <dd>{session.name}</dd>
+                <dt>Private address</dt>
+                <dd className="mono" data-testid="shielded-address">
+                  {session.addresses.shielded}
+                </dd>
+                <dt>Public address</dt>
+                <dd className="mono" data-testid="unshielded-address">
+                  {session.addresses.unshielded}
+                </dd>
+                {session.vault ? (
+                  <>
+                    <dt>Opened with</dt>
+                    <dd className="mono">
+                      {session.vault.signer.walletName} · {session.vault.signer.address}
+                    </dd>
+                    <dt>Network fees</dt>
+                    <dd>{session.vault.fees === "sponsor" ? "Paid for you" : "Paid from this account"}</dd>
+                    <dt>Sync</dt>
+                    <dd data-testid="sync">{sync?.synced ? "Up to date" : `Syncing${sync?.progress != null ? ` ${Math.floor(sync.progress * 100)}%` : "…"}`}</dd>
+                  </>
+                ) : null}
+              </dl>
+            </section>
+            <Balances />
+            <Send />
+            <SignMessage />
+          </>
+        )}
+      </main>
+    </>
+  );
+}

package/template/src/evm.tsx

@@ -0,0 +1,48 @@
+// The Ethereum side, with RainbowKit. It is here for whatever your app does on
+// Ethereum (a bridge, a token approval). NightKit does not need it: the vault
+// finds the user's wallet itself. When one is connected here, though, NightKit
+// is told which, so the vault offers the same wallet first.
+
+import "@rainbow-me/rainbowkit/styles.css";
+import { connectorsForWallets, darkTheme, lightTheme, RainbowKitProvider } from "@rainbow-me/rainbowkit";
+import { coinbaseWallet, injectedWallet, metaMaskWallet, phantomWallet, rabbyWallet, rainbowWallet, walletConnectWallet } from "@rainbow-me/rainbowkit/wallets";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { custom } from "viem";
+import { createConfig, WagmiProvider } from "wagmi";
+import { mainnet, sepolia } from "wagmi/chains";
+
+const projectId = import.meta.env.VITE_WALLETCONNECT_PROJECT_ID ?? "";
+
+// Coinbase's smart wallet signs with a passkey: nothing repeatable to open a
+// Midnight account from. Its ordinary (EOA) wallet works.
+coinbaseWallet.preference = "eoaOnly";
+
+const connectors = connectorsForWallets(
+  projectId
+    ? [{ groupName: "Popular", wallets: [metaMaskWallet, coinbaseWallet, phantomWallet, rabbyWallet, rainbowWallet, walletConnectWallet] }]
+    : // Without a project id: the extensions in this browser (they announce themselves) and Coinbase Wallet.
+      [{ groupName: "Ethereum wallets", wallets: [injectedWallet, coinbaseWallet] }],
+  { appName: "NightKit starter", projectId: projectId || "unused" },
+);
+
+// No RPC of wagmi's own: a default public node would see every visitor's address (and
+// refuses browser calls anyway). Read Ethereum through the connected wallet, or name your own RPC here.
+const noRpc = custom({
+  request: async () => {
+    throw new Error("no RPC configured: Ethereum is read through the connected wallet");
+  },
+});
+const config = createConfig({ chains: [mainnet, sepolia], connectors, transports: { [mainnet.id]: noRpc, [sepolia.id]: noRpc } });
+const queryClient = new QueryClient();
+
+export function EvmProviders({ children }: { children: ReactNode }) {
+  return (
+    <WagmiProvider config={config}>
+      <QueryClientProvider client={queryClient}>
+        {/* Square and 1AM blue, to sit beside NightKit's button. */}
+        <RainbowKitProvider theme={{ lightMode: lightTheme({ borderRadius: "none", accentColor: "#0064d6" }), darkMode: darkTheme({ borderRadius: "none", accentColor: "#0064d6" }) }}>{children}</RainbowKitProvider>
+      </QueryClientProvider>
+    </WagmiProvider>
+  );
+}

package/template/src/main.tsx

@@ -0,0 +1,32 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { NightKitProvider } from "nightkit-react";
+import { useAccount } from "wagmi";
+
+import { App } from "./App.tsx";
+import { EvmProviders } from "./evm.tsx";
+import "./styles.css";
+
+const config = {
+  networkId: import.meta.env.VITE_NETWORK_ID ?? "stagenet",
+  vaultUrl: import.meta.env.VITE_VAULT_URL ?? "http://localhost:5174",
+  appName: "NightKit starter",
+};
+
+function Root() {
+  // If an Ethereum wallet is connected through RainbowKit, tell the vault which.
+  const { address, connector } = useAccount();
+  return (
+    <NightKitProvider config={config} evm={address ? { account: address, walletRdns: connector?.id } : undefined}>
+      <App />
+    </NightKitProvider>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <EvmProviders>
+      <Root />
+    </EvmProviders>
+  </StrictMode>,
+);

package/template/src/panels/Balances.tsx

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState } from "react";
+import { useNightKit } from "nightkit-react";
+
+const NIGHT = "0".repeat(64);
+const name = (type: string) => (type === NIGHT ? "NIGHT" : `${type.slice(0, 8)}…`);
+
+interface Loaded {
+  shielded: Record<string, bigint>;
+  unshielded: Record<string, bigint>;
+  dust: bigint;
+}
+
+export function Balances() {
+  const { session, sync } = useNightKit();
+  const [data, setData] = useState<Loaded | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  // The same three calls for every wallet: this is the DApp Connector API.
+  const load = useCallback(async () => {
+    if (!session) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const [shielded, unshielded, dust] = await Promise.all([session.api.getShieldedBalances(), session.api.getUnshieldedBalances(), session.api.getDustBalance()]);
+      setData({ shielded, unshielded, dust: dust.balance });
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  }, [session]);
+
+  // A vault account answers once it has synced; 1AM answers at once.
+  const ready = !session?.vault || sync?.synced === true;
+  useEffect(() => {
+    if (ready) void load();
+  }, [ready, load]);
+
+  const rows = data ? [...Object.entries(data.shielded).map(([t, v]) => ["Private", t, v] as const), ...Object.entries(data.unshielded).map(([t, v]) => ["Public", t, v] as const)] : [];
+
+  return (
+    <section className="panel">
+      <h2>
+        Balances
+        <button className="link" type="button" onClick={() => void load()} disabled={busy || !ready}>
+          {busy ? "Loading…" : "Refresh"}
+        </button>
+      </h2>
+      {!ready ? <p className="dim">Your account is syncing. Balances appear when it is done.</p> : null}
+      {error ? <p className="err">{error}</p> : null}
+      {data ? (
+        <table data-testid="balances">
+          <tbody>
+            {rows.length === 0 ? (
+              <tr>
+                <td className="dim">No tokens yet.</td>
+              </tr>
+            ) : (
+              rows.map(([kind, type, value]) => (
+                <tr key={`${kind}${type}`}>
+                  <td>{name(type)}</td>
+                  <td className="dim">{kind}</td>
+                  <td className="mono num">{value.toString()}</td>
+                </tr>
+              ))
+            )}
+            <tr>
+              <td>Fee balance (DUST)</td>
+              <td />
+              <td className="mono num">{data.dust.toString()}</td>
+            </tr>
+          </tbody>
+        </table>
+      ) : null}
+    </section>
+  );
+}

package/template/src/panels/Send.tsx

@@ -0,0 +1,48 @@
+import { useState } from "react";
+import { isUserRejection } from "nightkit";
+import { useNightKit } from "nightkit-react";
+
+const NIGHT = "0".repeat(64);
+
+export function Send() {
+  const { session } = useNightKit();
+  const [recipient, setRecipient] = useState("");
+  const [amount, setAmount] = useState("");
+  const [status, setStatus] = useState<{ kind: "idle" | "busy" | "done" | "error"; text?: string }>({ kind: "idle" });
+  if (!session) return null;
+
+  const send = async () => {
+    setStatus({ kind: "busy", text: "Approve in your wallet…" });
+    try {
+      const kind = recipient.startsWith("mn_shield-addr") ? "shielded" : "unshielded";
+      // makeTransfer builds, balances and signs; submitTransaction sends it. The
+      // wallet shows the user what they are approving: 1AM in its popup, a
+      // NightKit account in the vault.
+      const { tx } = await session.api.makeTransfer([{ kind, type: NIGHT, value: BigInt(amount), recipient: recipient.trim() }]);
+      setStatus({ kind: "busy", text: "Sending…" });
+      await session.api.submitTransaction(tx);
+      setStatus({ kind: "done", text: "Sent." });
+    } catch (e) {
+      setStatus(isUserRejection(e) ? { kind: "idle" } : { kind: "error", text: e instanceof Error ? e.message : String(e) });
+    }
+  };
+
+  return (
+    <section className="panel">
+      <h2>Send NIGHT</h2>
+      <label>
+        To
+        <input value={recipient} onChange={(e) => setRecipient(e.target.value)} placeholder="mn_addr… or mn_shield-addr…" spellCheck={false} data-testid="send-to" />
+      </label>
+      <label>
+        Amount (smallest units)
+        <input value={amount} onChange={(e) => setAmount(e.target.value.replace(/\D/g, ""))} inputMode="numeric" placeholder="1000000" data-testid="send-amount" />
+      </label>
+      <button className="cta" type="button" disabled={!recipient || !amount || status.kind === "busy"} onClick={() => void send()} data-testid="send">
+        {status.kind === "busy" ? status.text : "Send"}
+      </button>
+      {status.kind === "done" ? <p className="ok">{status.text}</p> : null}
+      {status.kind === "error" ? <p className="err">{status.text}</p> : null}
+    </section>
+  );
+}

package/template/src/panels/SignMessage.tsx

@@ -0,0 +1,41 @@
+import { useState } from "react";
+import { isUserRejection } from "nightkit";
+import { useNightKit } from "nightkit-react";
+
+export function SignMessage() {
+  const { session } = useNightKit();
+  const [message, setMessage] = useState("Hello from Midnight");
+  const [result, setResult] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  if (!session) return null;
+
+  const sign = async () => {
+    setError(null);
+    setResult(null);
+    try {
+      const s = await session.api.signData(message, { encoding: "text", keyType: "unshielded" });
+      setResult(s.signature);
+    } catch (e) {
+      if (!isUserRejection(e)) setError(e instanceof Error ? e.message : String(e));
+    }
+  };
+
+  return (
+    <section className="panel">
+      <h2>Sign a message</h2>
+      <label>
+        Message
+        <input value={message} onChange={(e) => setMessage(e.target.value)} data-testid="sign-message" />
+      </label>
+      <button className="cta" type="button" disabled={!message} onClick={() => void sign()} data-testid="sign">
+        Sign
+      </button>
+      {result ? (
+        <p className="mono wrap" data-testid="signature">
+          {result}
+        </p>
+      ) : null}
+      {error ? <p className="err">{error}</p> : null}
+    </section>
+  );
+}

package/template/src/styles.css

@@ -0,0 +1,35 @@
+:root { --bg: #0c0e12; --surface: #13161b; --panel: #22262f; --border: #373a41; --text: #f7f7f7; --dim: #cecfd2; --faint: #94979c; --accent: #0064d6; --accent-hi: #459dff; --danger: #f97066; --live: #47cd89; --cta: #f7f7f7; --cta-ink: #0c0e12; color-scheme: dark; }
+@media (prefers-color-scheme: light) { :root { --bg: #f5f5f5; --surface: #fff; --panel: #fafafa; --border: #e9eaeb; --text: #181d27; --dim: #414651; --faint: #535862; --accent-hi: #0064d6; --danger: #b42318; --live: #079455; --cta: #0a0d12; --cta-ink: #fff; color-scheme: light; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.5 "Outfit", ui-sans-serif, system-ui, sans-serif; -webkit-font-smoothing: antialiased; }
+.mono { font-family: "JetBrains Mono", ui-monospace, Menlo, monospace; font-size: 13px; }
+.top { display: flex; align-items: center; gap: 12px; padding: 12px 20px; background: var(--surface); border-bottom: 1px solid var(--border); flex-wrap: wrap; }
+.logo { display: flex; align-items: center; gap: 8px; font-weight: 600; }
+/* 1AM's logo, painted in the text colour so it reads in light and dark. */
+.logo-1am { width: 147px; height: 22px; background: currentColor; -webkit-mask: url(/logo-1am-nightkit.svg) center / contain no-repeat; mask: url(/logo-1am-nightkit.svg) center / contain no-repeat; }
+.product { padding-left: 10px; border-left: 1px solid var(--border); }
+.net { font: 500 11px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; color: var(--faint); border: 1px solid var(--border); padding: 5px 6px; }
+.spacer { flex: 1; }
+main { max-width: 760px; margin: 0 auto; padding: 28px 16px 64px; display: grid; gap: 16px; }
+.hero { padding: 48px 0; }
+.hero h1 { margin: 0 0 12px; font: 600 clamp(28px, 5vw, 40px)/1.1 inherit; letter-spacing: -.02em; }
+.hero p { margin: 0 0 24px; max-width: 56ch; color: var(--dim); }
+.panel { background: var(--surface); border: 1px solid var(--border); padding: 18px; }
+.panel h2 { display: flex; align-items: baseline; justify-content: space-between; margin: 0 0 14px; font: 500 11px/1 ui-monospace, monospace; text-transform: uppercase; letter-spacing: .08em; color: var(--faint); }
+dl { display: grid; grid-template-columns: 140px 1fr; gap: 8px 16px; margin: 0; }
+dt { color: var(--dim); }
+dd { margin: 0; overflow-wrap: anywhere; }
+table { width: 100%; border-collapse: collapse; }
+td { padding: 8px 0; border-top: 1px solid var(--border); }
+.num { text-align: right; }
+label { display: grid; gap: 6px; margin-bottom: 12px; color: var(--dim); font-size: 13px; }
+input { height: 42px; padding: 0 12px; background: var(--panel); border: 1px solid var(--border); color: var(--text); font: 14px ui-monospace, Menlo, monospace; border-radius: 0; }
+input:focus-visible, button:focus-visible { outline: 2px solid var(--accent-hi); outline-offset: 2px; }
+.cta { min-height: 42px; padding: 0 18px; border: 1px solid var(--cta); background: var(--cta); color: var(--cta-ink); font: 600 13px/1 inherit; letter-spacing: .06em; text-transform: uppercase; cursor: pointer; border-radius: 0; }
+.cta:disabled { opacity: .5; cursor: default; }
+.link { border: 0; background: none; color: var(--accent-hi); font: inherit; cursor: pointer; padding: 0; }
+.link:disabled { color: var(--faint); cursor: default; }
+.dim { color: var(--dim); }
+.ok { color: var(--live); margin: 12px 0 0; }
+.err { color: var(--danger); margin: 12px 0 0; overflow-wrap: anywhere; }
+.wrap { overflow-wrap: anywhere; margin: 12px 0 0; }

package/template/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "noEmit": true, "jsx": "react-jsx", "types": ["vite/client"] }, "include": ["src", "vite.config.ts"] }

package/template/vite.config.ts

@@ -0,0 +1,4 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({ plugins: [react()], build: { target: "esnext" } });