@fedimint/core-web 0.0.0

package/README.md

@@ -0,0 +1,42 @@
+# Fedimint Client Typescript (Web)
+
+### THIS IS A WORK IN PROGRESS AND NOT READY FOR USE
+
+This package provides a typescript interface for the Fedimint client in the browser
+
+## Installation
+
+```sh
+npm install core-web
+# or
+yarn add core-web
+# or
+pnpm add core-web
+```
+
+## Usage
+
+```ts
+import { FedimintWallet } from 'core-web'
+
+// federation invite code
+const inviteCode = 'fed11qgqpw9thwvaz7t...'
+
+// This should be called only once
+await FedimintWallet.initFedimint()
+
+const wallet = await FedimintWallet.joinFederation(inviteCode)
+
+// Get Wallet Balance
+const balance = await wallet.getBalance()
+
+// Receive Ecash Payments
+await wallet.reissueNotes('A11qgqpw9thwvaz7t...')
+
+// Pay Lightning Invoice
+await wallet.payInvoice('lnbc...')
+```
+
+## Check out the example
+
+[`examples/vite-core`](../examples/vite-core/README.md)

package/dist/FedimintWallet.d.ts

@@ -0,0 +1,19 @@
+export declare class FedimintWallet {
+    private _fed;
+    private initPromise;
+    private openPromise;
+    private resolveOpen;
+    constructor(lazy?: boolean);
+    initialize(): Promise<void>;
+    open(clientName?: string): Promise<boolean>;
+    joinFederation(inviteCode: string, clientName?: string): Promise<void>;
+    private _rpcStream;
+    private _rpcSingle;
+    getBalance(): Promise<number>;
+    payInvoice(invoice: string): Promise<void>;
+    redeemEcash(notes: string): Promise<void>;
+    cleanup(): Promise<void>;
+    isOpen(): boolean;
+    subscribeBalance(callback: (balance: number) => void): () => void;
+}
+//# sourceMappingURL=FedimintWallet.d.ts.map

package/dist/FedimintWallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FedimintWallet.d.ts","sourceRoot":"","sources":["../src/FedimintWallet.ts"],"names":[],"mappings":"AAkBA,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,WAAW,CAAuB;gBAG9B,IAAI,GAAE,OAAe;IAS3B,UAAU;IASV,IAAI,CAAC,UAAU,GAAE,MAA4B;IAU7C,cAAc,CAClB,UAAU,EAAE,MAAM,EAClB,UAAU,GAAE,MAA4B;YAQ5B,UAAU;YAWV,UAAU;IAiBlB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAM7B,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB1C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzC,OAAO;IAIb,MAAM;IAMN,gBAAgB,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI;CAUrD"}

package/dist/FedimintWallet.js

