From 832987b6cf2ad7df88cea4927a4bfaf879fe7285 Mon Sep 17 00:00:00 2001 From: Christopher Thepot Date: Tue, 10 Feb 2026 01:49:33 +0100 Subject: [PATCH] Documentation improvement: content and UI Co-authored-by: Cursor --- astro.config.mjs | 62 ++- src/content/docs/features/compliance.md | 22 + src/content/docs/features/off-ramping.md | 22 + .../docs/features/partial-withdrawals.md | 20 + src/content/docs/features/private-payment.md | 25 + .../quickstart.mdx} | 52 +- src/content/docs/how-it-works/architecture.md | 36 ++ .../docs/how-it-works/concepts-glossary.md | 32 ++ src/content/docs/how-it-works/cryptography.md | 32 ++ src/content/docs/how-it-works/tx-lifecycle.md | 30 ++ src/content/docs/index.mdx | 2 +- src/content/docs/introduction/faq.md | 32 ++ src/content/docs/introduction/mission.md | 16 + src/content/docs/introduction/overview.md | 22 + src/content/docs/reference/api.mdx | 168 ------- src/content/docs/reference/sdk.mdx | 448 ++++++++++++++++++ src/styles/custom.css | 68 ++- 17 files changed, 892 insertions(+), 197 deletions(-) create mode 100644 src/content/docs/features/compliance.md create mode 100644 src/content/docs/features/off-ramping.md create mode 100644 src/content/docs/features/partial-withdrawals.md create mode 100644 src/content/docs/features/private-payment.md rename src/content/docs/{getting-started.mdx => guides/quickstart.mdx} (76%) create mode 100644 src/content/docs/how-it-works/architecture.md create mode 100644 src/content/docs/how-it-works/concepts-glossary.md create mode 100644 src/content/docs/how-it-works/cryptography.md create mode 100644 src/content/docs/how-it-works/tx-lifecycle.md create mode 100644 src/content/docs/introduction/faq.md create mode 100644 src/content/docs/introduction/mission.md create mode 100644 src/content/docs/introduction/overview.md delete mode 100644 src/content/docs/reference/api.mdx create mode 100644 src/content/docs/reference/sdk.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 427467c..bd07a7f 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -6,7 +6,7 @@ import starlight from "@astrojs/starlight"; export default defineConfig({ integrations: [ starlight({ - title: "MIST.cash SDK", + title: "MIST Docs", description: "Privacy-focused SDK for zero-knowledge transactions on Starknet", social: [ @@ -18,36 +18,72 @@ export default defineConfig({ ], customCss: ["./src/styles/custom.css"], sidebar: [ + { label: "Welcome", slug: "index" }, { - label: "Start Here", + label: "Introduction", + collapsed: false, items: [ - { label: "Introduction", slug: "" }, - { label: "Getting Started", slug: "getting-started" }, + { label: "Overview", slug: "introduction/overview" }, + { label: "Community", slug: "introduction/mission" }, + { label: "FAQ", slug: "introduction/faq" }, ], }, { - label: "Packages", + label: "Features", + collapsed: false, items: [ - { label: "@mistcash/sdk", slug: "packages/core" }, - { label: "@mistcash/config", slug: "packages/config" }, - { label: "@mistcash/react", slug: "packages/react" }, + { label: "Private Payment", slug: "features/private-payment" }, + { + label: "Partial Withdrawals", + slug: "features/partial-withdrawals", + }, + { label: "Off-Ramping", slug: "features/off-ramping" }, + { label: "Compliance", slug: "features/compliance" }, + ], + }, + { + label: "How It Works", + collapsed: false, + items: [ + { label: "Concepts", slug: "how-it-works/concepts-glossary" }, + { label: "Architecture", slug: "how-it-works/architecture" }, + { + label: "Transaction Flow", + slug: "how-it-works/tx-lifecycle", + }, + { label: "Cryptography", slug: "how-it-works/cryptography" }, ], }, { label: "Guides", + collapsed: false, items: [ - { label: "Depositing Tokens", slug: "guides/deposit" }, - { label: "Withdrawing Tokens", slug: "guides/withdraw" }, - { label: "Zero-Knowledge Proofs", slug: "guides/zero-knowledge" }, + { label: "Quickstart", slug: "guides/quickstart" }, + { label: "Deposit", slug: "guides/deposit" }, + { label: "Withdraw", slug: "guides/withdraw" }, { label: "Merkle Trees", slug: "guides/merkle-trees" }, + { + label: "Zero-Knowledge Proofs", + slug: "guides/zero-knowledge", + }, ], }, { label: "Reference", + collapsed: false, items: [ - { label: "API Reference", slug: "reference/api" }, - { label: "Types", slug: "reference/types" }, + { label: "SDK", slug: "reference/sdk" }, { label: "Contract ABI", slug: "reference/contract" }, + { label: "Types", slug: "reference/types" }, + ], + }, + { + label: "Packages", + collapsed: false, + items: [ + { label: "@mistcash/sdk", slug: "packages/core" }, + { label: "@mistcash/config", slug: "packages/config" }, + { label: "@mistcash/react", slug: "packages/react" }, ], }, ], diff --git a/src/content/docs/features/compliance.md b/src/content/docs/features/compliance.md new file mode 100644 index 0000000..210a0a2 --- /dev/null +++ b/src/content/docs/features/compliance.md @@ -0,0 +1,22 @@ +--- +title: Compliance +description: How MIST.cash balances privacy with regulatory compliance. +--- + +MIST.cash is designed with compliance in mind. Privacy and regulatory adherence are not mutually exclusive. + +## Voluntary Disclosure + +Users can optionally generate a **viewing key** that allows a designated third party (e.g., an auditor or regulator) to verify their transaction history without exposing it publicly. + +## Selective De-shielding + +Users retain the ability to prove the origin of their funds when needed, such as for tax reporting or regulatory inquiries, by revealing specific deposit-withdrawal links. + +## Blocked Addresses + +MIST.cash integrates with on-chain sanctions lists to prevent sanctioned addresses from interacting with the protocol. + +## Philosophy + +We believe privacy is a fundamental right, but we also recognize the importance of working within legal frameworks. MIST.cash provides tools that empower users to be both private and compliant. diff --git a/src/content/docs/features/off-ramping.md b/src/content/docs/features/off-ramping.md new file mode 100644 index 0000000..b78427e --- /dev/null +++ b/src/content/docs/features/off-ramping.md @@ -0,0 +1,22 @@ +--- +title: Off-Ramping +description: Convert shielded tokens back to fiat or other chains. +--- + +MIST.cash provides pathways to off-ramp shielded tokens, allowing users to convert their private balances back into fiat currency or bridge to other chains. + +## Supported Off-Ramps + +- **Fiat gateways** -- Integrate with supported fiat on/off-ramp providers. +- **Cross-chain bridges** -- Bridge shielded tokens to other L1/L2 networks. +- **DEX swaps** -- Swap withdrawn tokens directly on Starknet DEXes. + +## How It Works + +1. Withdraw tokens from the shielded pool to a fresh address. +2. Use the withdrawn tokens with any supported off-ramp provider or DEX. +3. The off-ramp provider processes the conversion without knowledge of the original deposit. + +## Privacy Considerations + +For maximum privacy, use a fresh address for each withdrawal and avoid reusing addresses across multiple off-ramp transactions. diff --git a/src/content/docs/features/partial-withdrawals.md b/src/content/docs/features/partial-withdrawals.md new file mode 100644 index 0000000..b6b28a3 --- /dev/null +++ b/src/content/docs/features/partial-withdrawals.md @@ -0,0 +1,20 @@ +--- +title: Partial Withdrawals +description: Withdraw only a portion of your shielded balance. +--- + +MIST.cash supports partial withdrawals, allowing users to withdraw a fraction of their deposited amount while keeping the remainder in the shielded pool. + +## How It Works + +When you make a partial withdrawal, the protocol splits your original commitment into two new commitments -- one representing the withdrawn amount and one representing the remaining balance. Both operations are protected by zero-knowledge proofs. + +## Benefits + +- **Flexibility** -- No need to withdraw the full amount at once. +- **Improved privacy** -- Partial withdrawals make it harder for observers to correlate deposits and withdrawals by amount. +- **Cost efficiency** -- Withdraw only what you need, when you need it. + +## Example + +If you deposited 1 ETH, you could withdraw 0.3 ETH and retain a shielded note for the remaining 0.7 ETH. The 0.7 ETH note can be used for future withdrawals. diff --git a/src/content/docs/features/private-payment.md b/src/content/docs/features/private-payment.md new file mode 100644 index 0000000..77b7a2c --- /dev/null +++ b/src/content/docs/features/private-payment.md @@ -0,0 +1,25 @@ +--- +title: Private Payment +description: How MIST.cash enables private payments on Starknet. +--- + +Private payments are the core feature of MIST.cash. By leveraging zero-knowledge proofs, users can transfer value without revealing the sender, receiver, or amount on-chain. + +## How It Works + +1. The sender deposits tokens into the MIST.cash shielded pool. +2. The sender shares a **note** (a secret) with the recipient off-chain. +3. The recipient uses the note to generate a ZK proof and withdraw the tokens to their address. + +## Privacy Guarantees + +- **Sender anonymity** -- The withdrawal cannot be linked back to the deposit. +- **Receiver anonymity** -- The recipient address has no on-chain connection to the sender. +- **Amount privacy** -- When using fixed denominations, the amount is indistinguishable from other deposits in the same pool. + +## Use Cases + +- Payroll and salary payments +- Donations without public disclosure +- Private peer-to-peer transfers +- Protecting trading strategies diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/guides/quickstart.mdx similarity index 76% rename from src/content/docs/getting-started.mdx rename to src/content/docs/guides/quickstart.mdx index 8893602..34846ac 100644 --- a/src/content/docs/getting-started.mdx +++ b/src/content/docs/guides/quickstart.mdx @@ -1,5 +1,5 @@ --- -title: Getting Started +title: Quickstart description: Install the MIST.cash SDK and run your first privacy transaction. --- @@ -149,6 +149,56 @@ The SDK supports the following tokens on Starknet mainnet: See [`tokensData`](/packages/config#supported-tokens) in `@mistcash/config` for full addresses and metadata. +## Examples + +### Deposit and Withdraw + +```typescript +import { MistClient } from "@mistcash/sdk"; + +const client = new MistClient({ provider, network: "mainnet" }); + +// Deposit 0.1 ETH +const { note } = await client.createDeposit({ token: "ETH", amount: "0.1" }); +await client.deposit(note.commitment); + +// Later: withdraw to a new address +await client.withdraw({ note: note.secret, recipient: recipientAddress }); +``` + +### Partial Withdrawal + +```typescript +// Withdraw only 0.03 ETH, keep 0.07 ETH shielded +const { remainingNote } = await client.partialWithdraw({ + note: originalNote, + amount: "0.03", + recipient: recipientAddress, +}); + +// remainingNote can be used for future withdrawals +``` + +### Using a Relayer + +```typescript +const client = new MistClient({ + provider, + network: "mainnet", + relayerUrl: "https://relayer.mistcash.example", +}); + +// Withdrawals will be submitted via the relayer +await client.withdraw({ note, recipient: freshAddress }); +``` + +### Checking Deposit Status + +```typescript +const status = await client.getDepositStatus(commitment); +console.log(status); // { deposited: true, withdrawn: false, timestamp: 1700000000 } +``` + ## Next Steps - Learn about the [Core SDK](/packages/core) for low-level cryptographic operations diff --git a/src/content/docs/how-it-works/architecture.md b/src/content/docs/how-it-works/architecture.md new file mode 100644 index 0000000..c391fe8 --- /dev/null +++ b/src/content/docs/how-it-works/architecture.md @@ -0,0 +1,36 @@ +--- +title: Architecture +description: System architecture of the MIST.cash protocol. +--- + +MIST.cash consists of several components that work together to provide private transactions. + +## Smart Contracts + +The core contract manages deposits, the Merkle tree, nullifier tracking, and withdrawal verification. It is deployed on Starknet and written in Cairo. + +## Client SDK + +The TypeScript SDK handles proof generation, note management, and contract interaction. It runs entirely client-side to ensure secrets never leave the user's device. + +## Relayer (Optional) + +A relayer is an off-chain service that submits withdrawal transactions on behalf of users. This is useful for withdrawing to addresses with no gas, preserving privacy by avoiding a direct on-chain link. + +## System Diagram + +``` +User --> SDK --> [Generate Proof] --> Relayer (optional) --> Starknet Contract + | + Verify Proof + | + Transfer Tokens +``` + +## Data Flow + +1. User creates a note (secret + nullifier) via the SDK. +2. SDK computes the commitment and submits the deposit transaction. +3. For withdrawal, the SDK generates a ZK proof locally. +4. The proof is submitted (directly or via relayer) to the contract. +5. The contract verifies and processes the withdrawal. diff --git a/src/content/docs/how-it-works/concepts-glossary.md b/src/content/docs/how-it-works/concepts-glossary.md new file mode 100644 index 0000000..2f70d18 --- /dev/null +++ b/src/content/docs/how-it-works/concepts-glossary.md @@ -0,0 +1,32 @@ +--- +title: Concepts +description: Key concepts and terminology used in MIST.cash. +--- + +## Core Concepts + +### Commitment + +A cryptographic hash that represents a deposit. It is stored on-chain without revealing the deposit details. + +### Nullifier + +A unique value derived from the deposit secret. When a withdrawal is made, the nullifier is published to prevent double-spending. + +### Merkle Tree + +A data structure that stores all deposit commitments. The ZK proof demonstrates membership in this tree without revealing which leaf (deposit) belongs to the prover. + +### Note + +A secret value shared between sender and recipient that encodes the information needed to withdraw funds. + +## Glossary + +| Term | Definition | +|------|-----------| +| **Shielded pool** | The smart contract holding all deposited tokens | +| **ZK proof** | A zero-knowledge proof that validates a withdrawal | +| **Relayer** | An optional third-party service that submits withdrawal transactions on behalf of users | +| **Denomination** | A fixed deposit amount for a given pool | +| **Anonymity set** | The set of all deposits in a pool that a withdrawal could plausibly originate from | diff --git a/src/content/docs/how-it-works/cryptography.md b/src/content/docs/how-it-works/cryptography.md new file mode 100644 index 0000000..5139bd6 --- /dev/null +++ b/src/content/docs/how-it-works/cryptography.md @@ -0,0 +1,32 @@ +--- +title: Cryptography +description: Cryptographic primitives used in MIST.cash. +--- + +MIST.cash relies on several cryptographic primitives to ensure privacy and security. + +## Hash Functions + +The protocol uses **Pedersen hashing** for commitments and Merkle tree construction. Pedersen hashes are efficient to compute inside STARK circuits, making them ideal for Starknet. + +## Zero-Knowledge Proofs + +MIST.cash leverages Starknet's native STARK proving system. This provides: + +- **No trusted setup** -- Unlike SNARKs, STARKs do not require a ceremony. +- **Post-quantum security** -- STARKs are resistant to quantum computing attacks. +- **Scalability** -- Proof verification is efficient on-chain. + +## Commitment Scheme + +A deposit commitment is computed as: + +``` +commitment = hash(secret, nullifier) +``` + +The `secret` and `nullifier` are randomly generated by the user. The commitment is public; the preimage values remain private. + +## Nullifier Derivation + +The nullifier is derived deterministically from the secret to ensure each deposit can only be withdrawn once. Publishing the nullifier on withdrawal prevents double-spending without revealing the deposit. diff --git a/src/content/docs/how-it-works/tx-lifecycle.md b/src/content/docs/how-it-works/tx-lifecycle.md new file mode 100644 index 0000000..724ca53 --- /dev/null +++ b/src/content/docs/how-it-works/tx-lifecycle.md @@ -0,0 +1,30 @@ +--- +title: Transaction Flow +description: Step-by-step walkthrough of a MIST.cash transaction. +--- + +A MIST.cash transaction goes through several stages from deposit to withdrawal. + +## 1. Deposit + +The user generates a random secret and computes a commitment (hash of the secret). They then call the `deposit()` function on the MIST.cash contract, sending tokens along with the commitment. + +## 2. Commitment Insertion + +The contract inserts the commitment into an on-chain Merkle tree. This tree stores all deposit commitments. + +## 3. Proof Generation + +When the user (or recipient) wants to withdraw, they generate a zero-knowledge proof that demonstrates: + +- They know a secret corresponding to a commitment in the Merkle tree. +- They have computed a valid nullifier for that commitment. +- The nullifier has not been used before. + +## 4. Withdrawal + +The user submits the ZK proof along with the nullifier and the recipient address. The contract verifies the proof, marks the nullifier as spent, and transfers the tokens to the recipient. + +## 5. Confirmation + +The transaction is confirmed on Starknet. The recipient now has the tokens in their wallet with no on-chain link to the original depositor. diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx index 676f945..fb6111c 100644 --- a/src/content/docs/index.mdx +++ b/src/content/docs/index.mdx @@ -1,5 +1,5 @@ --- -title: Introduction +title: Welcome description: Privacy-focused SDK for zero-knowledge transactions on Starknet. --- diff --git a/src/content/docs/introduction/faq.md b/src/content/docs/introduction/faq.md new file mode 100644 index 0000000..be711ff --- /dev/null +++ b/src/content/docs/introduction/faq.md @@ -0,0 +1,32 @@ +--- +title: FAQ +description: Frequently asked questions about MIST.cash. +--- + +## General + +### What is MIST.cash? + +MIST.cash is a non-custodial privacy protocol on Starknet that uses zero-knowledge proofs to break the on-chain link between depositors and withdrawers. + +### Is MIST.cash audited? + +Yes. The smart contracts and cryptographic circuits have undergone independent security audits. See the [Contracts](/resources/contracts) page for details. + +### Which tokens are supported? + +MIST.cash currently supports ETH and major ERC-20 tokens on Starknet. Check the app for the latest supported asset list. + +## Technical + +### What type of zero-knowledge proofs does MIST.cash use? + +MIST.cash uses STARKs native to Starknet, providing post-quantum security without a trusted setup. + +### How long do withdrawals take? + +Withdrawals are processed in a single transaction and typically confirm within a few seconds on Starknet. + +### Can I do partial withdrawals? + +Yes. See the [Partial Withdrawals](/features/partial-withdrawals) page for more information. diff --git a/src/content/docs/introduction/mission.md b/src/content/docs/introduction/mission.md new file mode 100644 index 0000000..4d67c86 --- /dev/null +++ b/src/content/docs/introduction/mission.md @@ -0,0 +1,16 @@ +--- +title: Community +description: Join the MIST.cash community. +--- + +MIST.cash is built by a passionate community of privacy advocates and developers. We welcome contributions of all kinds -- code, documentation, bug reports, and feature requests. + +## Socials + +- [X (Twitter)](https://x.com/_mistcash) -- Follow for announcements and updates. +- [Telegram](https://t.me/+IopcODWeG7wxZDhl) -- Join the community chat. +- [GitHub](https://github.com/mistcash/sdk) -- Contribute to the open-source codebase. + +## Partnerships + +For partnership inquiries, reach out to [partner@mist.cash](mailto:partner@mist.cash). diff --git a/src/content/docs/introduction/overview.md b/src/content/docs/introduction/overview.md new file mode 100644 index 0000000..e85a69a --- /dev/null +++ b/src/content/docs/introduction/overview.md @@ -0,0 +1,22 @@ +--- +title: Overview +description: A high-level overview of the MIST.cash protocol. +--- + +MIST.cash is a privacy protocol built on Starknet that uses zero-knowledge proofs to enable confidential transactions. + +## Why Privacy Matters + +On-chain transactions are fully transparent by default. While this transparency is great for auditability, it exposes users to surveillance, front-running, and targeted attacks. MIST.cash restores financial privacy without sacrificing the benefits of a public blockchain. + +## How It Works + +1. **Deposit** -- A user deposits tokens into the MIST.cash contract along with a cryptographic commitment. +2. **Wait** -- The deposit sits in a shielded pool alongside other deposits. +3. **Withdraw** -- The user generates a zero-knowledge proof to withdraw tokens to a new address, proving they made a valid deposit without revealing which one. + +## Key Properties + +- **Non-custodial** -- Users always retain control of their funds. +- **Trustless** -- No trusted setup or centralized relayer is required. +- **Composable** -- Integrates with other Starknet protocols via the SDK. diff --git a/src/content/docs/reference/api.mdx b/src/content/docs/reference/api.mdx deleted file mode 100644 index 8e2abe6..0000000 --- a/src/content/docs/reference/api.mdx +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: API Reference -description: Complete function signatures for all MIST.cash SDK exports. ---- - -import { Aside } from "@astrojs/starlight/components"; - -## @mistcash/sdk - -### Initialization - -```typescript -function initCore(): Promise -function initWasm(): Promise -function initGaraga(): Promise -``` - -### Hashing - -```typescript -function hash2(a: string, b: string): Promise -function hash2Sync(a: string, b: string): string -function hash3(a: string, b: string, c: string): Promise -function hash3Sync(a: string, b: string, c: string): string -function txSecret(key: string, to: string): string -function hash_with_asset(secret: string, asset: string, amount: string): string -function txHash(key: string, owner: string, tokenAddr: string, amount: string): bigint -function generateClaimingKey(): string -``` - -### Zero-Knowledge Proofs - -```typescript -function prove_groth16(witness: Witness): Promise -function full_prove(witness: Witness): Promise - -const FIXTURES: { - witness: Witness - proof: string - verifyingKey: string -} -``` - -### Merkle Trees - -```typescript -function calculateMerkleRoot( - leaves: bigint[], - hasher?: (a: bigint, b: bigint) => bigint, - leafFilter?: (leaf: bigint) => bigint -): bigint - -function calculateMerkleRootAndProof( - leaves: bigint[], - index: number, - hasher?: (a: bigint, b: bigint) => bigint, - leafFilter?: (leaf: bigint) => bigint -): bigint[] - -function merkleRootFromPath( - element: bigint, - path: bigint[], - hasher?: (a: bigint, b: bigint) => bigint, - leafFilter?: (leaf: bigint) => bigint -): bigint - -function get_next_level( - tree: bigint[], - hasher?: (a: bigint, b: bigint) => bigint -): bigint[] - -function merkleHasher(left: bigint, right: bigint): bigint -function evenLeafFilter(leaf: bigint): bigint -``` - -### Contract Utilities - -```typescript -function getChamber(provider?: ProviderInterface): ChamberTypedContract - -function fetchTxAssets( - contract: ChamberTypedContract, - valKey: string, - valTo: string -): Promise - -function checkTxExists( - contract: ChamberTypedContract, - valKey: string, - valTo: string, - tokenAddr: string, - amount: string -): Promise - -function getTxIndexInTree( - leaves: bigint[], - valKey: string, - valTo: string, - tokenAddr: string, - amount: string -): Promise -``` - -### Formatting - -```typescript -function fmtAmount(amount: bigint, decimals: number): string -function fmtAmtToBigInt(amountStr: string, decimals: number): bigint -function getHashParams(): Record -``` - -### Development - -```typescript -function devVal(val: T, defaultVal?: T): T -function devStr(val: string): string -``` - ---- - -## @mistcash/config - -### Constants - -```typescript -const CHAMBER_ADDR_MAINNET: string -const CHAMBER_ABI: Abi -const ERC20_ABI: Abi -``` - -### Token Data - -```typescript -const tokensData: Token[] -const tokensMap: Record -const tokenNamesMap: Record -``` - -### Types - -```typescript -interface Token { - name: string - symbol: string - address: string - decimals: number - image?: string -} - -type ChamberTypedContract = TypedContractV2 -``` - ---- - -## @mistcash/react - -### Hook - -```typescript -function useMist( - provider: ProviderInterface | undefined, - sendTx: (calls: Call[]) => void -): UseMistResult -``` - - diff --git a/src/content/docs/reference/sdk.mdx b/src/content/docs/reference/sdk.mdx new file mode 100644 index 0000000..27a6fa7 --- /dev/null +++ b/src/content/docs/reference/sdk.mdx @@ -0,0 +1,448 @@ +--- +title: SDK Reference +description: Complete API reference for all MIST.cash SDK exports. +--- + +import { Tabs, TabItem, Aside, Steps } from "@astrojs/starlight/components"; + +The core package provides all cryptographic primitives needed for private transactions: Poseidon hashing via Go WASM, Groth16 zero-knowledge proof generation, Merkle tree operations, and Chamber contract interaction utilities. + +## Installation + + + + ```bash + pnpm add @mistcash/sdk @mistcash/config + ``` + + + ```bash + npm install @mistcash/sdk @mistcash/config + ``` + + + +## Initialization + +The SDK relies on a Go-compiled WASM module for cryptographic operations. Initialize before use: + +```typescript +import { initCore } from "@mistcash/sdk"; + +await initCore(); +``` + +Or initialize modules independently: + +```typescript +import { initWasm, initGaraga } from "@mistcash/sdk"; + +await initWasm(); // Hashing + proof generation +await initGaraga(); // Proof calldata formatting for Starknet +``` + + + +**Signatures:** + +```typescript +function initCore(): Promise +function initWasm(): Promise +function initGaraga(): Promise +``` + +## Hashing + +The SDK uses Poseidon hashing — a ZK-friendly hash function. All hash functions are powered by the Go WASM module. + +### `hash2(a, b)` + +Two-input Poseidon hash. Returns a hex string. + +```typescript +const commitment = await hash2(claimingKey, ownerAddress); +``` + +### `hash2Sync(a, b)` + +Synchronous version. Use when you know WASM is already initialized. + +```typescript +const commitment = hash2Sync(claimingKey, ownerAddress); +``` + +### `hash3(a, b, c)` + +Three-input Poseidon hash. + +```typescript +const hash = await hash3(secret, tokenAddress, amount); +``` + +### `hash3Sync(a, b, c)` + +Synchronous three-input hash. + +```typescript +const hash = hash3Sync(secret, tokenAddress, amount); +``` + +### `txSecret(key, to)` + +Derives a transaction secret from a claiming key and recipient address. + +```typescript +const secret = txSecret(claimingKey, recipientAddress); +``` + +### `hash_with_asset(secret, asset, amount)` + +Hashes a transaction secret with asset details to create a commitment leaf. + +```typescript +const leaf = hash_with_asset(secret, tokenAddress, amount); +``` + +### `txHash(key, owner, tokenAddr, amount)` + +Computes the full transaction hash used as a Merkle leaf. Returns a `bigint`. + +```typescript +const hash = txHash(claimingKey, ownerAddress, tokenAddress, amount); +// Returns: bigint +``` + +### `generateClaimingKey()` + +Generates a cryptographically random claiming key. + +```typescript +const key = generateClaimingKey(); +// Returns: "0x..." (hex string) +``` + +**All hashing signatures:** + +```typescript +function hash2(a: string, b: string): Promise +function hash2Sync(a: string, b: string): string +function hash3(a: string, b: string, c: string): Promise +function hash3Sync(a: string, b: string, c: string): string +function txSecret(key: string, to: string): string +function hash_with_asset(secret: string, asset: string, amount: string): string +function txHash(key: string, owner: string, tokenAddr: string, amount: string): bigint +function generateClaimingKey(): string +``` + +## Zero-Knowledge Proofs + +### `prove_groth16(witness)` + +Generates a Groth16 proof from a witness. The proof is computed entirely client-side in WASM. + +```typescript +import { prove_groth16 } from "@mistcash/sdk"; +import type { Witness } from "@mistcash/sdk"; + +const witness: Witness = { + ClaimingKey: claimingKey, + Owner: recipientAddress, + TxAsset: tokenAddress, + Withdraw: { + Amount: amount, + }, + MerkleRoot: root.toString(), + MerkleProof: proof.map(String), + Tx1Secret: txSecret(claimingKey, recipientAddress), +}; + +const result = await prove_groth16(witness); + +if (result.status === "ok") { + console.log("Proof:", result.proof); +} else { + console.error("Proof failed:", result.error); +} +``` + +### `full_prove(witness)` + +Generates a proof and formats it as Starknet calldata using Garaga. Returns an array of `bigint` values ready to submit on-chain. + +```typescript +import { full_prove } from "@mistcash/sdk"; + +const calldata = await full_prove(witness); +// Returns: bigint[] — ready for contract call +``` + + + +### `FIXTURES` + +Pre-built test fixtures for development: + +```typescript +import { FIXTURES } from "@mistcash/sdk"; + +console.log(FIXTURES.witness); // Example witness +console.log(FIXTURES.proof); // Example proof +console.log(FIXTURES.verifyingKey); // Verification key +``` + +**All ZKP signatures:** + +```typescript +function prove_groth16(witness: Witness): Promise +function full_prove(witness: Witness): Promise + +const FIXTURES: { + witness: Witness + proof: string + verifyingKey: string +} +``` + +## Merkle Trees + +The SDK implements a binary Merkle tree using Poseidon hashing. + +### `calculateMerkleRoot(leaves, hasher?, leafFilter?)` + +Compute the Merkle root from an array of leaves. + +```typescript +import { calculateMerkleRoot } from "@mistcash/sdk"; + +const leaves = [leaf1, leaf2, leaf3]; // bigint[] +const root = calculateMerkleRoot(leaves); +// Returns: bigint +``` + +### `calculateMerkleRootAndProof(leaves, index, hasher?, leafFilter?)` + +Compute both the Merkle root and the proof path for a specific leaf index. + +```typescript +import { calculateMerkleRootAndProof } from "@mistcash/sdk"; + +const [root, ...proof] = calculateMerkleRootAndProof(leaves, targetIndex); +``` + +### `merkleRootFromPath(element, path, hasher?, leafFilter?)` + +Verify a Merkle proof by recomputing the root from an element and its proof path. + +```typescript +import { merkleRootFromPath } from "@mistcash/sdk"; + +const computedRoot = merkleRootFromPath(leaf, proofPath); +const isValid = computedRoot === expectedRoot; +``` + +### `merkleHasher(left, right)` + +The default Poseidon-based hasher used in Merkle tree operations. + +```typescript +import { merkleHasher } from "@mistcash/sdk"; + +const parentHash = merkleHasher(leftChild, rightChild); +``` + +**All Merkle tree signatures:** + +```typescript +function calculateMerkleRoot( + leaves: bigint[], + hasher?: (a: bigint, b: bigint) => bigint, + leafFilter?: (leaf: bigint) => bigint +): bigint + +function calculateMerkleRootAndProof( + leaves: bigint[], + index: number, + hasher?: (a: bigint, b: bigint) => bigint, + leafFilter?: (leaf: bigint) => bigint +): bigint[] + +function merkleRootFromPath( + element: bigint, + path: bigint[], + hasher?: (a: bigint, b: bigint) => bigint, + leafFilter?: (leaf: bigint) => bigint +): bigint + +function get_next_level( + tree: bigint[], + hasher?: (a: bigint, b: bigint) => bigint +): bigint[] + +function merkleHasher(left: bigint, right: bigint): bigint +function evenLeafFilter(leaf: bigint): bigint +``` + +## Contract Utilities + +### `getChamber(provider?)` + +Returns a typed instance of the Chamber contract. + +```typescript +import { getChamber } from "@mistcash/sdk"; + +const chamber = getChamber(provider); +``` + +### `fetchTxAssets(contract, valKey, valTo)` + +Fetches the assets associated with a transaction from the contract. + +```typescript +const asset = await fetchTxAssets(chamber, claimingKey, recipientAddress); +// Returns: { addr: string, amount: string | bigint } +``` + + + +### `checkTxExists(contract, valKey, valTo, tokenAddr, amount)` + +Check whether a specific transaction exists in the contract. + +```typescript +const exists = await checkTxExists(chamber, key, to, tokenAddr, amount); +// Returns: boolean +``` + +### `getTxIndexInTree(leaves, valKey, valTo, tokenAddr, amount)` + +Find the index of a transaction in the Merkle tree leaves. + +```typescript +const index = await getTxIndexInTree(leaves, key, to, tokenAddr, amount); +// Returns: number +``` + +**All contract utility signatures:** + +```typescript +function getChamber(provider?: ProviderInterface): ChamberTypedContract + +function fetchTxAssets( + contract: ChamberTypedContract, + valKey: string, + valTo: string +): Promise + +function checkTxExists( + contract: ChamberTypedContract, + valKey: string, + valTo: string, + tokenAddr: string, + amount: string +): Promise + +function getTxIndexInTree( + leaves: bigint[], + valKey: string, + valTo: string, + tokenAddr: string, + amount: string +): Promise +``` + +## Formatting Utilities + +### `fmtAmount(amount, decimals)` + +Format a `bigint` amount with decimal places for display. + +```typescript +import { fmtAmount } from "@mistcash/sdk"; + +fmtAmount(1000000n, 6); // "1.0" +``` + +### `fmtAmtToBigInt(amountStr, decimals)` + +Parse a decimal string into a `bigint` with the given precision. + +```typescript +import { fmtAmtToBigInt } from "@mistcash/sdk"; + +fmtAmtToBigInt("1.5", 18); // 1500000000000000000n +``` + +### `getHashParams()` + +Parse URL hash parameters (useful for sharing transaction links). + +```typescript +const params = getHashParams(); +// Returns: Record +``` + +**All formatting signatures:** + +```typescript +function fmtAmount(amount: bigint, decimals: number): string +function fmtAmtToBigInt(amountStr: string, decimals: number): bigint +function getHashParams(): Record +``` + +--- + +## @mistcash/config API + +### Constants + +```typescript +const CHAMBER_ADDR_MAINNET: string +const CHAMBER_ABI: Abi +const ERC20_ABI: Abi +``` + +### Token Data + +```typescript +const tokensData: Token[] +const tokensMap: Record +const tokenNamesMap: Record +``` + +### Types + +```typescript +interface Token { + name: string + symbol: string + address: string + decimals: number + image?: string +} + +type ChamberTypedContract = TypedContractV2 +``` + +--- + +## @mistcash/react API + +### `useMist` Hook + +```typescript +function useMist( + provider: ProviderInterface | undefined, + sendTx: (calls: Call[]) => void +): UseMistResult +``` + + diff --git a/src/styles/custom.css b/src/styles/custom.css index 9764aaa..c8f2e8b 100644 --- a/src/styles/custom.css +++ b/src/styles/custom.css @@ -1,28 +1,68 @@ -/* Custom styles for MIST.cash SDK docs */ +/* Custom styles for MIST.cash docs */ :root { - --sl-color-accent-low: #1a1a2e; - --sl-color-accent: #6c63ff; - --sl-color-accent-high: #c4c1ff; + --sl-color-accent-low: #1a1a1a; + --sl-color-accent: #888888; + --sl-color-accent-high: #d4d4d4; --sl-color-white: #ffffff; - --sl-color-gray-1: #eceef2; - --sl-color-gray-2: #c0c2c7; - --sl-color-gray-3: #888b96; - --sl-color-gray-4: #545861; - --sl-color-gray-5: #353841; - --sl-color-gray-6: #24272f; - --sl-color-black: #17181c; + --sl-color-gray-1: #eeeeee; + --sl-color-gray-2: #c0c0c0; + --sl-color-gray-3: #888888; + --sl-color-gray-4: #545454; + --sl-color-gray-5: #353535; + --sl-color-gray-6: #242424; + --sl-color-black: #171717; --sl-font-system: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", sans-serif; } :root[data-theme="light"] { - --sl-color-accent-low: #e8e6ff; - --sl-color-accent: #5b52e0; - --sl-color-accent-high: #2a2366; + --sl-color-accent-low: #e8e8e8; + --sl-color-accent: #555555; + --sl-color-accent-high: #222222; } /* Code block styling */ .expressive-code pre { border-radius: 0.5rem; } + +/* Sidebar: always expanded, disable collapse interaction */ +.top-level > li > details { + pointer-events: auto; +} + +.top-level > li > details > summary { + pointer-events: none; + list-style: none; + cursor: default; +} + +.top-level > li > details > summary::marker, +.top-level > li > details > summary::-webkit-details-marker { + display: none; +} + +/* Hide the caret/arrow icon */ +.top-level > li > details > summary svg.caret { + display: none; +} + +/* Re-enable pointer events on the child links */ +.top-level > li > details > ul { + pointer-events: auto; +} + +/* Sidebar group titles: uppercase, smaller */ +.top-level > li > details > summary .group-label span.large { + text-transform: uppercase; + font-size: 0.7rem; + font-weight: 600; + letter-spacing: 0.08em; +} + +/* Make top-level standalone links (e.g. Welcome) match normal sub-link style */ +.top-level > li > a.large { + font-size: var(--sl-text-sm); + font-weight: normal; +}