@miden-sdk/miden-sdk 0.13.0-next.1

package/README.md

@@ -0,0 +1,194 @@
+# @miden-sdk/miden-sdk
+
+## Overview
+
+The `@miden-sdk/miden-sdk` is a comprehensive software development toolkit (SDK) for interacting with the Miden blockchain and virtual machine from within a web application. It provides developers with everything needed to:
+
+- Interact with the Miden chain (e.g. syncing accounts, submitting transactions)
+- Create and manage Miden transactions
+- Run the Miden VM to execute programs
+- Generate zero-knowledge proofs using the Miden Prover (with support for delegated proving)
+- Integrate Miden capabilities seamlessly into browser-based environments
+
+Whether you're building a wallet, dApp, or other blockchain-integrated application, this SDK provides the core functionality to bridge your frontend with Miden's powerful ZK architecture.
+
+> **Note:** This README provides a high-level overview of the web client SDK.
+> For more detailed documentation, API references, and usage examples, see the documentation [here](../../docs/src/web-client) (TBD).
+
+### SDK Structure and Build Process
+
+This SDK is published as an NPM package, built from the `web-client` crate. The `web-client` crate is a Rust crate targeting WebAssembly (WASM), and it uses `wasm-bindgen` to generate JavaScript bindings. It depends on the lower-level `rust-client` crate, which implements the core functionality for interacting with the Miden chain.
+
+Both a `Cargo.toml` and a `package.json` are present in the `web-client` directory to support Rust compilation and NPM packaging respectively.
+
+The build process is powered by a custom `rollup.config.js` file, which orchestrates three main steps:
+
+1. **WASM Module Build**: Compiles the `web-client` Rust crate into a WASM module using `@wasm-tool/rollup-plugin-rust`, enabling WebAssembly features such as atomics and bulk memory operations.
+
+2. **Worker Build**: Bundles a dedicated web worker file that enables off-main-thread execution for computationally intensive functions.
+
+3. **Main Entry Point Build**: Bundles the top-level JavaScript module (`index.js`) which serves as the main API surface for consumers of the SDK. This module also imports `wasm.js`, which
+   provides a function to load the wasm module in an async way. Since there's a [known issue](https://github.com/wasm-tool/rollup-plugin-rust?tab=readme-ov-file#usage-with-vite)
+   with vite, there's a check to avoid loading the wasm module when SSR is enabled.
+
+This setup allows the SDK to be seamlessly consumed in JavaScript environments, particularly in web applications.
+
+## Installation
+
+### Stable Version
+
+A non-stable version of the SDK is also maintained, which tracks the `next` branch of the Miden client repository (essentially the development branch). To install the pre-release version, run:
+
+```javascript
+npm i @miden-sdk/miden-sdk
+```
+
+Or using Yarn:
+
+```javascript
+yarn add @miden-sdk/miden-sdk
+```
+
+### Pre-release ("next") Version
+
+A non-stable version is also maintained. To install the pre-release version, run:
+
+```javascript
+npm i @miden-sdk/miden-sdk@next
+```
+
+Or with Yarn:
+
+```javascript
+yarn add @miden-sdk/miden-sdk@next
+```
+
+> **Note:** The `next` version of the SDK must be used in conjunction with a locally running Miden node built from the `next` branch of the `miden-node` repository. This is necessary because the public testnet runs the stable `main` branch, which may not be compatible with the latest development features in `next`. Instructions to run a local node can be found [here](https://github.com/0xMiden/miden-node/tree/next) on the `next` branch of the `miden-node` repository. Additionally, if you plan to leverage delegated proving in your application, you may need to run a local prover (see [Remote prover instructions](https://github.com/0xMiden/miden-node/tree/next/bin/remote-prover)).
+
+## Building and Testing the Web Client
+
+If you're interested in contributing to the web client and need to build it locally, you can do so via:
+
+```
+yarn install
+yarn build
+```
+
+This will:
+
+- Install all JavaScript dependencies,
+- Compile the Rust code to WebAssembly,
+- Generate the JavaScript bindings via wasm-bindgen,
+- And bundle the SDK into the dist/ directory using Rollup.
+
+To run integration tests after building, use:
+
+```
+yarn test
+```
+
+This runs a suite of integration tests to verify the SDK’s functionality in a web context.
+
+### Building the npm package
+
+Follow the steps below to produce the contents that get published to npm (`dist/` plus the license file). All commands are executed from `crates/web-client`.
+
+1. **Install prerequisites**
+   - Install the Rust toolchain version specified in `rust-toolchain.toml`.
+   - Install Node.js ≥18 and Yarn.
+2. **Install dependencies**
+   ```bash
+   yarn install
+   ```
+   This installs both the JavaScript tooling and the `@wasm-tool/rollup-plugin-rust` dependency that compiles the Rust crate.
+3. **Build the package**
+   ```bash
+   yarn build
+   ```
+   The `build` script (see `package.json`) performs the following:
+   - Removes the previous `dist/` directory (`rimraf dist`).
+   - Runs `npm run build-rust-client-js`, which builds the `idxdb-store` TypeScript helper that the SDK imports.
+   - Invokes Rollup with `RUSTFLAGS="--cfg getrandom_backend=\"wasm_js\""` so the Rust `getrandom` crate targets browser entropy and so that atomics/bulk-memory WebAssembly features are enabled.
+   - Copies the generated TypeScript declarations from `js/types` into `dist/`.
+   - Executes `node clean.js` to strip paths from the generated `.js` files, leaving only the artifacts needed on npm.
+4. **Inspect the artifacts**
+   - `dist/index.js` is the ESM entry point referenced by `"main"`/`"browser"`/`"exports"`.
+   - `dist/index.d.ts` and the rest of the `.d.ts` files provide the TypeScript surface.
+   Use `npm pack` if you want to preview the exact tarball that would be published.
+
+> Tip: during development you can set `MIDEN_WEB_DEV=true` before running `yarn build` (or run `npm run build-dev`) to skip the clean step and keep extra debugging metadata in the bundled output. This debugging metadata also includes debug symbols for the generated wasm binary
+
+### Checking the generated TypeScript bindings
+
+The script at `crates/web-client/scripts/check-bindgen-types.js` verifies that every type exported by the generated wasm bindings (`dist/crates/miden_client_web.d.ts`) is re-exported from the public declarations (`js/types/index.d.ts`). Run it after a build with:
+
+```
+yarn check:wasm-types
+```
+
+`WebClient` is intentionally excluded because the wrapper defines its own implementation. If the check reports missing exports, update `js/types/index.d.ts` so consumers get the full generated surface.
+
+## Usage
+
+The following are just a few simple examples to get started. For more details, see the [API Reference](../../docs/typedoc/web-client/README.md).
+
+### Create a New Wallet
+
+```typescript
+import { AccountStorageMode, WebClient } from "@miden-sdk/miden-sdk";
+
+// Instantiate web client object
+const webClient = await WebClient.createClient();
+
+// Set up newWallet params
+const accountStorageMode = AccountStorageMode.private();
+const mutable = true;
+
+// Create new wallet
+const account = await webClient.newWallet(accountStorageMode, mutable);
+
+console.log(account.id().toString()); // account id as hex
+console.log(account.isPublic()); // false
+console.log(account.isPrivate()); // true
+console.log(account.isNetwork()); // false
+console.log(account.isFaucet()); // false
+```
+
+### Create and Execute a New Consume Transaction
+
+Using https://faucet.testnet.miden.io/, send some public test tokens using the account id logged during the new wallet creation. Consume these tokens like this:
+
+```typescript
+// Once the faucet finishes minting the tokens, you need to call syncState() so the client knows there is a note available to be consumed. In an actual application, this may need to be in a loop to constantly discover claimable notes.
+await webClient.syncState();
+
+// Query the client for consumable notes, and retrieve the id of the new note to be consumed
+let consumableNotes = await webClient.getConsumableNotes(account);
+const noteIdToConsume = consumableNotes[0].inputNoteRecord().id();
+
+// Create a consume transaction request object
+const consumeTransactionRequest = webClient.newConsumeTransactionRequest([
+  noteIdToConsume,
+]);
+
+// Execute, prove, submit, and apply the transaction in one step
+const transactionId = await webClient.submitNewTransaction(
+  account,
+  consumeTransactionRequest
+);
+
+// Need to sync state again (in a loop) until the node verifies the transaction
+await syncState();
+
+// Check new account balance
+const updatedAccount = await webClient.getAccount(account);
+const accountBalance = updatedAccount
+  .vault()
+  .getBalance(/* id of remote faucet */)
+  .toString();
+console.log(accountBalance);
+```
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.