@@ -0,0 +1,106 @@
+import init, { WasmClient } from '../wasm/fedimint_client_wasm.js';
+const DEFAULT_CLIENT_NAME = 'fm-default';
+export class FedimintWallet {
+    // private worker: Worker | null = null
+    constructor(lazy = false) {
+        this._fed = null;
+        this.initPromise = null;
+        this.openPromise = null;
+        this.resolveOpen = () => { };
+        if (lazy)
+            return;
+        this.initialize();
+        this.openPromise = new Promise((resolve) => {
+            this.resolveOpen = resolve;
+        });
+    }
+    // Setup
+    async initialize() {
+        if (this.initPromise)
+            return this.initPromise;
+        // this.worker = new Worker(new URL('./wasm.worker.ts', import.meta.url))
+        this.initPromise = init().then(() => {
+            console.trace('Fedimint Client Wasm Initialization complete');
+        });
+        return this.initPromise;
+    }
+    async open(clientName = DEFAULT_CLIENT_NAME) {
+        await this.initialize();
+        const wasm = await WasmClient.open(clientName);
+        if (wasm === undefined)
+            return false;
+        this._fed = wasm;
+        this.resolveOpen();
+        return true;
+    }
+    async joinFederation(inviteCode, clientName = DEFAULT_CLIENT_NAME) {
+        await this.initialize();
+        this._fed = await WasmClient.join_federation(clientName, inviteCode);
+        this.resolveOpen();
+    }
+    // RPC
+    async _rpcStream(module, method, body = {}, cb) {
+        await this.openPromise;
+        if (!this._fed)
+            throw new Error('FedimintWallet is not open');
+        await this._fed.rpc(module, method, JSON.stringify(body), cb);
+    }
+    async _rpcSingle(module, method, body = {}) {
+        // console.warn('RPC', module, method, body)
+        return new Promise((resolve, reject) => {
+            if (!this._fed)
+                return reject('FedimintWallet is not open');
+            this._fed.rpc(module, method, JSON.stringify(body), (res) => {
+                const parsed = JSON.parse(res);
+                if (parsed.error) {
+                    reject(parsed.error);
+                }
+                else {
+                    resolve(parsed);
+                }
+            });
+        });
+    }
+    // Client
+    async getBalance() {
+        return (await this._rpcSingle('', 'get_balance'));
+    }
+    // LN
+    async payInvoice(invoice) {
+        await this._rpcSingle('ln', 'pay_bolt11_invoice', {
+            invoice,
+        });
+    }
+    // async listGateways() {
+    //   return await this._rpcSingle("ln", "list_gateways");
+    // }
+    //
+    // async verifyGateways() {
+    //   return await this._rpcSingle("ln", "verify_gateway_availability");
+    // }
+    // Mint
+    async redeemEcash(notes) {
+        await this._rpcSingle('mint', 'reissue_external_notes', {
+            oob_notes: notes, // "out of band notes"
+            extra_meta: null,
+        });
+    }
+    // Teardown
+    async cleanup() {
+        await this._fed?.free();
+    }
+    isOpen() {
+        return this._fed !== null;
+    }
+    // Streaming
+    subscribeBalance(callback) {
+        this._rpcStream('', 'subscribe_balance_changes', {}, (res) => {
+            callback(res);
+        });
+        // TODO: implement unsubscribe on wasm side
+        return () => {
+            // no-op (fake unsubscribe)
+        };
+    }
+}
+//# sourceMappingURL=FedimintWallet.js.map

package/dist/FedimintWallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FedimintWallet.js","sourceRoot":"","sources":["../src/FedimintWallet.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { FedimintWallet } from './FedimintWallet.js';
+export { FedimintWallet };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+import { FedimintWallet } from './FedimintWallet.js';
+export { FedimintWallet };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/wasm.worker.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=wasm.worker.d.ts.map

package/dist/wasm.worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.worker.d.ts","sourceRoot":"","sources":["../src/wasm.worker.ts"],"names":[],"mappings":""}

package/dist/wasm.worker.js

@@ -0,0 +1,37 @@
+"use strict";
+// import init, { InitOutput, WasmClient } from '../wasm/fedimint_client_wasm.js'
+// let client: WasmClient | undefined
+// async function workerInit() {
+//   await init(new URL('@fedi/common/wasm/fedi_wasm_bg.wasm', import.meta.url))
+// }
+// const initPromise = workerInit().catch((error) =>
+//   postMessage({ error: String(error) }),
+// )
+// async function rpcRequest(method: string, data: string): Promise<string> {
+//   await initPromise
+//   return await fedimint_rpc(method, data)
+// }
+// const handleMessage = async (token: string, method: string, data: string) => {
+//   if (method === 'open') {
+//     await initPromise
+//     client = await WasmClient.open(data)
+//     if (client !== undefined) {
+//       postMessage({ token, result: true })
+//     } else {
+//       postMessage({ token, result: false })
+//     }
+//   } else if (method === 'join_federation') {
+//     await initPromise
+//     const result = await WasmClient.join_federation(data)
+//     postMessage({ token, result })
+//   }
+// }
+// // Handles worker.postMessage calls
+// addEventListener('message', (e) => {
+//   const { token, method, data } = e.data
+//   handleMessage(token, method, data)
+//   // rpcRequest(method, data)
+//   //   .then((result) => postMessage({ token, result }))
+//   //   .catch((error) => postMessage({ error: String(error) }))
+// })
+//# sourceMappingURL=wasm.worker.js.map

package/dist/wasm.worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.worker.js","sourceRoot":"","sources":["../src/wasm.worker.ts"],"names":[],"mappings":";AAAA,iFAAiF;AAEjF,qCAAqC;AAErC,gCAAgC;AAChC,gFAAgF;AAChF,IAAI;AAEJ,oDAAoD;AACpD,2CAA2C;AAC3C,IAAI;AAEJ,6EAA6E;AAC7E,sBAAsB;AACtB,4CAA4C;AAC5C,IAAI;AAEJ,iFAAiF;AACjF,6BAA6B;AAC7B,wBAAwB;AACxB,2CAA2C;AAC3C,kCAAkC;AAClC,6CAA6C;AAC7C,eAAe;AACf,8CAA8C;AAC9C,QAAQ;AACR,+CAA+C;AAC/C,wBAAwB;AACxB,4DAA4D;AAC5D,qCAAqC;AACrC,MAAM;AACN,IAAI;AAEJ,sCAAsC;AACtC,uCAAuC;AACvC,2CAA2C;AAC3C,uCAAuC;AACvC,gCAAgC;AAChC,2DAA2D;AAC3D,kEAAkE;AAClE,KAAK"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@fedimint/core-web",
+  "description": "Library for building web apps with a fedimint client",
+  "version": "0.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fedimint/fedimint-web-sdk.git",
+    "directory": "packages/core-web"
+  },
+  "files": [
+    "dist",
+    "wasm",
+    "src"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@types/node": "^20.14.8",
+    "typescript": "^5.2.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run clean && tsc --project tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "clean:deep": "pnpm run clean && rm -rf node_modules",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/FedimintWallet.ts

@@ -0,0 +1,142 @@
+import init, { WasmClient } from '../wasm/fedimint_client_wasm.js'
+
+type StreamError = {
+  error: string
+}
+
+// type StreamSuccess = {
+//   data: {} | [] | null | undefined | number | string | boolean
+// }
+
+type StreamSuccess = any & { error: never }
+
+type StreamResult = StreamSuccess | StreamError
+
+type Body = string | null | Record<string, string | null>
+
+const DEFAULT_CLIENT_NAME = 'fm-default' as const
+
+export class FedimintWallet {
+  private _fed: WasmClient | null = null
+  private initPromise: Promise<void> | null = null
+  private openPromise: Promise<void> | null = null
+  private resolveOpen: () => void = () => {}
+  // private worker: Worker | null = null
+
+  constructor(lazy: boolean = false) {
+    if (lazy) return
+    this.initialize()
+    this.openPromise = new Promise((resolve) => {
+      this.resolveOpen = resolve
+    })
+  }
+
+  // Setup
+  async initialize() {
+    if (this.initPromise) return this.initPromise
+    // this.worker = new Worker(new URL('./wasm.worker.ts', import.meta.url))
+    this.initPromise = init().then(() => {
+      console.trace('Fedimint Client Wasm Initialization complete')
+    })
+    return this.initPromise
+  }
+
+  async open(clientName: string = DEFAULT_CLIENT_NAME) {
+    await this.initialize()
+    const wasm = await WasmClient.open(clientName)
+
+    if (wasm === undefined) return false
+    this._fed = wasm
+    this.resolveOpen()
+    return true
+  }
+
+  async joinFederation(
+    inviteCode: string,
+    clientName: string = DEFAULT_CLIENT_NAME,
+  ) {
+    await this.initialize()
+    this._fed = await WasmClient.join_federation(clientName, inviteCode)
+    this.resolveOpen()
+  }
+
+  // RPC
+  private async _rpcStream(
+    module: string,
+    method: string,
+    body: Body = {},
+    cb: (res: string) => void,
+  ) {
+    await this.openPromise
+    if (!this._fed) throw new Error('FedimintWallet is not open')
+    await this._fed.rpc(module, method, JSON.stringify(body), cb)
+  }
+
+  private async _rpcSingle(module: string, method: string, body: Body = {}) {
+    // console.warn('RPC', module, method, body)
+    return new Promise((resolve, reject) => {
+      if (!this._fed) return reject('FedimintWallet is not open')
+      this._fed.rpc(module, method, JSON.stringify(body), (res: string) => {
+        const parsed = JSON.parse(res)
+        if (parsed.error) {
+          reject(parsed.error)
+        } else {
+          resolve(parsed)
+        }
+      })
+    })
+  }
+
+  // Client
+
+  async getBalance(): Promise<number> {
+    return (await this._rpcSingle('', 'get_balance')) as number
+  }
+
+  // LN
+
+  async payInvoice(invoice: string): Promise<void> {
+    await this._rpcSingle('ln', 'pay_bolt11_invoice', {
+      invoice,
+    })
+  }
+
+  // async listGateways() {
+  //   return await this._rpcSingle("ln", "list_gateways");
+  // }
+  //
+  // async verifyGateways() {
+  //   return await this._rpcSingle("ln", "verify_gateway_availability");
+  // }
+
+  // Mint
+
+  async redeemEcash(notes: string): Promise<void> {
+    await this._rpcSingle('mint', 'reissue_external_notes', {
+      oob_notes: notes, // "out of band notes"
+      extra_meta: null,
+    })
+  }
+
+  // Teardown
+  async cleanup() {
+    await this._fed?.free()
+  }
+
+  isOpen() {
+    return this._fed !== null
+  }
+
+  // Streaming
+
+  subscribeBalance(callback: (balance: number) => void) {
+    this._rpcStream('', 'subscribe_balance_changes', {}, (res: any) => {
+      callback(res)
+    })
+
+    // TODO: implement unsubscribe on wasm side
+    return () => {
+      // no-op (fake unsubscribe)
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { FedimintWallet } from './FedimintWallet.js'
+
+export { FedimintWallet }

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/wasm.worker.ts

@@ -0,0 +1,41 @@
+// import init, { InitOutput, WasmClient } from '../wasm/fedimint_client_wasm.js'
+
+// let client: WasmClient | undefined
+
+// async function workerInit() {
+//   await init(new URL('@fedi/common/wasm/fedi_wasm_bg.wasm', import.meta.url))
+// }
+
+// const initPromise = workerInit().catch((error) =>
+//   postMessage({ error: String(error) }),
+// )
+
+// async function rpcRequest(method: string, data: string): Promise<string> {
+//   await initPromise
+//   return await fedimint_rpc(method, data)
+// }
+
+// const handleMessage = async (token: string, method: string, data: string) => {
+//   if (method === 'open') {
+//     await initPromise
+//     client = await WasmClient.open(data)
+//     if (client !== undefined) {
+//       postMessage({ token, result: true })
+//     } else {
+//       postMessage({ token, result: false })
+//     }
+//   } else if (method === 'join_federation') {
+//     await initPromise
+//     const result = await WasmClient.join_federation(data)
+//     postMessage({ token, result })
+//   }
+// }
+
+// // Handles worker.postMessage calls
+// addEventListener('message', (e) => {
+//   const { token, method, data } = e.data
+//   handleMessage(token, method, data)
+//   // rpcRequest(method, data)
+//   //   .then((result) => postMessage({ token, result }))
+//   //   .catch((error) => postMessage({ error: String(error) }))
+// })

package/wasm/README.md

@@ -0,0 +1,169 @@
+<h1 align="center">
+  <a href="https://fedimint.org">
+    Fedimint
+  </a>
+</h1>
+
+<p align="center">
+    <img src="docs/banner.png">
+</p>
+
+<p align="center">
+  <a href="https://github.com/fedimint/fedimint/actions/workflows/ci-nix.yml">
+      <img src="https://github.com/fedimint/fedimint/actions/workflows/ci-nix.yml/badge.svg" alt="GitHub Actions CI Build Status">
+  </a>
+  <a href="https://chat.fedimint.org"><img alt="Developer Discord Chat" src="https://img.shields.io/discord/990354215060795454?label=dev%20chat"></a>
+  <a href="https://github.com/fedimint/fedimint/discussions">
+    <img src="https://img.shields.io/badge/community-discussion-blue" alt="GitHub Discussion">
+  </a>
+  <a href="https://docs.fedimint.org">
+    <img src="https://img.shields.io/static/v1?label=Docs&message=master&color=007ec6&logo=GitBook&logoColor=ffffff" alt="docs built from master">
+  </a>
+  <a href="https://app.radicle.xyz/nodes/radicle.fedimint.org/rad:z2eeB9LF8fDNJQaEcvAWxQmU7h2PG">
+    <img src="https://img.shields.io/badge/Radicle-explore-blue" alt="View on Radicle">
+  </a>
+  <img alt="Lines of code" src="https://tokei.rs/b1/github/fedimint/fedimint">
+</p>
+
+[Fedimint](https://fedimint.org) is a module based system for building federated applications. It is designed to be a
+trust-minimized, censorship-resistant, and private alternative to centralized applications.
+
+> **Fedimint is alpha software released under
+an [MIT License](https://github.com/fedimint/fedimint/blob/master/LICENSE). This means that the software here is
+provided "as is", without warranty of any kind. We are a small development team with limited resources. If you
+experience a loss of funds due to a bug in this software, we may not have the means to help you recover the funds. We
+recommend you run Fedimint on testnets like mutinynet, or on mainnet with small amounts of money. You can find our
+latest release [here](https://github.com/fedimint/fedimint/releases/latest).**
+
+Fedimint ships with 3 default
+modules - [Bitcoin](https://github.com/bitcoin/bitcoin), [Lightning](https://github.com/lightning/bolts),
+and [Chaumian Ecash](https://en.wikipedia.org/wiki/Ecash) - for out-of-the-box best practices for private and
+trust-minimized payments. [You can write custom modules](https://github.com/fedimint/fedimint-custom-modules-example)
+that define further consensus items and transaction types leveraging the payments modules to build your own federated
+applications.
+
+The Fedimint Developer Discord is the best place to get help and ask
+questions. [Join the Discord](https://discord.gg/cEVEmqCgWG) and say hi! We are extremely active and work to onboard
+developers of all skill levels to Fedimint and associated open-source Bitcoin projects. Fedimint touches many different
+areas of Bitcoin development, so there is something for everyone. See below for more information on how to get involved.
+
+## Running your own Fedimint
+
+It's easy to set up and run your own federations. Fedimint is designed to
+be [Byzantine Fault Tolerant](https://en.wikipedia.org/wiki/Byzantine_fault) so is resilient to `m` malicious nodes in a
+federation of `3m + 1` nodes. If you run a federation of 4 guardians you are resilient to 1 malicious guardian, if you
+run a federation of 7 guardians you are resilient to 2 guardians, etc.
+
+Fedimint can also be run in "solo mode" with a single guardian. This is useful for testing and development, but is not
+recommended for production use.
+
+To do lightning payments, Fedimint requires
+a [Lightning Gateway](https://github.com/fedimint/fedimint/blob/master/docs/gateway.md): a user of the federation that
+is willing to swap ecash in exchange for sending/receiving lightning payments. The Lightning Gateway is not a guardian
+and acts as an untrusted economic actor serving the federation.
+
+### Running Fedimint on Mutinynet
+
+See the [Fedimint Mutinynet Setup Guide](./docs/setup-docs.md). You can modify the configuration options to deploy it
+with.
+
+## For Developers
+
+We are actively looking for developers to help build Fedimint and associated open-source Bitcoin projects. Fedimint
+touches many different areas of Bitcoin development, so there is something for everyone. The best places to get started
+are:
+
+- [The Fedimint Developer Discord](https://discord.gg/cEVEmqCgWG): the best place to get help and ask questions.
+- [Fedimint Technical Reference Documentation](https://docs.fedimint.org)
+- [Fedimint Contributor Calendar](https://calendar.google.com/calendar/u/0/embed?src=fedimintcalendar@gmail.com): This
+  calendar contains all the developer calls and events.
+- [Fedimint Developer Calls](https://meet.jit.si/fedimintdevcall): We have developer calls every Monday at 4PM UTC to
+  review PRs and discuss current development priorities. As a new developer, this is a great place to find good first
+  issues and mentorship from the core team on how to get started contributing to Fedimint.
+- [PR Review Club](https://meet.jit.si/fedimintdevcall): We have PR review calls every Tuesday at 4PM UTC.
+- [Weekly Deep Dive](https://meet.jit.si/fedimintdevcall): We have a deep dive every Thursday at 4PM UTC to discuss
+  technical topics relating to Fedimint in depth: cryptography, Rust programming, consensus, networking, etc. This is a
+  great place to learn about the internals of Fedimint and Bitcoin. We normally plan these calls based off requests from
+  contributors on aspects of Fedimint they want to learn more about, so please reach out if you have a topic you want to
+  learn more about.
+
+For contribution guidelines, Areas of contributions and how to get involved, please refer to
+the [Contributing Guidelines](CONTRIBUTING.md).
+
+### Fedimint Repos and Projects to Contribute To
+
+- [Fedimint](https://github.com/fedimint/fedimint/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22): The
+  core Fedimint repository. This is where the core consensus and networking code lives. Fedimint is an advanced Rust
+  project and is a great place to learn Rust, cryptography, networking, consensus, and bitcoin development. We have a
+  lot of good first issues, are happy to mentor new developers, and are always looking for experienced Rust developers
+  to help with the core codebase.
+- [UI](https://github.com/fedimint/ui): The default Fedimint Guardian and Lightning Gateway UIs. These are Typescript
+  and React projects. Contributing to this repo helps with UI/UX design and development to make Fedimint more user
+  friendly.
+- [Lightning Gateway](https://github.com/fedimint/fedimint/issues?q=is%3Aissue+is%3Aopen+label%3Alightning): Fedimint's
+  Lightning Gateway is implemented as an HTLC interceptor and currently works with CLN, LND, and LDK's sample-node
+  implementations. We are always looking for lightning developers to help with the Lightning Gateway, especially around
+  improving payment reliability and to add support for more lightning implementations.
+- [Custom Modules](https://github.com/fedimint/fedimint-custom-modules-example): Fedimint ships with 3 default modules:
+  Bitcoin, Lightning, and Chaumian Ecash. You can write custom modules that define further consensus items and
+  transaction types leveraging the payments modules to build your own federated applications. We are always looking for
+  developers to help build custom modules and to help improve the module system.
+
+## Spinning up the Fedimint Developer Environment
+
+Fedimint is a Rust project and uses the [Nix package manager](https://nixos.org/) to manage dependencies and build the
+project.
+
+### Local Development
+
+We have a detailed tutorial on how to use the cli to send/receive ecash, lightning payments, and perform other developer
+operations in the [Fedimint Developer Tutorial](https://github.com/fedimint/fedimint/blob/master/docs/tutorial.md).
+
+Fedimint's developer environment and rust build pipeline is managed
+through [Nix Flakebox](https://github.com/rustshop/flakebox). To get started, install Nix.
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
+```
+
+Then fork and clone the Fedimint repo.
+
+```bash
+git clone https://github.com/your-username/fedimint.git
+```
+
+Then enter the nix developer environment.
+
+```bash
+nix develop
+```
+
+and use this command to start a local regtest network with 4 guardians, a bitcoin node, and a lightning gateway.
+
+```bash
+just mprocs
+```
+
+You can then interact with the guardians and lightning gateway using the cli. For more details on how to use the cli,
+see the [Fedimint Developer Tutorial](https://github.com/fedimint/fedimint/blob/master/docs/tutorial.md).
+
+If you want to run with UIs, see the [UI](https://github.com/fedimint/ui) repo for developer environment instructions.
+
+# Maintainers
+
+| Area              | Lead-Maintainer    | Co-Maintainers               | Status                                |
+|-------------------|--------------------|------------------------------|---------------------------------------|
+| Project Lead      | @elsirion          | @dpc @joschisan              | X                                     | 
+| Core Server       | @joschisan         | X                            | mostly well factored, no known issues | 
+| Core Consensus    | @joschisan         | @bradleystachurski           | polished and documented               | 
+| Lightning Module  | @joschisan         | @m1sterc001guy               | active development, known issues      |
+| Mint Module       | @joschisan         | X                            | active development, known issues      |
+| Wallet Module     | @bradleystachurski | @dpc @joschisan              | active development, critical issues   |
+| Core Client       | @dpc               | X                            | X                                     |
+| Lightning Gateway | @m1sterc001guy     | @joschisan                   | X                                     |
+| Database          | @m1sterc001guy     | X                            | X                                     |
+| Networking        | X                  | X                            | X                                     |
+| CI / Nix          | @dpc               | @maan2003 @bradleystachurski | X                                     |
+| Testing           | @bradleystachurski | X                            | X                                     |
+| Devimint          | @maan2003          | X                            | X                                     |
+| Config Generation | X                  | X                            | X                                     |