Command	Usage
`initwallet`	`initwallet \` - Creates a new wallet instance. If no mnemonic provided, generates one
`getbalance`	Gets the current wallet balance as well the token balance
`getsparkaddress`	Gets a new Spark Address for receiving transfers
`announcetoken`	`announcetoken \ \ \ \ \` - Mint a certain amount of tokens
`minttokens`	`minttokens \` - Mint a certain amount of tokens
`transfertokens`	`transfertokens \ \ \` - Sends tokens to the given receiver Spark Address using Bech32m token identifier (btkn1...)
`burntokens`	`burntokens \` - Burns the specified amount of tokens
`freezetokens`	`freezetokens \` - Freezes tokens at the Spark Address
`unfreezetokens`	`unfreezetokens \` - Unfreezes tokens at the Spark Address
`tokenactivity`	Gets the token activity for the issuer's token
`tokeninfo`	Gets the token info for the issuer's token
`help`	Shows the help menu
`exit`	Exits the CLI tool

## Demo application The fully built Demo Application is available [Here](https://github.com/buildonspark/spark/tree/develop/sdks/js/examples/spark-demo) ## Sample Express server project ### Clone the SDK repo ```bash theme={null} git clone https://github.com/buildonspark/spark.git ``` ### Navigate to project directory ```bash theme={null} cd spark/sdks/js/examples/spark-node-express/ ``` Follow the instructions in the README to install dependencies and run the server. # Analytics Source: https://docs.spark.money/issuance/token-analytics Query the full transaction history for your token. Filter by address, status, issuer key, or output ID to understand how your token moves through the network.

## Query Transactions Get all transactions for your token: ```typescript theme={null} const [tokenIdentifier] = await wallet.getIssuerTokenIdentifiers(); if (!tokenIdentifier) throw new Error("No token identifiers found for this issuer"); const response = await wallet.queryTokenTransactionsWithFilters({ tokenIdentifiers: [tokenIdentifier], pageSize: 50, direction: "NEXT", }); console.log("Total transactions in page:", response.tokenTransactionsWithStatus.length); ``` ## Filter by Address Get transactions for a specific Spark address: ```typescript theme={null} const response = await wallet.queryTokenTransactionsWithFilters({ sparkAddresses: ["spark1abc..."], pageSize: 50, }); ``` Filter constraints can be combined (AND semantics). For example, you can filter by both `tokenIdentifiers` and `sparkAddresses` in a single request. ## Transaction Status Each transaction has a status: | Status | Meaning | | :- | :- | | `TOKEN_TRANSACTION_STARTED` | Created, not yet signed | | `TOKEN_TRANSACTION_SIGNED` | Signed by all parties | | `TOKEN_TRANSACTION_REVEALED` | Reveal stage completed | | `TOKEN_TRANSACTION_FINALIZED` | Confirmed | | `TOKEN_TRANSACTION_STARTED_CANCELLED` | Cancelled before signing | | `TOKEN_TRANSACTION_SIGNED_CANCELLED` | Cancelled after signing | Filter by status: ```typescript theme={null} const finalized = response.tokenTransactionsWithStatus.filter( tx => tx.status === "TOKEN_TRANSACTION_FINALIZED" ); console.log("Completed transactions:", finalized.length); ``` ## Pagination For tokens with many transactions, use cursor pagination: ```typescript theme={null} const [tokenIdentifier] = await wallet.getIssuerTokenIdentifiers(); if (!tokenIdentifier) throw new Error("No token identifiers found for this issuer"); const firstPage = await wallet.queryTokenTransactionsWithFilters({ tokenIdentifiers: [tokenIdentifier], pageSize: 50, direction: "NEXT", }); console.log("Transactions in first page:", firstPage.tokenTransactionsWithStatus.length); const nextCursor = firstPage.pageResponse?.nextCursor; if (nextCursor) { const secondPage = await wallet.queryTokenTransactionsWithFilters({ tokenIdentifiers: [tokenIdentifier], pageSize: 50, cursor: nextCursor, direction: "NEXT", }); console.log("Transactions in next page:", secondPage.tokenTransactionsWithStatus.length); } ``` # Holders Source: https://docs.spark.money/issuance/token-holders Query token balances by Spark address using the `SparkReadonlyClient`. Public queries respect [privacy mode](/wallets/privacy): if a wallet is private, unauthenticated requests return empty results. Holders

## Your Balance Check how many tokens you hold: ```typescript theme={null} const balances = await wallet.getIssuerTokenBalances(); for (const { tokenIdentifier, balance } of balances) { if (!tokenIdentifier) continue; console.log(tokenIdentifier, balance); } ``` ## Check Any Address Pass an address to check someone else's balance: ```typescript theme={null} import { SparkReadonlyClient } from "@buildonspark/spark-sdk"; const client = SparkReadonlyClient.createPublic({ network: "MAINNET" }); const [tokenIdentifier] = await wallet.getIssuerTokenIdentifiers(); if (!tokenIdentifier) throw new Error("No token identifiers found for this issuer"); const holderBalances = await client.getTokenBalance("spark1abc...", [tokenIdentifier]); const info = holderBalances.get(tokenIdentifier); console.log("User balance:", info?.ownedBalance); ``` ## Display Amounts Convert base units to human-readable format: ```typescript theme={null} const holderBalances = await client.getTokenBalance("spark1abc...", [tokenIdentifier]); const info = holderBalances.get(tokenIdentifier); if (!info) throw new Error("No balance found (zero balance, unknown token, or privacy mode)"); function formatUnits(amount: bigint, decimals: number): string { const negative = amount < 0n; const value = negative ? -amount : amount; const base = 10n ** BigInt(decimals); const whole = value / base; const fraction = value % base; const fractionStr = fraction.toString().padStart(decimals, "0").replace(/0+$/, ""); const out = fractionStr ? `${whole.toString()}.${fractionStr}` : whole.toString(); return negative ? `-${out}` : out; } console.log(`${formatUnits(info.ownedBalance, info.tokenMetadata.decimals)} ${info.tokenMetadata.tokenTicker}`); ``` ## All Token Balances Get all token balances for an address: ```typescript theme={null} const tokenBalances = await client.getTokenBalance("spark1abc..."); function formatUnits(amount: bigint, decimals: number): string { const negative = amount < 0n; const value = negative ? -amount : amount; const base = 10n ** BigInt(decimals); const whole = value / base; const fraction = value % base; const fractionStr = fraction.toString().padStart(decimals, "0").replace(/0+$/, ""); const out = fractionStr ? `${whole.toString()}.${fractionStr}` : whole.toString(); return negative ? `-${out}` : out; } for (const [tokenId, info] of tokenBalances) { console.log(`${info.tokenMetadata.tokenTicker}: ${formatUnits(info.ownedBalance, info.tokenMetadata.decimals)}`); } ``` ## Listen for Changes Get notified when balances change: ```typescript theme={null} wallet.on("transfer:claimed", async (transferId, newBalance) => { console.log("Transfer received:", transferId); const updated = await wallet.getBalance(); console.log("New balance:", updated.balance); }); ``` # Spark CLI Source: https://docs.spark.money/issuance/tools/cli # Transfer Tokens Source: https://docs.spark.money/issuance/transfer-tokens Send tokens to any Spark address. Transfers are instant, free, and recipients receive them automatically.

## Send Tokens ```typescript theme={null} const [tokenIdentifier] = await wallet.getIssuerTokenIdentifiers(); if (!tokenIdentifier) throw new Error("No token identifiers found for this issuer"); await wallet.transferTokens({ tokenIdentifier, tokenAmount: 100_000000n, // 100 tokens (6 decimals) receiverSparkAddress: "spark1abc..." }); ``` ## Batch Transfer Send to multiple recipients in a single transaction: ```typescript theme={null} await wallet.batchTransferTokens([ { tokenIdentifier, tokenAmount: 1000_000000n, receiverSparkAddress: "spark1alice..." }, { tokenIdentifier, tokenAmount: 500_000000n, receiverSparkAddress: "spark1bob..." }, { tokenIdentifier, tokenAmount: 250_000000n, receiverSparkAddress: "spark1carol..." } ]); ``` Batch transfers are atomic. All succeed or none do. Each item in the array must include its own `tokenIdentifier`. ## Token Amounts All amounts are in base units. If your token has 6 decimals: | Human | Base Units | | :- | :- | | 1 | 1,000,000 | | 100 | 100,000,000 | | 0.5 | 500,000 | ```typescript theme={null} function toBaseUnits(amount: string, decimals: number): bigint { const [whole, fraction = ""] = amount.split("."); const fractionPadded = (fraction + "0".repeat(decimals)).slice(0, decimals); return BigInt(whole || "0") * 10n ** BigInt(decimals) + BigInt(fractionPadded || "0"); } await wallet.transferTokens({ tokenIdentifier, tokenAmount: toBaseUnits("50.5", 6), receiverSparkAddress: "spark1..." }); ``` ## Receiving Tokens Recipients don't need to do anything. Tokens appear instantly: ```typescript theme={null} const { tokenBalances } = await wallet.getBalance(); tokenBalances.forEach((data, key) => { console.log(data.tokenMetadata.tokenName, ":", data.ownedBalance); }); ``` # TypeScript Source: https://docs.spark.money/issuance/typescript TypeScript SDK for issuing and managing tokens on Spark. Requires Node.js v18+. ## Getting Started To get started, follow the steps below. Want to skip the manual setup? Scaffold a new project instantly: ```bash theme={null} npx @buildonspark/create-spark-app my-app ``` Supports React (Vite), Next.js, React Native, Expo, Express, and [more](https://github.com/buildonspark/spark). Install the Spark Issuer SDK packages using your package manager of choice. ```bash npm theme={null} npm install @buildonspark/issuer-sdk ``` ```bash yarn theme={null} yarn add @buildonspark/issuer-sdk ``` ```bash pnpm theme={null} pnpm add @buildonspark/issuer-sdk ``` Create an issuer instance that will be used to interact with the Spark network. ```ts issuer.ts theme={null} import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; const { wallet, mnemonic } = await IssuerSparkWallet.initialize({ mnemonicOrSeed: "optional-mnemonic-or-seed", accountNumber: 0, // optional options: { network: "REGTEST", }, }); console.log("Wallet initialized successfully:", mnemonic); ``` You're ready to start building. ```ts app.ts theme={null} import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; async function main() { try { // Initialize issuer wallet const { wallet } = await IssuerSparkWallet.initialize({ options: { network: "REGTEST" } }); console.log("Issuer wallet created!"); console.log("Address:", await wallet.getSparkAddress()); // Create a token const { tokenIdentifier, transactionHash } = await wallet.createToken({ tokenName: "My Token", tokenTicker: "MTK", decimals: 8, maxSupply: BigInt(21000000_00000000), // 21M tokens (with 8 decimals) isFreezable: false, returnIdentifierForCreate: true, }); console.log("Token created:", tokenIdentifier); console.log("Announcement tx:", transactionHash); // Mint tokens to yourself const mintTxId = await wallet.mintTokens({ tokenIdentifier, tokenAmount: BigInt(1000_00000000), // 1000 tokens (with 8 decimals) }); console.log("Tokens minted:", mintTxId); } catch (error) { console.error("Error:", error); } } main(); ``` ## TypeScript Configuration ### tsconfig.json Create a `tsconfig.json` file in your project root: ```json tsconfig.json theme={null} { "compilerOptions": { "target": "ES2020", "module": "commonjs", "lib": ["ES2020"], "outDir": "./dist", "rootDir": "./src", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "declaration": true, "declarationMap": true, "sourceMap": true }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] } ``` ### Package.json Scripts Add TypeScript build scripts to your `package.json`: ```json package.json theme={null} { "scripts": { "build": "tsc", "start": "node dist/app.js", "dev": "ts-node src/app.ts", "watch": "tsc --watch" } } ``` ## Core Issuer Operations ### Initialize an Issuer Wallet An issuer wallet requires either a mnemonic or raw seed for initialization. The `initialize()` function accepts both. If no input is given, it will auto-generate a mnemonic and return it. ```ts theme={null} import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; // Initialize a new issuer wallet const { wallet, mnemonic } = await IssuerSparkWallet.initialize({ mnemonicOrSeed: "optional-mnemonic-or-seed", accountNumber: 0, // optional options: { network: "REGTEST" // or "MAINNET" } }); console.log("Issuer wallet initialized:", mnemonic); ``` ### Mnemonic Phrases A mnemonic is a human-readable encoding of your wallet's seed. It's a 12- or 24-word phrase from the BIP-39 wordlist, used to derive the cryptographic keys that control your issuer wallet. ## TypeScript Features ### Type Safety The Spark Issuer TypeScript SDK provides full type safety for all issuer operations: ```ts theme={null} import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; // TypeScript will provide autocomplete and type checking const { wallet } = await IssuerSparkWallet.initialize({ options: { network: "REGTEST" } }); // All methods are fully typed const address: string = await wallet.getSparkAddress(); const tokensMetadata = await wallet.getIssuerTokensMetadata(); const tokenIdentifiers = await wallet.getIssuerTokenIdentifiers(); ``` ### Interface Definitions Key interfaces used by the Issuer SDK: ```ts theme={null} // Token creation parameters interface CreateTokenParams { tokenName: string; tokenTicker: string; decimals: number; isFreezable: boolean; maxSupply?: bigint; // defaults to 0n (unlimited) extraMetadata?: Uint8Array; returnIdentifierForCreate?: boolean; } // Token metadata returned by getIssuerTokensMetadata() interface IssuerTokenMetadata { rawTokenIdentifier: Uint8Array; tokenPublicKey: string; tokenName: string; tokenTicker: string; decimals: number; maxSupply: bigint; isFreezable: boolean; extraMetadata?: Uint8Array; bech32mTokenIdentifier: Bech32mTokenIdentifier; } // Token distribution stats interface TokenDistribution { totalCirculatingSupply: bigint; totalIssued: bigint; totalBurned: bigint; numHoldingAddress: number; numConfirmedTransactions: bigint; } ``` ### Error Handling The SDK provides typed error classes for better error handling: ```ts theme={null} import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; import { SparkError, SparkValidationError } from "@buildonspark/spark-sdk"; const { wallet } = await IssuerSparkWallet.initialize({ options: { network: "REGTEST" }, }); try { await wallet.createToken({ tokenName: "My Token", tokenTicker: "MTK", decimals: 8, maxSupply: BigInt(21000000_00000000), isFreezable: false }); } catch (error) { if (error instanceof SparkValidationError) { console.error('Validation error:', error.message); } else if (error instanceof SparkError) { console.error('SDK error:', error.message); } else { console.error('Unexpected error:', error); } } ``` # Core Concepts Source: https://docs.spark.money/learn/core-concepts

A statechain is a protocol that enables off-chain transfers of ownership for blockchain assets. It allows users to transfer control of a UTXO multiple times without creating on-chain transactions, using cryptographic signatures facilitated by a group of entities. This approach aims to improve transaction speed, privacy, and scalability while maintaining the security of the underlying blockchain.

## Spark Entity (SE)

The group of operators that run a Spark. They are responsible for performing the operations necessary for signing and forgetting past keys.

## Spark Operator (SO)

One of the operators within the SE. All operators, or a threshold number of them, assist with the transfer of off-chain UTXOs.

## Spark Service Provider (SSP)

A service provider that facilitates efficient deposits into and withdrawals from Spark. Any number of SSPs can exist within a single Spark. SSPs or another entity can optionally provide Lightning services, enabling Lightning transactions for users within Spark.

## Branches and Leaves

Leaves are terminal transactions of the tree that are owned by an individual user. Branches are all transactions of the tree that are not leaf transactions. These are nearly identical to leaf transactions, except they do not have timelocks and can only be spent by the sum of the keys of the leaves under them.

## Exit Transaction

A signed Bitcoin transaction that sends funds from Spark to the user. This serves as the unilateral exit mechanism, enabling any user to withdraw funds from Spark without cooperation by broadcasting the exit transaction and its parents.

## Atomic Swap

Exchanging two secrets A and B trustlessly for each other such that either both parties involved know both A and B or neither know both A and B.

# Deposits from L1 Source: https://docs.spark.money/learn/deposits Depositing L1 funds to Spark is straightforward. The SE (Spark Entity) and user collaborate to generate an aggregate public key and derive a pay-to-taproot address from it. They then work together to create and sign two transactions: an exit transaction, and an intermediate branch transaction before it that triggers the exit transaction's relative timelock. Once these transactions are both signed, the user can finally broadcast the deposit transaction to the pay-to-taproot address. Note that the inputs to the funding transaction should be segwit inputs. The user will now have a leaf in Spark. ### Steps-by-Step Process

1. **Key Generation:** * The user and SE work together to generate an aggregate public key, which is the sum of the user's public key and the SE's public key (which itself is derived from the individual SO public keys). They then derive a pay-to-taproot address for this key. * $\text{PubKey}_{Combined} = \text{PubKey}_{User} + \text{PubKey}_{SE}$ * where $\text{PubKey}_{SE} = \sum \lambda_i * \text{PubKey}_{SO_i}$ * and $\lambda_i$ is the Lagrange Coefficient on $x_0 = 0$ for $i$

2. **Setup and Signing:** * User constructs a deposit transaction sending their funds to the pay-to-taproot address, but doesn't broadcast it. * User and SE collaboratively create and sign two transactions: 1. An intermediate branch transaction (not broadcasted) with no timelock that spends from the deposit transaction. This transaction triggers the relative timelock of leaves under it. 2. An exit transaction that spends from the intermediate transaction. This transaction is broadcasted if the user wants to unilaterally exit Spark. * **Both transactions are signed by all parties involved in order to provide a unilateral exit path. Spark-compatible wallets should verify the transaction validity of all transactions involved.**

3. **Storage:** * User and SE securely store the signed transactions.

4. **User Deposit and Confirmation:** * User broadcasts the deposit transaction created in step 2. Once the L1 transaction has been confirmed, the funds are available to transfer within Spark.

# FAQ Source: https://docs.spark.money/learn/faq ### Is Spark live? Yes. Spark's beta mainnet is now live. Developers can start building and transacting on the network. While this is a beta release, core functionality like sending and receiving Bitcoin, supporting tokens (e.g. stablecoins), and Lightning interoperability is fully operational. That said, Spark is still highly experimental. Expect bugs, rapid iteration, and breaking changes as we continue to scale the network. ### How do I check if Spark is having issues? Check [spark.money/status](https://spark.money/status) for real-time network status. You can also report issues there. ### How is Spark native to Bitcoin? The Bitcoin you hold on Spark is the same Bitcoin you hold on Bitcoin. It's not wrapped or custodied in a multisig by a set of signers. On Spark, you can unilaterally exit your funds back to L1 at any time by broadcasting your pre-signed transaction to a Bitcoin node. ### How many Spark Operators (SOs) are there, and who are they? Spark is supported by its founding Spark Operators (SOs): [Lightspark](https://www.lightspark.com), [Flashnet](https://flashnet.xyz), and [Breez](https://breez.technology/), each selected for proven security and operational expertise. We take a thoughtful and deliberate approach to growing the operator set because security and reliability are our top priorities. Additional SOs will join as the network scales. ### Should I expect some limits? Spark is still early. Please treat everything as a beta environment. With that in mind, limits may be applied. Our first priority is making sure everything stays secure. ### What happens if Spark operators go offline?

You can always exit to Bitcoin L1 using your pre-signed exit transaction. If all operators go offline, you won't be able to make new Spark transfers until operators are back online, but your funds remain in your custody and are redeemable to Bitcoin L1 at any time. Check [Spark Status](https://spark.money/status) for real-time network health.

### Who provides liquidity for deposits and withdrawals?

Lightspark provides liquidity for deposits and withdrawals. Other providers can participate too, giving users more options and reducing reliance on any one provider.

### Does Spark have a token or a planned airdrop?

Spark does not have a token. Spark has not announced plans for any airdrop or token generation event. Be wary of scams claiming airdrops, giveaways, etc. If in doubt, refer to official Spark communication channels: Web: [https://spark.money](https://spark.money) Twitter: [@spark](https://x.com/spark)

### Does Spark support smart contracts?

No, Spark does not support smart contracts.

### Is Spark open source? Yes, Spark is open source. You can read the code or contribute directly [here](https://github.com/buildonspark/spark). ### Does Spark require KYC / KYB?

No. Spark is an open protocol that provides infrastructure for moving Bitcoin and tokens (e.g. stablecoins). Like Bitcoin, it does not impose any KYC requirements at the protocol level.

### What are the fees on Spark? | Transaction Type | Fee | | - | - | | L1 to Spark | On-chain fee paid by user | | Spark to Spark | Free (small flat fee coming in 6-12 months) | | Spark to Lightning | 0.25% + routing fee | | Lightning to Spark | Free for the receiver. 0.15% for the sender (charged on routing nodes) | | Exit to L1 | `250 × sats_per_vbyte + 750` where `sats_per_vbyte` is the fee rate based on exit speed (slow, medium, or fast) | The L1 exit fee is flat and doesn't scale with amount. For small withdrawals, it may be a higher percentage. The fee varies based on exit speed (slow, medium, or fast). # Spark FROST Source: https://docs.spark.money/learn/frost-signing Spark employs a customized version of the FROST (Flexible Round-Optimized Schnorr Threshold) signing scheme to enable transaction signing by a required participant alongside a threshold group of signers known as Signing Operators (SOs). ## Problem Statement

In Spark, transactions require co-signing by a user and a group of Signing Operators (see [SOs](/learn/technical-definitions#spark-operator-so)), together SOs make up that Spark Entity [(SE)](/learn/technical-definitions#spark-entity-se). The signature must meet these requirements: * **Threshold Signing for SOs:** Only $t$ out of $n$ total SOs are needed to complete the signing process. * **Mandatory User Signing:** The user's participation is essential for a valid signature. * **Single Schnorr Signature:** The final signature must be aggregated into a single Schnorr signature, ruling out multi-signature schemes like 2-of-2. The final signature is the aggregate of the user's signature and the SOs' signatures, where the user is the required participant. Additionally, the cryptographic keys must support: * **Tweakability:** Keys can be modified by adding or multiplying a tweak value. * **Additive Aggregatability:** Given all shards of two keys (e.g., key1 and key2), it must be possible to derive all shards for their sum (key1 + key2). This document presents a modified FROST signing scheme tailored to address these needs in Spark.

## Key Generation ### User Key

The user independently generates a single key pair, denoted as $(sk_{user}, pk_{user})$, where $sk_{user}$ is the secret key and $pk_{user}$ is the corresponding public key.

### SO Keys

The Signing Operators (SOs) collaboratively generate a threshold signing key pair, denoted as $(sk_{so}, pk_{so})$, using a Distributed Key Generation (DKG) protocol. Each SO receives a Shamir secret share $ss_i$ of $sk_{so}$, configured with a threshold $(t, n)$, meaning any $t$ of the $n$ SOs can reconstruct the key. **Note:** Details of the secure DKG process are beyond the scope of this document. You can find more information in the [FROST paper](https://eprint.iacr.org/2020/852.pdf).

## Key Aggregation

The user's key and the SOs' key are combined into an aggregated key using additive aggregation: * The aggregated secret key is computed as $sk_{agg} = sk_{user} + sk_{so}$. * The corresponding public key is $Y = pk_{user} + pk_{so}$. All participants must know the aggregated public key $Y$.

## Pre-processing

Mirroring FROST's pre-processing phase, all participants generate and commit to nonces: * **SO Nonces:** Each SO generates nonce pairs $(d_{ij}, e_{ij})$ and their commitments $(D_{ij}, E_{ij})$, where $D_{ij} = g^{d_{ij}}$ and $E_{ij} = g^{e_{ij}}$, using a fixed generator $g$. * **User Nonces:** The user generates nonce pairs $(d_{user_i}, e_{user_i})$ and commitments $(D_{user_i}, E_{user_i})$, sharing these commitments with all SOs. These nonces enhance security during signing by preventing replay attacks.

## Signing Flow

The signing process involves the user, a coordinator, and a subset of SOs, proceeding as follows: 1. **Initiation:** * The user submits a signing request for message $m$ to a signing operator coordinator. 2. **Participant and Nonce Selection:** * The coordinator selects a set $S$ of $t$ participating SOs. * It compiles an unused nonce commitment list $B = \{(D_{ij}, E_{ij}) \mid i \in S\} \cup \{(D_{user_j}, E_{user_j})\}$ and broadcasts $B$ to all participants. 3. **Signature Share Calculation by SOs:** * Each SO $i \in S$ computes: * $\rho_i = H_1(i, m, B)$, using a hash function $H_1$. * Nonce contribution: $R_i = D_{ij} \cdot E_{ij}^{\rho_i}$. * Challenge: $c = H_2(R, Y, m)$, where $R = \prod_{i \in S} R_i$. * Signature share: $z_i = d_{ij} + e_{ij} \rho_i + \lambda_i ss_i c$, where $\lambda_i$ is the Lagrange coefficient for reconstructing $sk_{so}$. 4. **SO Signature Aggregation:** * The coordinator aggregates the SO shares: $z_{so} = \sum_{i \in S} z_i$. * It computes $R_{so} = \prod_{i \in S} R_i$, validates the partial signature, and sends $(R_{so}, z_{so})$ along with $B$ to the user. 5. **User Signature Share Calculation:** * The user computes: * $\rho_{user} = H_1(0, m, B)$ (assuming user index 0). * Nonce contribution: $R_{user} = D_{user_j} \cdot E_{user_j}^{\rho_{user}}$. * Full nonce: $R = R_{so} \cdot R_{user}$. * Challenge: $c = H_2(R, Y, m)$. * Signature share: $z_{user} = d_{user_j} + e_{user_j} \rho_{user} + sk_{user} c$. 6. **Final Signature:** * The user aggregates the final signature as $(R, z)$, where $z = z_{so} + z_{user}$.

## Key Tweaks

The SO key $\mathit{sk_{so}}$ is shared via Shamir secret sharing with the polynomial: $f(x) = \mathit{sk_{so}} + a_1 x + a_2 x^2 + \cdots + a_{t-1} x^{t-1}$ Each SO $i$ holds the share $(i, f(i))$.

### Additive Tweak

To tweak $\mathit{sk_{so}}$ by adding $t$ (i.e., $\mathit{sk_{so}'} = \mathit{sk_{so}} + t$): * Define the new polynomial $f'(x) = f(x) + t$ * Update each share to $f'(i) = f(i) + t$

### Multiplicative Tweak

For a multiplicative tweak by $t$ (i.e., $\mathit{sk_{so}'} = t \cdot \mathit{sk_{so}}$): * Update each share to $f'(i) = t \cdot f(i)$

### Secure Tweak Distribution

Directly sharing $t$ with SOs risks key exposure if the sender is an SO or colludes with one. Instead: * Construct a polynomial $g(x)$ of degree $t-1$ where $g(0) = t$ * Distribute $g(i)$ to each SO $i$ * Each SO updates their share: $f'(i) = f(i) + g(i)$ This method applies the tweak securely without revealing $t$.

## Key Split

When splitting a key into $n$ child keys (e.g., for transaction splitting), the property holds: $\mathit{Alice_{old}} + \mathit{SO_{old}} = \sum_{i=1}^n (\mathit{Alice_i} + \mathit{SO_i})$ Here, $\mathit{Alice_{old}}$ and $\mathit{SO_{old}}$ are the original user and SO keys, and $\mathit{Alice_i}$ and $\mathit{SO_i}$ are the child keys.

### Process

1. **User Key Splitting:** * The user (Alice) generates $n$ key pairs $(\mathit{sk_{Alice_i}}, \mathit{pk_{Alice_i}})$ for $i = 1$ to $n$ * Compute $\mathit{sum_{Alice}} = \sum_{i=1}^n \mathit{sk_{Alice_i}}$ * Calculate $\mathit{Tweak} = \mathit{sk_{Alice_{old}}} - \mathit{sum_{Alice}}$ 2. **Tweak Communication:** * The user sends $\mathit{Tweak}$ to the SOs. 3. **SO Key Splitting:** * The SOs use DKG to generate $n-1$ key pairs $(\mathit{sk_{SO_i}}, \mathit{pk_{SO_i}})$ for $i = 1$ to $n-1$ * Set the $n$-th key as $\mathit{sk_{SO_n}} = \mathit{sk_{SO_{old}}} - \left( \sum_{i=1}^{n-1} \mathit{sk_{SO_i}} - \mathit{Tweak} \right)$ 4. **Verification:** * The sum of child keys is: $\sum_{i=1}^n \mathit{sk_{Alice_i}} + \sum_{i=1}^n \mathit{sk_{SO_i}} = \mathit{sum_{Alice}} + \sum_{i=1}^{n-1} \mathit{sk_{SO_i}} + \mathit{sk_{SO_{old}}} - \sum_{i=1}^{n-1} \mathit{sk_{SO_i}} + \mathit{Tweak}$ * Substituting $\mathit{Tweak} = \mathit{sk_{Alice_{old}}} - \mathit{sum_{Alice}}$: $= \mathit{sum_{Alice}} + \mathit{sk_{SO_{old}}} + (\mathit{sk_{Alice_{old}}} - \mathit{sum_{Alice}}) = \mathit{sk_{Alice_{old}}} + \mathit{sk_{SO_{old}}}$ 5. **Shard Adjustment:** * For SOs' Shamir shares, the $n$-th key's share for SO $j$ is adjusted as: $f_{SO_n}(j) = f_{SO_{old}}(j) - \left( \sum_{i=1}^{n-1} f_{SO_i}(j) - \mathit{Tweak} \right)$

# Lightning Interoperability Source: https://docs.spark.money/learn/lightning

This provides Alice with true offline receive - she doesn't need to be online in order to receive the full Lightning payment. Additionally, Alice does not need to run a Lightning node and does not need to open any channels or perform any force closures. All operations here are atomic under the same 1/n or minority/n trust assumptions, as the operators must work together to recreate the preimage.

### Sending a Lightning Payment

1. Alice receives a Lightning invoice from Bob. 2. Alice makes an API call to the Lightning payment provider, agreeing to conditionally transfer leaves upon payment completion. 3. SE locks transfers on Alice's specified leaves until a specified time. 4. The payment provider makes a Lightning payment to pay Bob's invoice. 5. The payment provider submits proof of Lightning payment to the SE. 6. SE finalizes the transfer of Alice's leaves to the Lightning payment provider atomically. **Note:** If the specified time expires, the SE unlocks usage of Alice's leaves and control returns to her.

*** ### Routing Nodes If you're a Lightning node operator or LSP looking to establish channels with Spark, connect to our routing nodes: ``` 02a98e8c590a1b5602049d6b21d8f4c8861970aa310762f42eae1b2be88372e924@54.201.244.204:10016 039174f846626c6053ba80f5443d0db33da384f1dde135bf7080ba1eec465019c3@54.149.30.52:10015 ``` Opening channels to these nodes improves routing reliability for Lightning payments to and from Spark wallets. # Limitations / Attacks Source: https://docs.spark.money/learn/limitations

If a prior owner of a Spark leaf publishes the branch in a unilateral exit, there is a time limitation during which the correct owner needs to publish the correct leaf transaction. If the current owner does not do so during the window, then the attacker can claim the leaf UTXO. The SOs all have a copy of the signed transaction and can act as watchtowers on behalf of the current leaf owner. Further, the user can delegate watchtower functionality to any third party as the watchtower holds no toxic data. Additionally, depending on how the Spark is configured, this attack can be fairly costly for the attacker - they need to publish the entire branch (unless someone else has unilaterally closed much of the same branch) and CPFP each tree node.

### Loss of SE liveness

If any (or a minority of the Spark is configured for threshold) of the SOs lose liveness or lose their keys, the Spark will not be able to continue. Users will still be able to withdraw their funds through unilateral exits, but they will be unable to continue to send off-chain payments with Spark. This means that the entities comprising the SE should be carefully chosen to be highly available and low-latency since they are in the flow of UTXO transfers. The number of entities and the threshold of trust are configurable - for example, could require trusting ⅓ of the n entities in the SE, which would grant higher liveliness. This can be further mitigated by a single SE holding multiple public keys with the same threshold aggregate public key. That way if one host server is lost, the other cold key can be used, without the whole state-chain being closed on-chain.

# Scalability Source: https://docs.spark.money/learn/scalability Spark's design enables it to be nearly infinitely scalable with minimal computational costs. This is unlocked through the lack of global consensus or propagation. Validator nodes (SOs) only need to gather for signing at moment of transfer. Transactions can be processed and settled independently of other transactions, making Spark fully parallelizable. SOs themselves can be scaled horizontally allowing them to process and sign more transactions as they scale. The goal of Spark is to be able to handle billions of concurrent users, and to do so with minimal fees and instant finality. # Sovereignty Source: https://docs.spark.money/learn/sovereignty Self-sovereignty is a core principle of Spark's design. It is an unparalleled quality that very few L2s can afford to its users. Spark, like Lightning, is narrowly designed for transfers of value, not general computation like other L2s. This focus makes achieving non-custodiality and true trustless exits much more straightforward.

How it works: * **Pre-signed Transactions:** Before you deposit funds into Spark, you work with the operators to create a pre-signed transaction that exits funds to the Bitcoin L1. Meaning you can always exit your funds if the operators go offline or become malicious after a transfer * **Timelocked Transactions:** When ownership of the leaf (in Spark, leaves work like UTXOs and represent the ownership of a UTXO on L1) is transferred (e.g., from Alice to Bob), a transaction is signed that gives Bob ownership of a leaf on L1. This exit transaction is encumbered by a timelock that is relative to its parent transaction. By the timelock being relative, it means that there is no limit to how long you can hold onto an unpublished leaf before it must go on-chain. * **Decrementing Timelocks**: If Bob then transfers the leaf to Charlie, a new transaction is signed for Charlie with a shorter timelock (e.g., 300 blocks instead of Bob's 400). Each subsequent transfer reduces the timelock, so the most recent owner's transaction becomes valid first. This ensures that the current owner always has a sooner exit than the previous owner. This can be supported by watchtowers to ensure that the current owner always exits before the previous owner. * **Fallback to L1:** If the Spark operators disappear, get compromised, attempt to censor, or refuse to cooperate, you (the current owner) can unilaterally broadcast to Bitcoin L1 the pre-signed transactions up to, and including, your leaf and claim the funds once the relative timelocks expire.

This mechanism ensures that you don't rely on any outside entity indefinitely. Even if it's a centralized component, you have an unshakeable and unconditional escape hatch to reclaim your funds on the Bitcoin L1, making your funds non-custodial in practice. The relativity of the timelock also makes it so the user does not have to refresh or exit funds to L1 on a set schedule. Exiting Spark can take as little as 100 blocks depending on the depth of their leaf. This differs substantially from the standard L2 exit mechanisms, in which users must rely on a centralized sequencer or bridge to exit, without absolute guarantees.

# Technical Definitions Source: https://docs.spark.money/learn/technical-definitions > **Disclaimer** *This section can be bypassed if the reader understands statechains, which are used as a building block for what follows. This section provides a high-level overview of how statechains work. Please note that the description here is intentionally simplified and may not be entirely accurate; its purpose is to convey the core functionality of statechains in an accessible manner.* Statechains are a way to transfer ownership of a UTXO off-chain. In this example, all key signing operations are performed with [Schnorr](https://en.bitcoin.it/wiki/Schnorr). First, begin with the assumption that keys can be linearly added together to form a single key. We will start with two parties holding keys - one is the user Alice (A), and the other will be called the statechain entity (SE), which can be composed of any number of members but will be shown as a single entity below. $(SE+A=Key1)$ Each key is represented as a large random number. In this example, SE's key is represented by the value 100, and A's key is represented by the value 50. $(100+50=150=Key1)$ Now assume that a signature is simply multiplying the key by the hash of some object. The hash will also be represented by a number. In this example, our hash will be represented by the value 2. Thus, a signature of this hash will be: $((100+50)*2=300)$ To deposit funds into the statechain, Alice first creates a transaction to send money to a joint address controlled by the SE and herself (using their combined key of 150). However, she doesn't broadcast this transaction immediately. Instead, Alice and the SE collaborate to create and sign an exit transaction. This exit transaction is designed to transfer the coins directly to Alice, but it is locked with an absolute timelock set to an arbitrary amount of blocks in the future. Once Alice has the signed exit transaction in her possession, she then broadcasts the original deposit transaction. This creates a UTXO with a spending condition that requires the combined signature of SE and Alice. This careful sequencing ensures that Alice always has the ability to exit the statechain at any moment, even before the deposit is confirmed. This setup forms the foundation of the statechain mechanism. Alice now wishes to transfer ownership of this UTXO to Bob (B), but she wants to do so without putting the transaction on-chain. Bob's randomly generated key is represented by the number 40. He then calculates that the difference between his key and Alice's key is 10 (50 - 40 = 10). For Bob plus the SE to sign using the same value as Alice+SE (150), the SE needs to tweak their key by 10. So, the SE discards the old key (100) and only keeps a copy of the newly tweaked key 110 (100 + 10 = 110). Now, SE+Bob still equals 150 (110 + 40 = 150), so the UTXO can be spent by signing using the combined 150. This meets the original spending condition of the UTXO. Alice can't sign a new transaction anymore because the SE discarded the 100 key. If Alice tried to sign, Alice+SE would now equal 160 (50 + 110 = 160), which isn't a valid key to sign the transaction. This process effectively transfers control of the UTXO from Alice to Bob without requiring an on-chain transaction. During the key handoff process, the new owner collaborates with the SE to create and sign a new exit transaction. This new exit transaction features a lower timelock compared to the previous owner's exit transaction. For instance, if Alice's original exit transaction had a timelock of 100 blocks, Bob (the new owner) might set his timelock to 90 blocks. This process of decreasing timelocks continues with each subsequent transfer. When Bob transfers to Carol, her exit transaction might have a timelock of 80 blocks, and when Carol transfers to Dave, his could be set to 70 blocks. This decreasing timelock pattern ensures that the most recent owner always has the earliest opportunity to claim the UTXO on-chain. It's important to note that these exit transactions can only be executed on-chain once their respective timelocks expire. This mechanism provides a safeguard, allowing the current owner to claim the funds before any previous owners, while still maintaining the off-chain nature of the transfers until necessary. It's important to understand that this mechanism imposes a time limit on how long a UTXO can remain within a statechain. The current owner must claim the funds on-chain before the absolute timelock expires. If they fail to do so, previous owners will have the opportunity to claim the UTXO on-chain. This time constraint prevents indefinite off-chain existence of UTXOs in vanilla Statechains. ## Timelocks

Timelocks on Bitcoin can either be absolute or relative. An absolute timelock specifies a block height after which a transaction can be broadcasted. A relative timelock specifies a number of blocks after the parent transaction is included in a block before the child transaction can be broadcasted. The diagram below shows how statechains typically work:

In the above diagram, transactions 1 through 3 are all held off-chain. They all spend the same output from Txn0 and are replacements for each other. They use decreasing timelocks such that Txn4 can be put on-chain prior to Txn3, which could be put on-chain prior to Txn2. In this way, when ownership of the key controlling the funds is transferred to a new user, they can check the prior transactions and be assured that they can publish their new transaction first. These timelocks create a timebomb where the off-chain transaction with the lowest timelock will need to be put on-chain when its timelock expires, otherwise there is a risk that other transactions can claim the funds. This can, however, be eliminated by the following flow:

Txn1 spends the output of Txn0. Txn1 has no timelock. When users transfer keys, they transfer ownership of the key that encumbers the output of Txn1. The transactions that spend from Txn1's output look like the normal statechain transactions that include decreasing timelocks relative to their parent transaction. But because Txn1 is held off-chain, there is no absolute timebomb. The obvious problem with this is that if someone double-spends the output consumed by Txn1, then all of the leaves (Txn2..4) become invalid. To avoid this, the "SE" key is deleted by the SE - resulting in only one transaction ever generated for Txn0's output. The exact mechanics of this will be discussed later.

## Splitting a Leaf

We split leaves to spend smaller denominations. We do so by constructing a Bitcoin transaction that takes the parent UTXO as an input and produces multiple outputs, each controlled by a new key, which is split off from the original key. The sum of the new keys in all branches equals the original key, this allows for re-aggregation of leaves and more flexible leaf management without on-chain transactions. To split a leaf in Spark, we need to split its existing key into multiple keys such that the sum of the new keys equals the original key. This can be represented as follows: Original key: $(a_0=150)$ Split into two keys: $(a_1=100)$ $(a_2=50)$ Ensuring $(a_0= a_1+a_2)$ If the parent leaf is encumbered by the spending condition of $(a_0)$ it can then alternatively be spent using $(a_1+a_2)$ as they sum up to $(a_0)$ We want to ensure the following: $(\text{PrivKey}_{\text{User\_Old}} + \text{PrivKey}_{\text{SE\_Old}} = \sum_{i=1}^{n} \left( \text{PrivKey}_{\text{User}_i} + \text{PrivKey}_{\text{SE}_i} \right))$ 1. **User Key Splitting** * Generate $(n)$ new user private keys * Calculate the difference $(t)$ between old and new keys: $(t = \text{PrivKey}_{\text{User\_Old}} - \sum_{i=1}^{n} \text{PrivKey}_{\text{User}_i})$ 2. **SE Key Splitting** * Calculate the new SE key sum: $(P_{\text{SE\_New}} = P_{\text{SE\_Old}} + t)$ * Generate $(n-1)$ randomly generated SE private keys. * Calculate the final SE key to satisfy the key sum equality: $(P_{\text{SE\_New\_n}} = P_{\text{SE\_Old}} + t - \sum_{i=1}^{n-1} P_{\text{SE\_New\_i}})$ 3. **Branch Transaction Creation** * Create transaction with $(i)$ outputs, each locked by a new combined public key $(\text{SE}_n+\text{U}_n)$ 4. **Intermediate Branch and Exit Transactions for Each Leaf** * Create and sign intermediate branch and exit transactions for each new leaf using the new keys 5. **Key Deletion** * Securely delete original private keys 6. **Finalization** * Store the branch transaction off-chain. * Record the new leaves for use within Spark.

## Spark Tree

A Spark tree is made up of both Leaf-Transactions as well as Branch-Transactions.

We extend a UTXO within Spark into branches and leaves. Txn0 is spent by Txn1, which is held off-chain. Txn1 is the first branch transaction. As mentioned above, the absolute timelock timebombs are removed from the tree.

## Aggregation

When a transaction branches, the key that controls the parent input is divided into multiple child keys. These child keys are created in such a way that their sum equals the parent key. For example, Txn1 could be replaced by a new transaction, which would be valid if it's signed using the combined (aggregated) signatures from all the child keys at the bottom of the tree. In other words, the following keys, when aggregated, can spend Txn1: $( (B_{0.1.1.1.1} + SE_{0.1.1.1.1}) + (B_{0.1.2.1.1} + SE_{0.1.2.1.1}) + (B_{0.2.1.1.1} + SE_{0.2.1.1.1}) + (B_{0.2.2.1.1} + SE_{0.2.2.1.1}) )$ Which is equivalent to all the following: $(B_0 + SE_0)$ $(B_{0.1} + SE_{0.1} + B_{0.2} + SE_{0.2})$ $(B_{0.1.1} + SE_{0.1.1} + B_{0.1.2} + SE_{0.1.2} + B_{0.2.1} + SE_{0.2.1} + B_{0.2.2} + SE_{0.2.2})$ $((B_{0.1.1.1} + SE_{0.1.1.1}) + (B_{0.1.2.1} + SE_{0.1.2.1}) + (B_{0.2.1.1} + SE_{0.2.1.1}) + (B_{0.2.2.1} + SE_{0.2.2.1}))$

# TLDR Source: https://docs.spark.money/learn/tldr Spark is an off-chain scaling solution that builds on top of [Statechains](https://bitcoinops.org/en/topics/statechains/) to enable instant, extremely low fee, and unlimited self-custodial transactions of Bitcoin and tokens while also natively enabling sending and receiving via Lightning. Spark is not a rollup, nor a blockchain. There are no smart contracts nor VM. Spark is native to Bitcoin and its payments-focused architecture, enabling on-chain funds to be transacted at any scale, with near-instant speeds, and at virtually zero cost. At its core, Spark is a simple [shared signing protocol](/learn/frost-signing) on top of Bitcoin. It operates as a distributed ledger. There are no bridges, external consensus, or sequencers. Users can enter and exit the network freely, with funds always non-custodial and recoverable on L1 via a unilateral exit which depends on Bitcoin and no one else. Transactions on Spark happen by delegating on-chain funds via the shared signing protocol. Like the Lightning Network, Spark transactions work by delegating ownership of on-chain UTXOs between parties. The key difference: Spark introduces a set of signers, called Spark Operators (SOs), responsible for helping sign transactions as they happen. SOs cannot move funds without the users, who are required participants in any transfer. On L1, Spark state appears as a chain of multi-sigs, secured by users and SOs. On L2, it operates as a tree structure, mapping transaction history and balances in real time. Simple, fully native to Bitcoin, and open-sourced. For a system that scales Bitcoin as effectively as Spark does, it achieves the maximum possible level of trustlessness. Specifically, it maintains 1/n trust assumptions or minority/n depending on the setup. To learn more about the trust assumptions, read our [trust assumptions](/learn/trust-model) page. For a deeper technical explainer of how Spark works, including statechains, FROST signatures, and the leaf architecture, read [What is Spark? A Bitcoin Layer 2 Built on Statechains](https://www.spark.money/research/what-is-spark-bitcoin-layer-2). # Transaction Lifecycle Source: https://docs.spark.money/learn/tokens/broadcast-lifecycle How token transactions actually work under the hood. ## The basics A token transaction moves tokens from inputs to outputs. Three parties involved: 1. **You** (the wallet): construct and sign the transaction 2. **Spark Operators**: validate, co-sign, and commit 3. **Watchtowers**: watch for cheaters trying to double-spend on L1 The key thing: operators never have unilateral control. Every transaction needs your signature. They witness and enforce, but they can't move your tokens without you. ## The flow ``` 1. You build the transaction - Which outputs to spend - Who gets what - Sign it 2. Send to operators 3. Operators validate - Check your signatures - Check you own the inputs - Reserve revocation keys 4. Operators fill in the final details - Revocation commitments (for double-spend protection) - Withdrawal parameters (for L1 exit) 5. Operators commit - Threshold signs off - Watchtowers updated 6. Done - You get the final transaction - Recipient can spend immediately ``` One call handles the whole thing. It's atomic. Either everything succeeds or nothing does. ## Transaction types **Mint**: Issuer creates new tokens. No inputs spent. Just issuer signature authorizing creation. **Transfer**: Move tokens between owners. Inputs must equal outputs. **Create**: Register a new token type. Define name, ticker, decimals, max supply. ## Revocation: how double-spend protection works This is the clever part. When you receive tokens, each output has a "revocation commitment". This is a public key where the private key is split among operators. Nobody knows the full key. When you spend those tokens, operators release their key shares to you. Now you can reconstruct the full "revocation key" for the outputs you just spent. Why does this matter? If you try to cheat by broadcasting old outputs to L1: * Watchtowers see it * They have the revocation key (you gave it to them when you spent) * They sweep your funds immediately * You lose everything The economic incentive is simple: cheating costs more than you could gain. ## Validity window Transactions expire. You have up to 300 seconds (5 minutes) from when you create a transaction to when operators commit it. After that, it's rejected and you have to start over. This prevents stale transactions from clogging the system. ## What can go wrong | Problem | What happened | | - | - | | Insufficient balance | You don't have enough tokens | | Output already spent | Someone else spent it first | | Invalid signature | Wrong key | | Frozen | Issuer froze your address | | Transaction expired | Took too long, try again | ## Finality Once operators commit, it's done. Instant. Final. The recipient can spend immediately. No confirmations to wait for. The only "confirmation" that matters is the threshold of operators agreeing. Once they do, the transaction is irreversible at the Spark level. # Burning Source: https://docs.spark.money/learn/tokens/burning Burning destroys tokens permanently. Once burned, they're gone forever. ## How it works The issuer signs a burn transaction specifying which tokens to destroy. Operators validate and commit. Those tokens no longer exist. Total supply decreases. ## Why burn? **Redemptions.** User wants to cash out $100 of stablecoin. You send them $100, burn their 100 tokens. Supply stays matched to reserves. **Deflationary mechanics.** Some tokens burn a portion of each transaction or do periodic buyback-and-burns. **Mistakes.** Minted too many? Burn the excess. ## Who can burn Only the issuer can use the burn function directly. But there's a workaround: anyone can burn tokens by sending them to the burn address. ``` spark1pgssyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszqgpqyqszykl0d2 ``` Tokens sent here are gone. The address exists but nobody has the key. This lets regular users burn their own tokens if they want to. ## Irreversibility Burning is permanent. There's no undo. Double-check amounts before you burn. If an issuer burns tokens by mistake, the only fix is minting new ones (if max supply allows). ## Burning vs freezing Freezing is temporary and reversible. Burning is permanent. If you're not sure, freeze first. You can always burn later. # Core Concepts Source: https://docs.spark.money/learn/tokens/core-concepts The building blocks of how tokens work on Spark. ## UTXO model Tokens on Spark work like Bitcoin. You have outputs. To spend, you consume outputs and create new ones. Math has to balance. Inputs equal outputs. ``` Alice has: 100 tokens (one output) Alice sends: 75 to Bob Result: Bob gets: 75 tokens (new output) Alice gets: 25 tokens (change output) Original output: consumed ``` This is different from account-based systems (like Ethereum) where you have a balance that gets debited. Here, you have discrete chunks of tokens that get spent and created. ## TTXOs A TTXO (Token Transaction Output) is a single token holding. It contains: * **Owner**: Who can spend it * **Token**: Which token (identified by a 32-byte identifier) * **Amount**: How many * **Revocation commitment**: For double-spend protection * **Withdrawal parameters**: For L1 exit Each TTXO maps to a pre-signed Bitcoin transaction. If operators disappear, you broadcast that transaction and claim your tokens on L1. That's the self-custody guarantee. ## Operators and threshold Spark Operators validate and co-sign transactions. A threshold of operators must agree for any transaction to go through. | Operators | Threshold | | - | - | | 2 | 2 | | 3 | 2 | | 5 | 3 | Formula: `(n + 2) / 2` rounded down. This is majority, not 1-of-n. What operators can do: * Delay transactions by refusing to sign * See transaction metadata * Run watchtowers What operators cannot do: * Move your tokens without your signature * Steal your tokens (even if all collude) * Block your exit to L1 ## Revocation The key innovation. How do you prevent double-spending in an off-chain system? When you receive tokens, each output has a revocation commitment. This is a public key where the private key is split among operators via DKG. Nobody knows the full key. When you spend those tokens, operators release their key shares. Now you can reconstruct the full revocation key for those outputs. If you try to cheat by broadcasting old (spent) outputs to L1: * Watchtowers detect it * They have the revocation key * They sweep your funds * You lose everything Cheating costs more than you could gain. That's the security model. ## DKG Distributed Key Generation. How operators create shared secrets without any single party knowing the full secret. Operators pre-generate batches of keys where: * Each operator holds a share * No single operator has the full private key * Threshold cooperation is needed to reconstruct These become revocation commitments for new outputs. ## Watchtowers Services that monitor Bitcoin L1 for attempted double-spends. Each operator runs one. If someone broadcasts a revoked output: 1. Watchtower detects it 2. Uses stored revocation key to sweep 3. Cheater loses everything Only one honest watchtower is needed. They're incentivized to catch cheaters. They get the bond. ## Relationship to Bitcoin Tokens on Spark aren't wrapped or bridged. They're native Bitcoin constructs. Exit transactions are valid Bitcoin transactions. Security comes from Bitcoin's proof-of-work. Operators can disappear and you still exit to L1. No bridge. No custodian. That's the point. # Freezing Source: https://docs.spark.money/learn/tokens/freezing Issuers can optionally freeze addresses. This is not enforced at the protocol level. It's a feature issuers can choose to implement. ## How it works The issuer signs a message saying "freeze this public key." Spark Operators add that key to their frozen list. Any transfer attempt from that key gets rejected. Unfreezing works the same way. Issuer signs, operators remove from list, transfers work again. ## What gets frozen Freezing targets a public key, not specific tokens. So: * All tokens owned by that key become untransferable * Any new tokens sent to that key are also frozen ## Optional by design Freezing is entirely optional. Issuers choose whether to use it. Some issuers may never freeze anyone. Others may need it for compliance reasons. The protocol doesn't require freezing. It's a tool available to issuers who want it. # Glossary Source: https://docs.spark.money/learn/tokens/glossary Quick definitions. ## BTKN Bitcoin Token. The token protocol on Spark. Fast, cheap, native Bitcoin tokens. ## Create Registering a new token type. You do this once per token. Define name, ticker, decimals, max supply. ## DKG Distributed Key Generation. How operators create shared secrets where no single party knows the full key. Used for revocation commitments. ## Final Token Transaction The complete transaction after operators fill in revocation commitments and withdrawal parameters. This is what gets stored and propagated. ## Mint Creating new token units. Only the issuer can mint. ## Partial Token Transaction What the wallet constructs before sending to operators. Missing revocation commitments and other fields that operators fill in. ## Revocation Commitment A public key embedded in each token output. The private key is split among operators. When you spend, operators release their shares so you can reconstruct the full revocation key. ## Revocation Key The private key for a revocation commitment. If you try to double-spend by broadcasting old outputs, watchtowers use this to sweep your funds. ## Spark Entity The group of Spark Operators running the network. ## Spark Operator A single node that validates, co-signs, and enforces transactions. Each one runs a watchtower. ## Threshold How many operators must agree. Formula: `(n + 2) / 2`. For 5 operators, threshold is 3. ## Token Identifier 32-byte unique ID for a token. Displayed in bech32m format. ## Transfer Moving tokens between owners. Inputs must equal outputs. ## TTXO Token Transaction Output. A single token holding. Owner, amount, token type, revocation commitment, withdrawal parameters. ## Unilateral Exit Withdrawing to Bitcoin L1 without operator cooperation. You broadcast pre-signed exit transactions, wait for locktime, claim tokens on L1. ## Validity Duration How long a transaction can wait before operators reject it. Max 300 seconds. ## Watchtower Service monitoring Bitcoin for double-spend attempts. Each operator runs one. If someone broadcasts a revoked output, watchtowers sweep their funds. ## Withdrawal Bond Sats you post when exiting to L1. Returned after locktime if legitimate. Swept by watchtowers if you're cheating. ## Withdrawal Locktime Blocks to wait after broadcasting an exit transaction. Gives watchtowers time to check and respond. # Hello, BTKN! Source: https://docs.spark.money/learn/tokens/hello-btkn BTKN (Bitcoin Token) YO

### What the BTKN? BTKN is the Bitcoin token standard we wished existed when we started building on Bitcoin. It's fast, it's incredibly cheap, and it moves natively on Bitcoin without any of the UX limitations that usually comes with tokens on Bitcoin. For developers, BTKN just makes sense. You can mint tokens in seconds, transfer them instantly, and your users never have to think about gas fees or wait for confirmations. They're native Bitcoin tokens that inherit all of Bitcoin's security guarantees. BTKN is everything we learned building on Bitcoin, distilled into one protocol. We took the best parts of Bitcoin's UTXO model, added instant settlement when you need it, and made sure you can always fall back to Bitcoin's base layer when security matters most. ### TL;DR In more technical terms: BTKN (Bitcoin Token) is our adaptation of the [LRC-20](https://github.com/akitamiabtc/LRC-20/blob/main/LRC20-current.pdf) protocol but specifically optimized for Spark. We discovered LRC-20 in Summer 2023 and were impressed by it. After pushing it to its limits, we realized we needed to make significant improvements and changes that warranted its own identity: BTKN. BTKN has two key components: Bitcoin (L1) as the settlement layer and Spark as the execution engine. On Bitcoin (L1), BTKN works by tweaking Bitcoin addresses in a way that embeds token data inside regular transactions. Bitcoin nodes process these transactions as usual, but BTKN-aware nodes can extract and verify token movements by watching how those keys are adjusted. On Spark, BTKN doesn't need to play the same tricks as L1. We don't tweak keys. Instead, they exist natively as metadata within Spark's TTXOs. When an issuer mints new tokens, they submit a transaction embedding the token's details (amount, ID, and properties) directly into a designated TTXO. Spark Operators validate these transactions, making sure they follow protocol rules and attesting to state changes. They then share this data with BTKN nodes, which continuously track transactions and keep Spark in sync with L1. BTKN tokens on Spark inherit the same L1 guarantees as Bitcoin. You can unilaterally exit your assets at any time. # A bit of history Source: https://docs.spark.money/learn/tokens/history If you've spent any time in crypto, you're used to the idea that tokens live inside smart contracts. On Ethereum, Solana, and most other chains, tokens aren't native; they're managed by programs that live on-chain, enforcing balances and rules. There are no smart contracts on Bitcoin, not in the way you think of them, at least. Bitcoin's base layer is intentionally simple. It doesn't execute arbitrary code. It doesn't have an account model. It doesn't let you just "deploy" a contract and start issuing tokens. So how do you put tokens on Bitcoin? The answer: metaprotocols, systems that extend Bitcoin by embedding additional information into regular Bitcoin transactions. Instead of deploying new logic to the chain, metaprotocols work on top of Bitcoin's existing rules, using its transactions as a foundation while keeping token data indexed off-chain. Over the years, we've seen a wave of attempts to bring tokens to Bitcoin: Ordinals, BRC-20, RGB, Taproot Assets, and more. Each one is impressive in its own right, but none have really scaled. What does scaling actually mean? Liquidity. Tens, if not hundreds, of billions of dollars secured under a single standard. We're incredibly opinionated on how this plays out: liquidity will consolidate around stablecoins. The Bitcoin standard that wins will be the one that integrates with every stablecoin issuer, meeting them exactly where they are. From the biggest players to the most niche issuers, adoption at scale is the only thing that matters. And yet, today? Not a single major stablecoin issuer has been onboarded. Zero. If someone tells you they're planning to? Look at the fine print. Implementation details have a way of disappearing when it's time to ship. We evaluated everything and came to a clear conclusion: we needed to build something new. We saw an opportunity to focus on making tokens that actually work the way people expect them to work. So we built BTKN (Bitcoin Token) from first principles. It combines the best ideas from across the ecosystem with new innovations that only became possible on Spark. The result is a token standard that's native to Bitcoin, optimized for speed, and ready to onboard any asset types on Bitcoin. # Minting Source: https://docs.spark.money/learn/tokens/minting Minting creates new tokens. Only the issuer can mint. ## How it works The issuer signs a transaction saying "create X tokens and give them to Y address." Spark Operators verify the signature, confirm it doesn't exceed max supply, and commit the transaction. New tokens now exist. That's it. No on-chain transaction. No gas. Instant. ## What gets checked | Check | Why | | - | - | | Issuer signature | Only the issuer key can create tokens | | Token exists | You have to create (register) the token first | | Max supply | Can't mint beyond the cap you set | | Not frozen | Frozen issuers can't mint | ## Mint vs Create People confuse these. **Create** registers a new token type. You do this once. You define the name, ticker, decimals, max supply. **Mint** creates new units of an existing token. You do this whenever you want more tokens in circulation. ## Supply If you set a max supply during creation, you can't mint beyond it. If you didn't set one, you can mint forever. Most stablecoin issuers mint on-demand: user deposits \$100, issuer mints 100 tokens. Supply grows with demand. ## Where tokens go By default, minted tokens go to the issuer's address. You can also mint directly to someone else's address. Useful for airdrops or when you're minting in response to a deposit. ## Common patterns **Premint everything**: Mint total supply upfront, then distribute via transfers. Simple accounting. **Mint on demand**: Mint as users onboard. Better for stablecoins where supply should match deposits. **Batch mint**: Send to multiple recipients in one transaction. More efficient. # Transferring Source: https://docs.spark.money/learn/tokens/transferring Transfers move tokens between people. They're instant and final. ## How it works You have token outputs (TTXOs). To send tokens, you spend some outputs and create new ones for the recipient. If you're sending less than what's in your outputs, you get change back. ``` Alice has: 100 tokens (one output) Alice sends: 75 tokens to Bob Result: Bob gets: 75 tokens (new output) Alice gets: 25 tokens (change output) Original 100-token output: gone (revoked) ``` The math has to balance. Inputs = outputs. No tokens created or destroyed. ## Why it's instant No on-chain transaction. No block confirmations. The transfer happens the moment Spark Operators commit it. Bob can spend those tokens immediately. ## Input selection When you have multiple outputs, the SDK picks which ones to spend. Two strategies: **Small first** (default): Spends your smallest outputs first. Over time, this consolidates your holdings into fewer, larger outputs. **Large first**: Spends your biggest outputs first. Useful if you want to preserve small outputs for exact-amount payments later. You can also pick specific outputs manually if you care. ## Sending to multiple people You can send to multiple recipients in one transaction. More efficient than separate transfers. One round trip to operators instead of many. ## Consolidation If you have lots of small outputs, transfer everything to yourself. You'll end up with one output instead of many. Cleaner, faster, cheaper to exit to L1 if you ever need to. ## Limits | Limit | Value | | - | - | | Max inputs per transaction | 500 | | Max outputs per transaction | 500 | | Validity window | 300 seconds | If you need to spend more than 500 inputs, split into multiple transactions. ## Finality Once operators commit, it's done. The only way to "reverse" is if the recipient sends tokens back voluntarily. There's no chargeback, no undo, no dispute process at the protocol level. # Transfers on Spark Source: https://docs.spark.money/learn/transfers Leaf ownership is transferred by adjusting the SE's key such that the combined key (SE+User) remains the same before and after the transfer, but control shifts from the sender to the receiver.

Original Combined Key:\ $(\text{PubKey}_{\text{Combined}} = \text{PubKey}_{\text{Sender}} + \text{PubKey}_{\text{SE}})$ After Transfer:\ $(\text{PubKey}_\text{Combined} = \text{PubKey}_\text{Receiver} + \text{PubKey}'_\text{SE})$ We do this by tweaking the SE key with the difference between the sender and receiver private keys. Note that no private keys are ever revealed through this process.

### Transfer Process

To transfer ownership of a leaf, the SE adjusts its key so that the combined public key (SE + User) remains the same, but control shifts from the sender to the receiver. This is achieved by the SE tweaking its key by the difference between the sender's and receiver's private keys. By doing so, the SE's new key, when combined with the receiver's key, equals the original combined key, ensuring the UTXO can still be spent under the original spending conditions. This key adjustment allows the transfer of control without revealing any private keys or requiring an on-chain transaction. The SE securely deletes the old private key associated with the sender and collaborates with the receiver to sign a new exit transaction with a lower timelock than the previous one. This process effectively transfers control of the leaf to the receiver, who now has full control over the UTXO.

# Trust Model Source: https://docs.spark.money/learn/trust-model Spark operates under a “moment-in-time” trust model, meaning that trust is only required at the time of a transaction. As long as at least one (or a configurable threshold) of the Spark operators behaves honestly during a transfer, the system ensures perfect forward security. Even if operators are later compromised or act maliciously, they cannot retroactively compromise past transactions or take money from users. This security is achieved through a fundamental action required of SOs: forgetting the operator key after a transfer. If an operator follows this protocol, the transferred funds are secure, even against future coercion or hacking. Spark strengthens this model by using multiple operators, ensuring that as long as one (or the required threshold) deletes their key, users remain secure and have perfect forward security. This approach contrasts with most other Layer 2 solutions, where operators retain the ability to compromise user funds until they exit the system. The only exception is Lightning, which requires no trusted entities at all. # Withdrawals to L1 Source: https://docs.spark.money/learn/withdrawals There are two ways to exit Spark and withdraw funds to Bitcoin L1: cooperative and unilateral exits. ### Cooperative Exit

In a cooperative exit, the user and SE work together to create a new transaction that spends directly from the deposit transaction to the user's desired Bitcoin address. This is the most efficient and cost-effective method, as it requires only a single on-chain transaction. 1. **Transaction Creation:** The user and SE collaborate to create a transaction that spends from the deposit transaction's output directly to the user's desired Bitcoin address. 2. **Signing:** Both the user and SE sign this transaction using their respective private keys. 3. **Broadcasting:** The signed transaction is broadcast to the Bitcoin network. 4. **Confirmation:** Once confirmed, the funds are available in the user's Bitcoin address.

### Unilateral Exit

If the SE is unavailable or uncooperative, the user can perform a unilateral exit using the pre-signed exit transactions created during the deposit and transfer processes. 1. **Broadcasting Branch Transaction:** The user broadcasts the branch transaction that was signed during the deposit process. 2. **Waiting for Confirmation:** Once the branch transaction is confirmed, the user waits for the relative timelock to expire. 3. **Broadcasting Exit Transaction:** After the timelock expires, the user broadcasts the exit transaction that was signed during the deposit or most recent transfer. 4. **Confirmation:** Once confirmed, the funds are available in the user's Bitcoin address.

The unilateral exit process ensures that users always have control over their funds, even if the SE becomes unavailable or malicious. This is a critical aspect of Spark's self-custody design, providing users with the security and sovereignty that Bitcoin was designed to offer.

# Create a Wallet Source: https://docs.spark.money/quickstart/create-wallet Create a self-custodial Bitcoin wallet on Spark, fund it, and send your first payment.

Get up and running with Spark in minutes. This quickstart guide will walk you through creating your first Spark wallet, funding it with Bitcoin, and making your first transaction on Spark. *** Launch the Spark CLI with a single command. Requires Node.js 20+. ```bash CLI theme={null} npx @buildonspark/cli ``` Or install it globally: ```bash CLI theme={null} npm install -g @buildonspark/cli spark-cli ``` Create your first wallet on Spark: ```bash CLI theme={null} > initwallet ``` Example output: ```bash CLI theme={null} Mnemonic: please broccoli hole unfold trigger novel marriage come invest need ostrich never Network: REGTEST ``` Important: Keep your mnemonic securely stored offline. Anyone with access to it can take full control of your funds. To recover an existing wallet: ```bash CLI theme={null} > initwallet ``` Generate a static deposit address: ```bash CLI theme={null} > getstaticdepositaddress bcrt1pz5sxkd4eaycla7av8c9avmdleyertmhkh2zf60vrmn346wwnjayq8phsra ``` You’ll get a static Bitcoin L1 deposit address linked to your wallet, it can’t be changed. Try it out in our Regtest environment using some monopoly money from the [faucet](https://app.lightspark.com/regtest-faucet). After depositing Bitcoin from the faucet, get the associated transaction hash: ```bash CLI theme={null} > getlatesttx # Example: > getlatesttx bcrt1pz5sxkd4eaycla7av8c9avmdleyertmhkh2zf60vrmn346wwnjayq8phsra 2c5ccdc5852eb23662344c142970a1d96f2bed539a1be074cbbff65411ba3270 ``` Once the transaction is confirmed on-chain, you can claim it. To claim your Bitcoin on Spark, start by requesting a quote: ```bash CLI theme={null} > claimstaticdepositquote # Example: > claimstaticdepositquote 2c5ccdc5852eb23662344c142970a1d96f2bed539a1be074cbbff65411ba3270 ``` With the quote info ready, you can now claim your Bitcoin. ```bash CLI theme={null} > claimstaticdeposit # Example: > claimstaticdeposit 2c5ccdc5852eb23662344c142970a1d96f2bed539a1be074cbbff65411ba3270 3901 3045022100a69a1c58893947e46d4310d967c2d7e96f539e3e2656e1c76cbce1b96afc149102200a0aef9518cd0a76c9baecbf60afd52ca4c30d2d8025bcba70288a9df6a39e63 ``` Verify that your balance has increased: ```bash CLI theme={null} > getbalance Sats Balance: 3901 ``` Create a new wallet and fetch its Spark Address. The Spark Address is a static address that can be shared with payers to receive Bitcoin. ```bash CLI theme={null} # Wallet 2 > initwallet Mnemonic: repeat entry hazard estate normal relief pledge act online raw pull bean Network: REGTEST > getsparkaddress sparkrt1pgss95264kxj85cqz8g2cj5f66wy5yhhc0je35f8923de7mk8ttvls7a7x9vp9 ``` Now send from Wallet 1: ```bash CLI theme={null} # Wallet 1 > initwallet > sendtransfer # Example: > sendtransfer 200 sparkrt1pgss95264kxj85cqz8g2cj5f66wy5yhhc0je35f8923de7mk8ttvls7a7x9vp9 ``` That's it. The transfer’s complete. Run `getbalance` on each wallet to confirm the Bitcoin moved. Spark is fully compatible with Lightning. Let's test it by sending a Lightning payment between our 2 wallets. ```bash CLI theme={null} # Wallet 2 - Create invoice > initwallet > createinvoice # Example: > createinvoice 1000 Spark is awesome! ``` ```bash theme={null} # Wallet 1 - Pay invoice > initwallet > payinvoice # Example: > payinvoice lnbcrt10u1p5pqphup[...]cpkql23a 200 ``` The payer specifies the maximum fee they're willing to pay for the invoice (in sats). The SDK then finds the route with the lowest possible fees but it will never exceed that limit. Use `getbalance` on each wallet to verify the payment. You can withdraw Bitcoin from Spark to Bitcoin by sending them to an L1 address. In this example, we’ll withdraw Bitcoin from Wallet 1 and send it to Wallet 2’s L1 address. ```bash CLI theme={null} # Wallet 2 - Get deposit address > initwallet > getstaticdepositaddress ``` Check withdrawal fee: ```bash CLI theme={null} # Wallet 1 - Check fees and withdraw > initwallet > withdrawalfee # Example: > withdrawalfee 15000 bcrt1p6tx52amnr448lv8vyr7fumqt3c2qmlkg4hgvj8swxfcz8cayukvqwk9mu6 ``` If it’s acceptable: ```bash CLI theme={null} > withdraw # Example: > withdraw 15000 bcrt1pslvlzmkwz8f42u8vr2fkhdhyzyh2x5cwy8l0lpdnqr4ptsjrefrq0sd0gl FAST ``` Once the transaction is confirmed, use the same claim process described above to claim your Bitcoin on Spark. # Launch a Token Source: https://docs.spark.money/quickstart/launch-token Create a token on Spark, mint supply, and send your first token transfer.

Create and launch your first token on Spark in minutes. This quickstart will walk you through setting up your wallet, issuing a token, minting supply, and sending your first transfer. All on Spark, without touching L1 or waiting for confirmations. *** Launch the Spark CLI with a single command. Requires Node.js 20+. ```bash CLI theme={null} npx @buildonspark/cli ``` Or install it globally: ```bash CLI theme={null} npm install -g @buildonspark/cli spark-cli ``` Create a wallet to serve as the issuer of your token: ```bash CLI theme={null} > initwallet ``` Example output: ```bash CLI theme={null} Mnemonic: rhythm torch mistake reopen device surround cabin wish snake better blind draft Network: REGTEST ``` Important: Keep your mnemonic safe and offline. The wallet you create here becomes the root of trust for your token. It's the only wallet authorized to mint or burn supply. Launch your token directly on Spark: ```bash CLI theme={null} > createtoken # Example: > createtoken MyToken MTK 6 1000000 false ``` Human-readable name of the token. Short symbol for the token (typically 3–6 characters). Decimal precision used for display and arithmetic. Hard cap on total mintable supply. Whether the issuer can freeze or unfreeze token balances. ```bash CLI theme={null} TxID: 9c5d17acb7fe203ab6342b3f556b4e5f3b4dabe1bca3b0b98b1b3d9cf7d92c4d Token ID: btkn1qv6cps0n0ttm3p4gx62rzty4rjhzqwe5eqv2wlt ``` Spark transaction ID of the token creation. Bech32m token identifier (e.g., btkn1...) used in later operations. Your token now exists on Spark. It's ready for minting and transfers. Bring new tokens into circulation. Only the issuer wallet can mint, up to the max you set before. ```bash CLI theme={null} > minttokens 500000 ``` Example response: ```bash CLI theme={null} Minted: 500000 MTK Remaining mintable: 500000 MTK ``` You can verify the token balance: ```bash CLI theme={null} > gettokenbalance Token: MTK Balance: 500000 ``` Tokens on Spark move instantly and cost nothing. You can choose to create a new wallet to find a sender. ```bash CLI theme={null} # Wallet 2 > initwallet Mnemonic: explain bullet cradle segment lava enable someone lemon bracket fossil invite crash > getsparkaddress sparkrt1pgw6rrt6s4y3xghx6cl5v4mm08eylktaygff62mg8uk3u5zqq2zwqf9t9d0 ``` Then send tokens from your issuer wallet: ```bash CLI theme={null} # Wallet 1 (Issuer) > transfertokens btkn1qv6cps0n0ttm3p4gx62rzty4rjhzqwe5eqv2wlt 100000 sparkrt1pgw6rrt6s4y3xghx6cl5v4mm08eylktaygff62mg8uk3u5zqq2zwqf9t9d0 ``` That’s it. The transfer settles instantly on Spark. # Features Source: https://docs.spark.money/start/features The team behind Spark has spent years building on Bitcoin. After countless iterations, Spark represents our best attempt at creating the definitive platform for builders on Bitcoin. We built it from scratch, with strong opinions on what makes a truly great developer experience. Spark exposes powerful, low-level features for a wide range of use cases. ***

Live

In development

*** ### Something we should be building? Most of what's on this page came from working directly with our builders. If you have a use case that needs something we don't support yet, we want to hear about it. Get in touch # Welcome to Spark Source: https://docs.spark.money/start/overview Spark is the fastest, cheapest, and most UX-friendly way to build financial apps and launch assets natively on Bitcoin. It's a Bitcoin platform that lets developers move Bitcoin and Bitcoin-native assets (including stablecoins) instantly, at near-zero cost, while staying fully connected to Bitcoin’s infrastructure. *** ## Quickstart The fastest way to go from 0 to 1 on Spark
*** ## Build something Spark makes Bitcoin fast enough to build on. Payments, wallets, stablecoins, and whatever comes next.
*** ## Get to know Spark Spark integrates with best-in-class infrastructure partners to help you ship faster
*** ## Building on Spark

# Products Source: https://docs.spark.money/start/products Spark SDKs and developer tools for Bitcoin L2 development. Explore Spark's product ecosystem and offerings. ## Core Products ### Spark Network The foundational layer-2 network for Bitcoin scaling. ### Spark Wallet SDK Developer tools for building Spark-native wallets. ### Spark Issuer SDK Platform for creating and managing tokens on Spark. ## Developer Tools ### Spark CLI Command-line interface for Spark development. ### Spark Explorer Block explorer for the Spark network. ### Spark Faucet Test token distribution for developers. # Use Cases Source: https://docs.spark.money/start/use-cases Spark makes Bitcoin fast enough to build on. We're building the infrastructure that makes Bitcoin the definitive platform for payments, wallets, and stablecoins. Where new kinds of apps can finally exist on the world's most secure ledger. ## Payments Global transfers, tipping, merchant apps, and more payment solutions built on Bitcoin. ## DeFi Liquidity pools, tokenized BTC, swaps, and decentralized finance protocols. ## Rewards Bitcoin cashback, loyalty, micro-incentives, and reward-based applications. # Spark CLI Source: https://docs.spark.money/tools/cli Command-line tool for wallet operations and testing on Spark. # Explorer Source: https://docs.spark.money/tools/explorer Block explorer for viewing Spark transactions and addresses. # Regtest Faucet Source: https://docs.spark.money/tools/faucet Get test Bitcoin for development on Spark regtest. # Test Wallet Source: https://docs.spark.money/tools/test-wallet Browser-based wallet for testing Spark features. A simple test wallet for experimenting with Spark features. ## Features * **Send/Receive** - Test Spark transactions * **Token Management** - Handle multiple token types * **Lightning Integration** - Test Lightning payments * **Developer Tools** - Debug and monitor transactions ## Getting Started 1. **Create Wallet** - Generate a new test wallet 2. **Fund Wallet** - Use the faucet to get test tokens 3. **Start Testing** - Try all Spark features safely ## Test Environment This wallet connects to Spark's testnet, so you can experiment without risk. # Token Lists Source: https://docs.spark.money/tools/token-lists Registry of BTKN tokens on Spark. # 0-Conf Deposits Source: https://docs.spark.money/wallets/0-conf Use the Spark SDK instant static deposit APIs to quote and claim Bitcoin deposits before final confirmation. Instant Bitcoin deposits UI

0-conf deposits make inbound Bitcoin feel instant. Instead of waiting for the normal L1 confirmation threshold before a deposit becomes usable, an enabled integration can quote the transaction, select an available fulfillment plan, and claim the credit as soon as the transaction is accepted for instant funding. For wallets, onramps, bridges, exchanges, and payment apps, this removes the dead time between "BTC sent" and "funds available." Users can keep trading, bridging, spending, or settling while the Bitcoin transaction continues toward final confirmation in the background. 0-conf static deposits are currently gated. Contact the team to enable support for your integration. The first-party JavaScript SDK exposes this flow through: * `wallet.getInstantStaticDepositQuote(transactionId, outputIndex?, partnerId?)` * `wallet.claimInstantStaticDeposit({ quote, plan, transactionId, outputIndex })` These `SparkWallet` methods quote the deposit, return the available funding plans, and claim the selected plan. *** ## Flow Use the same static deposit address flow as a normal L1 deposit. ```typescript theme={null} const depositAddress = await wallet.getStaticDepositAddress(); ``` Broadcast a Bitcoin transaction paying the static deposit address. Record the transaction ID and the output index that pays the Spark deposit address. ```typescript theme={null} const transactionId = "abc123..."; const outputIndex = 0; ``` Ask for an instant static deposit quote. Pass `partnerId` if one has been issued for your integration. ```typescript theme={null} const quoteResult = await wallet.getInstantStaticDepositQuote( transactionId, outputIndex, partnerId ); ``` The quote response includes one or more fulfillment plans. A plan with `confirmations === 0` is the 0-conf path. Plans with higher confirmation counts can also be claimed through the same SDK method. ```typescript theme={null} const plan = quoteResult.fulfillmentPlans.find( (plan) => plan.confirmations === 0 ) ?? quoteResult.fulfillmentPlans[0]; if (!plan) { throw new Error("No instant deposit fulfillment plan available"); } ``` Claim with the quote and selected plan. The SDK signs the correct user statement for the selected plan and submits the instant static deposit claim. ```typescript theme={null} const claim = await wallet.claimInstantStaticDeposit({ quote: quoteResult.quote, plan, transactionId: quoteResult.quote.transactionId, outputIndex: quoteResult.quote.outputIndex, }); console.log("Instant deposit claim:", claim.claimId); ``` *** ## Complete Example ```typescript theme={null} const depositAddress = await wallet.getStaticDepositAddress(); console.log("Send BTC to:", depositAddress); // After the Bitcoin transaction is broadcast: const transactionId = "abc123..."; const outputIndex = 0; const partnerId = "your-partner-id"; // Optional. Use only if Spark provides one. const quoteResult = await wallet.getInstantStaticDepositQuote( transactionId, outputIndex, partnerId ); const zeroConfPlan = quoteResult.fulfillmentPlans.find( (plan) => plan.confirmations === 0 ); if (!zeroConfPlan) { throw new Error("0-conf is not available for this deposit"); } const claim = await wallet.claimInstantStaticDeposit({ quote: quoteResult.quote, plan: zeroConfPlan, transactionId: quoteResult.quote.transactionId, outputIndex: quoteResult.quote.outputIndex, }); console.log("Claim ID:", claim.claimId); ``` *** ## Quote Response `getInstantStaticDepositQuote` returns: ```typescript theme={null} type InstantStaticDepositQuoteOutput = { quote: { id: string; network: BitcoinNetwork; transactionId: string; outputIndex: number; depositAmount: CurrencyAmount; creditAmount: CurrencyAmount; quoteSignature: string; }; fulfillmentPlans: Array<{ id: string; amount: CurrencyAmount; confirmations: number; status: string; transferSparkId: string | null; }>; }; ``` Use `quote.creditAmount.originalValue` when you need the credited sat amount. Use `plan.confirmations` to distinguish the 0-conf plan from plans that require one or more confirmations. *** ## Claim Response `claimInstantStaticDeposit` returns: ```typescript theme={null} type InstantStaticDepositClaim = { claimId: string; }; ``` After claiming, monitor wallet balance, transfer state, or your own deposit workflow using your normal Spark wallet integration. *** ## Notes * The deposit must be to a static deposit address from `getStaticDepositAddress()`. * Pass `outputIndex` when you know it. The quote method can auto-detect it, but the claim call requires an output index. * 0-conf availability is determined by the quote and fulfillment plans. If the deposit is not eligible or your integration is not enabled, the quote or claim may fail. ## Related APIs * [`getInstantStaticDepositQuote`](/api-reference/wallet/get-instant-static-deposit-quote) * [`claimInstantStaticDeposit`](/api-reference/wallet/claim-instant-static-deposit) * [`getStaticDepositAddress`](/api-reference/wallet/get-static-deposit-address) * [`getClaimStaticDepositQuote`](/api-reference/wallet/get-claim-static-deposit-quote) # Addressing Source: https://docs.spark.money/wallets/addressing Spark doesn't force a single address format on your users. Depending on what you're building, your users might interact with standard Bitcoin taproot addresses, Lightning invoices, Spark addresses, or none of the above. You choose what to expose. *** ## Address types ### Bitcoin taproot addresses Every Spark wallet has a standard Bitcoin taproot address (`bc1p...` on mainnet) for L1 deposits. This is the same address format used by any Bitcoin wallet. Your users can receive Bitcoin from Coinbase, a hardware wallet, or any on-chain source. On test networks you'll see different prefixes: `tb1p...` (testnet/signet) and `bcrt1p...` (regtest/local). ```typescript theme={null} const depositAddress = await wallet.getStaticDepositAddress(); // bc1p5d7rjq7g6rdk2yhzks9smtbqtedr4dekq08ge8ztwac72sfr9rusxg3297 ``` This means a Spark-powered app can function as a full L1 Bitcoin wallet. Users deposit to a taproot address, hold Bitcoin on Spark, and withdraw back to L1 whenever they want. ### Lightning invoices Spark wallets can create and pay Lightning invoices without running a node or managing channels. Some apps only expose Lightning. Users never see a Spark address or know Spark exists. ```typescript theme={null} // Create a Lightning invoice const { invoice } = await wallet.createLightningInvoice({ amountSats: 50000, memo: "Payment for order #1234", }); // Pay a Lightning invoice const payment = await wallet.payLightningInvoice({ invoice: "lnbc500u1p...", }); ``` ### Spark addresses Spark addresses are Bech32m-encoded identifiers that map to a wallet's identity public key. Think of them as user IDs. They identify a wallet on the Spark network. Transfers between Spark addresses are instant and free. ```typescript theme={null} const sparkAddress = await wallet.getSparkAddress(); // spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` Most wallets don't expose Spark addresses to end users. They're useful behind the scenes for free, instant transfers between your own users, between services, or for settlement between apps. *** ## What to expose Spark is modular. Pick the addressing that fits your use case: | Use case | What users see | What Spark does behind the scenes | | - | - | - | | **Bitcoin wallet** | Taproot address (`bc1p...` / `tb1p...` / `bcrt1p...`) | L1 deposits, Spark balance, L1 withdrawals | | **Payments app** | Lightning invoices | Spark handles routing, no node needed | | **Exchange / fintech** | Nothing (internal accounts) | Spark addresses for free internal transfers | | **P2P transfers** | Spark addresses or usernames | Instant, free Spark-to-Spark settlement | The point: Spark adapts to your product. It can be a full L1 wallet, a Lightning payments backend, a free internal ledger, or all three at once. Your users don't need to know what's underneath. *** ## Spark address format For developers working directly with Spark addresses, here's the format: ```typescript MAINNET theme={null} spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` ```typescript REGTEST theme={null} sparkrt1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` ```typescript TESTNET theme={null} sparkt1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` ```typescript SIGNET theme={null} sparks1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` ```typescript LOCAL theme={null} sparkl1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu ``` ### Network prefixes | Network | Prefix | Availability | | - | - | - | | **Mainnet** | `spark` | Available | | **Regtest** | `sparkrt` | Available | | **Testnet** | `sparkt` | Coming soon | | **Signet** | `sparks` | Coming soon | | **Local** | `sparkl` | Available | ### Key facts * Derived from your wallet's network and identity public key * Same wallet always produces the same Spark address * Network-specific. A mainnet wallet and regtest wallet will have different addresses # API Reference Source: https://docs.spark.money/wallets/api-reference # Balances & Activity Source: https://docs.spark.money/wallets/balances Query balances, view transfer history, and monitor wallet activity in real-time.

*** ## Check Wallet Balance Get your current Bitcoin balance and token holdings in your Spark wallet. getBalance() Gets the current balance of the wallet, including Bitcoin balance and token balances. ```typescript theme={null} const balance = await wallet.getBalance(); console.log("Available:", balance.satsBalance.available, "sats"); console.log("Owned:", balance.satsBalance.owned, "sats"); console.log("Incoming:", balance.satsBalance.incoming, "sats"); console.log("Token Balances:", balance.tokenBalances); ``` Bitcoin balances in satoshis: `available` (spendable), `owned` (includes funds locked in outgoing transfers and swaps), and `incoming` (pending inbound transfers not yet claimed). Map of Bech32m token identifiers to token balance objects. Each balance includes `ownedBalance` (total owned), `availableToSendBalance` (excludes pending transfers), and token metadata. *** ## Received does not mean spendable An incoming Bitcoin transfer must be claimed by the receiving wallet before it becomes owned and available. A payment to an offline receiver can appear in `getPendingTransfers()` while both read-only `getAvailableBalance()` and `getOwnedBalance()` remain zero. The read-only client cannot claim it. An initialized `SparkWallet` claims incoming transfers automatically. Use `satsBalance.incoming` for pending funds known to the wallet, and `transfer:claimed` followed by a balance refresh to update spendable funds. A Lightning receive request reaching `TRANSFER_COMPLETED` is not a substitute for checking the receiving wallet’s balance. `owned` is not “available plus every incoming payment.” Show pending receipts separately, and use `available` when deciding whether a payment can be sent. ## View Transfer History Track all incoming and outgoing transfers for your wallet with pagination support. getTransfers(limit?, offset?) Gets all transfers for the wallet with optional pagination. `getTransfers()` includes Spark transfers, Lightning sends/receives, and cooperative exits. For token transaction details (e.g., sender address), use [`queryTokenTransactionsWithFilters()`](/api-reference/wallet/query-token-transactions-with-filters). ```typescript theme={null} // Get first 20 transfers const transfers = await wallet.getTransfers(); console.log("Transfers:", transfers.transfers); // Get next 10 transfers with pagination const nextTransfers = await wallet.getTransfers(10, 20); console.log("Next page:", nextTransfers.transfers); // Get transfers from the last 24 hours const yesterday = new Date(Date.now() - 24 * 60 * 60 * 1000); const recentTransfers = await wallet.getTransfers(50, 0, yesterday); ``` Maximum number of transfers to return (default: 20) Offset for pagination (default: 0) Only return transfers created after this date (mutually exclusive with `createdBefore`) Only return transfers created before this date (mutually exclusive with `createdAfter`) Array of transfer objects containing transfer details The offset used for this request *** For newest-first token history, use the [cursor pagination example](/api-reference/wallet/query-token-transactions-with-filters#newest-first-activity). ## Real-time Event Monitoring Monitor wallet activity in real-time using EventEmitter methods for instant updates. on(event, listener) Adds a listener for the specified event to monitor wallet activity. ```typescript theme={null} // Listen for incoming transfer claims wallet.on("transfer:claimed", (transferId, updatedBalance) => { console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance}`); }); // Listen for deposit confirmations (after 3 L1 confirmations) wallet.on("deposit:confirmed", (depositId, updatedBalance) => { console.log(`Deposit ${depositId} confirmed. New balance: ${updatedBalance}`); }); ``` The event name to listen for (e.g., "transfer:claimed", "deposit:confirmed") The callback function to execute when the event is emitted The SparkWallet instance for method chaining once(event, listener) Adds a one-time listener for the specified event. ```typescript theme={null} // Listen for a single incoming transfer wallet.once("transfer:claimed", (transferId, updatedBalance) => { console.log(`Transfer ${transferId} claimed! New balance: ${updatedBalance}`); }); ``` The event name to listen for The callback function to execute when the event is emitted The SparkWallet instance for method chaining off(event, listener) Removes the specified listener from the specified event. ```typescript theme={null} // Remove a specific listener const handleTransfer = (transferId) => console.log(`Transfer: ${transferId}`); wallet.on("transfer:claimed", handleTransfer); // Later, remove the listener wallet.off("transfer:claimed", handleTransfer); ``` The event name to remove the listener from The specific callback function to remove The SparkWallet instance for method chaining *** ## Available Events Spark wallets emit various events for different types of activity: #### Available Events | Event | Description | | - | - | | `transfer:claimed` | Emitted when an **incoming** transfer is claimed | | `deposit:confirmed` | Emitted when a pending L1 deposit becomes spendable | | `stream:connected` | Emitted when the event stream connects | | `stream:disconnected` | Emitted when the stream disconnects | | `stream:reconnecting` | Emitted when attempting to reconnect | Events only fire for **incoming** funds. For outgoing operations (Lightning sends, withdrawals), poll the status using `getLightningSendRequest()` or `getCoopExitRequest()`. *** ## Use Sparkscan Explorer Monitor your wallet activity using the Sparkscan block explorer for a visual interface. Sparkscan provides a web interface to view your wallet's transaction history, balance, and activity without needing to implement the API calls yourself. *** ## Example: Complete Balance Monitoring ```typescript theme={null} import { SparkWallet } from "@buildonspark/spark-sdk"; async function setupBalanceMonitoring() { const { wallet } = await SparkWallet.initialize({ options: { network: "REGTEST" } }); // Get initial balance const balance = await wallet.getBalance(); console.log("Initial balance:", balance.satsBalance.available, "sats"); // Set up event listeners wallet.on("transfer:claimed", (transferId, newBalance) => { console.log(`Transfer ${transferId} claimed. New balance: ${newBalance} sats`); }); // Get recent transfers const transfers = await wallet.getTransfers(10); console.log("Recent transfers:", transfers.transfers); return wallet; } ``` # Create a Wallet Source: https://docs.spark.money/wallets/create-wallet Create and initialize Spark wallets with full key control.

*** ## Initialize Wallet The `initialize` method is the primary way to create or restore a Spark wallet. Leave `mnemonicOrSeed` blank to generate a new wallet, or provide an existing mnemonic seed phrase to import an existing wallet. ```typescript Create Wallet theme={null} import { SparkWallet } from "@buildonspark/spark-sdk"; // Create a new wallet const { wallet, mnemonic } = await SparkWallet.initialize({ options: { network: "REGTEST" // or "MAINNET" } }); console.log("New wallet created!"); console.log("Mnemonic:", mnemonic); console.log("Address:", await wallet.getSparkAddress()); ``` ```typescript Import Wallet theme={null} import { SparkWallet } from "@buildonspark/spark-sdk"; // Restore wallet from existing mnemonic const { wallet } = await SparkWallet.initialize({ mnemonicOrSeed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about", accountNumber: 0, // Optional: specify account index options: { network: "REGTEST" // or "MAINNET" } }); console.log("Wallet restored from mnemonic!"); console.log("Address:", await wallet.getSparkAddress()); ``` BIP-39 mnemonic phrase or raw seed. Leave blank to generate a new wallet. Account index for generating multiple identity keys from the same mnemonic (default: 0 on REGTEST, 1 on MAINNET). **Important:** Always specify this explicitly if you use the same mnemonic across networks. Custom signer implementation for advanced use cases Wallet configuration options including network selection The initialized SparkWallet instance The 12-word mnemonic seed phrase for wallet recovery (undefined for raw seed) *** ## Essential Wallet Operations After creating your wallet, you can perform these essential operations getIdentityPublicKey() Gets the identity public key of the wallet ```typescript theme={null} const identityKey = await wallet.getIdentityPublicKey(); console.log("Identity Public Key:", identityKey); ``` The identity public key as a hex string getSparkAddress() Gets the Spark address of the wallet ```typescript theme={null} const sparkAddress = await wallet.getSparkAddress(); console.log("Spark Address:", sparkAddress); ``` The Spark address for receiving Bitcoin and tokens getBalance() Gets the current balance of the wallet, including Bitcoin and token balances. ```typescript theme={null} const balance = await wallet.getBalance(); console.log("Balance:", balance.satsBalance.available, "sats"); console.log("Token Balances:", balance.tokenBalances); ``` Bitcoin balances in satoshis: `available`, `owned`, and `incoming`. Use `available` for spendable funds. Map of Bech32m token identifiers to token balance and metadata. `UserTokenMetadata` includes `extraMetadata?: Uint8Array` for arbitrary issuer-defined bytes. cleanup() Initialization starts an active wallet: it subscribes to events, claims incoming transfers, and runs periodic maintenance such as token-output optimization. This also applies to a wallet used only to create invoices for other users. For queries alone, use [`SparkReadonlyClient`](/wallets/readonly-client). Automatic token-output optimization is enabled by default. To disable that task, pass `tokenOptimizationOptions: { enabled: false }` inside the initialization `options`. The wallet still subscribes to events and claims incoming transfers; this is not a read-only mode. Call `cleanup()` when the wallet is no longer needed. It clears background intervals, aborts streams, removes listeners, and closes connections. Open resources can keep a Node.js script alive after its main function finishes. ```typescript theme={null} try { console.log(await wallet.getSparkAddress()); // Perform this script’s wallet work here. } finally { await wallet.cleanup(); } ``` No return value - cleans up connections and aborts active streams *** ## Network Configuration Spark supports both mainnet and regtest networks: ```typescript Mainnet theme={null} const { wallet } = await SparkWallet.initialize({ options: { network: "MAINNET" } }); // Use for production applications ``` ```typescript Regtest theme={null} const { wallet } = await SparkWallet.initialize({ options: { network: "REGTEST" } }); // Use for development and testing ``` Always use REGTEST for development and testing. Only use MAINNET for production applications with real Bitcoin. **Account number defaults differ by network.** REGTEST defaults to account 0, MAINNET defaults to account 1. If you test on REGTEST without specifying `accountNumber`, then deploy to MAINNET with the same mnemonic, your wallet will be empty because funds are on a different account. Always explicitly set `accountNumber` for consistent behavior. *** ## Account Derivation You can create multiple accounts from the same mnemonic by specifying different account numbers: ```typescript theme={null} // Account 0 (default) const wallet0 = await SparkWallet.initialize({ mnemonicOrSeed: "your mnemonic here", accountNumber: 0 }); // Account 1 const wallet1 = await SparkWallet.initialize({ mnemonicOrSeed: "your mnemonic here", accountNumber: 1 }); // Each account will have different addresses console.log("Account 0:", await wallet0.getSparkAddress()); console.log("Account 1:", await wallet1.getSparkAddress()); ``` *** ## API Reference ```typescript theme={null} SparkWallet.initialize({ mnemonicOrSeed?: Uint8Array | string, // Optional: existing mnemonic or seed accountNumber?: number, // Optional: account index (default: 0) signer?: SparkSigner, // Optional: custom signer implementation options?: { network?: "MAINNET" | "TESTNET" | "SIGNET" | "REGTEST" | "LOCAL" } }) // Returns: { wallet: SparkWallet, mnemonic: string | undefined } ``` **Wallet Methods:** ```typescript theme={null} // Initialize wallet with mnemonic or seed initialize({ mnemonicOrSeed, signer, options }) // Get the identity public key getIdentityPublicKey() // Get the Spark address getSparkAddress() // Clean up connections cleanup() ``` # Deposit from L1 Source: https://docs.spark.money/wallets/deposit-from-l1 Deposit Bitcoin from L1 using reusable static addresses.

*** ## Deposit Flow The complete process for receiving on-chain Bitcoin into a Spark wallet: Create a static deposit address that can be reused for multiple deposits. ```typescript theme={null} const staticAddress = await wallet.getStaticDepositAddress(); console.log("Static Deposit Address:", staticAddress); ``` Send Bitcoin from any wallet to your deposit address. ```typescript theme={null} // For mainnet: Send real Bitcoin to the address // For regtest: Use the faucet console.log("Send Bitcoin to:", staticAddress); ``` Wait for the transaction to be confirmed on the blockchain. ```typescript theme={null} // Monitor using a block explorer or your infrastructure // You need to monitor the address for new transactions ``` Claim the deposit once it has 3 confirmations. ```typescript theme={null} const quote = await wallet.getClaimStaticDepositQuote(txId); const claimResult = await wallet.claimStaticDeposit({ transactionId: txId, creditAmountSats: quote.creditAmountSats, sspSignature: quote.signature }); ``` *** ## Generate Static Deposit Address For Bitcoin deposits on L1, Spark generates P2TR addresses. These addresses start with `bc1p...` on mainnet, `tb1p...` on testnet/signet, and `bcrt1p...` on regtest/local. Static deposit addresses are reusable, allowing the same address to receive multiple deposits. This approach is user-friendly, minimizes operational overhead, and is ideal for production applications. ```typescript theme={null} const staticDepositAddress = await wallet.getStaticDepositAddress(); console.log("Static Deposit Address:", staticDepositAddress); // This address can be reused for multiple deposits ``` **Mainnet Address Example** `bc1p5d7rjq7g6rdk2yhzks9smtbqtedr4dekq08ge8ztwac72sfr9rusxg3297` *** ## Deposit Bitcoin #### Mainnet Deposits To deposit Bitcoin on the mainnet, send funds to your static deposit address. #### Regtest Deposits For testing purposes on the Regtest network, use the faucet to fund your Spark wallet without using real Bitcoin. If you have custom L1 requirements like confirmation thresholds, transaction chaining, or specific coin selection, [talk to our team](https://www.spark.money/contact). We can expose lower-level controls to fit your infrastructure needs. ## Monitor for Deposit Transactions After sending Bitcoin to your deposit address, you'll need to monitor for incoming transactions using a blockchain explorer or your own infrastructure. ```typescript theme={null} const staticAddress = await wallet.getStaticDepositAddress(); // Example: Monitor for new transactions using a block explorer API // const newTransactions = await yourBlockchainMonitor.checkAddress(staticAddress); ``` Since static addresses can receive multiple deposits, you need to actively monitor the address for new transactions. *** ## Claiming Deposits Once a deposit is found on the blockchain, you can claim it by providing the transaction ID. ```typescript theme={null} // Step 1: Get a quote for your deposit (can be called anytime after transaction) const quote = await wallet.getClaimStaticDepositQuote(txId); console.log("Quote:", quote); // Step 2: Claim the deposit using the quote details const claimResult = await wallet.claimStaticDeposit({ transactionId: txId, creditAmountSats: quote.creditAmountSats, sspSignature: quote.signature }); console.log("Claim successful:", claimResult); ``` You can call `getClaimStaticDepositQuote` anytime after the deposit transaction is made, but `claimStaticDeposit` will only succeed after the deposit transaction has 3 confirmations. If you'd like to receive faster, [get in touch](https://www.spark.money/contact). We can do 0-1 conf as well. *** ## Sending Back to L1 Since your Spark wallet has a standard Bitcoin address, you can also send funds back on-chain without claiming them into Spark first: ```typescript theme={null} // Refund a static deposit const refundTxHex = await wallet.refundStaticDeposit({ depositTransactionId: txId, destinationAddress: "bc1p...", satsPerVbyteFee: 10 }); // You'll need to broadcast this transaction yourself console.log("Refund transaction hex:", refundTxHex); // Or use refundAndBroadcastStaticDeposit to broadcast automatically const txid = await wallet.refundAndBroadcastStaticDeposit({ depositTransactionId: txId, destinationAddress: "bc1p...", satsPerVbyteFee: 10 }); ``` **When to use this:** * You want to forward funds to another Bitcoin address directly * You'd rather skip the claim fee * You're using Spark as a receiving address but want to settle on L1 ## Confirmation Requirements * By default, deposits require **3 confirmations** on L1 * 0-1 confirmation deposits are available. [Get in touch](https://www.spark.money/contact) to enable faster settlement * Funds will be available in your Spark wallet after claiming ## Minimum Deposit Amount The minimum deposit must exceed the dust limit plus fees: * **Dust limit:** \~400 sats * **Claim fee:** \~99 sats (varies with network conditions) Deposits below \~500 sats may fail with "utxo amount minus fees is less than the dust amount". **Important:** Static deposits do NOT auto-claim when your wallet is offline. If a deposit confirms while your wallet instance is not running, you must manually claim it using `claimStaticDeposit()` with the transaction ID when you next initialize the wallet. # Deposit from Lightning Source: https://docs.spark.money/wallets/deposit-from-lightning Receive Bitcoin via Lightning invoices with instant settlement into Spark.

*** ## Understanding Lightning Invoices To send and receive Lightning payments, you can generate and pay Lightning invoices. A Lightning invoice (also called a payment request) is a specially formatted string that contains all the information needed to make a Lightning Network payment: * **Amount**: How many satoshis to send (can be omitted for zero-amount invoices) * **Destination**: The recipient's node public key * **Payment Hash**: A unique identifier for the payment * **Description**: Optional memo describing the payment * **Expiry**: How long the invoice is valid for (use the returned `invoice.expiresAt`) Lightning invoices start with "ln" followed by the network identifier (bc for mainnet) and typically look like this: `lnbc1...` *** ## Lightning Deposit Flow The complete process for receiving Lightning payments into your Spark wallet: Generate a Lightning invoice with the desired amount and description. ```typescript theme={null} const invoice = await wallet.createLightningInvoice({ amountSats: 50000, memo: "Deposit to Spark wallet" }); ``` Provide the invoice to the sender (via QR code, link, or text). ```typescript theme={null} // Display invoice for user to share console.log("Share this invoice:", invoice.invoice.encodedInvoice); // Save invoice.id in your application; it is a lookup ID, not a payable invoice. ``` Track the payment status until completion. ```typescript theme={null} // Poll for payment status const checkPayment = async (invoiceId: string) => { const request = await wallet.getLightningReceiveRequest(invoiceId); if (!request) { console.log("Request unavailable: check the ID and querying wallet"); return false; } console.log("Receive status:", request.status); // This is the Lightning receive request status; check the receiver's balance for spendability. return request.status === "TRANSFER_COMPLETED"; }; ``` *** ## Create Lightning Invoice Generate Lightning invoices to receive Bitcoin payments that will be deposited into your Spark wallet. createLightningInvoice(params) Creates a Lightning invoice for receiving Bitcoin payments. ```typescript theme={null} const invoice = await wallet.createLightningInvoice({ amountSats: 10000, // Amount in satoshis memo: "Payment for services", // Optional description includeSparkAddress: true // Optional: embed Spark address }); console.log("Lightning invoice:", invoice.invoice.encodedInvoice); console.log("Invoice ID:", invoice.id); ``` The amount in satoshis to request Optional memo/description for the invoice (max 120 bytes). Cannot be used with `descriptionHash`. Whether to embed Spark address in the invoice fallback field. Mutually exclusive with `includeSparkInvoice`. Whether to include a Spark invoice in the invoice routing hints. Mutually exclusive with `includeSparkAddress`. Optional: 33-byte compressed identity pubkey for other Spark users Optional: Hash of a longer description (h tag). Used in LNURL/UMA. Cannot be used with `memo`. Unique identifier for the invoice (e.g., `SparkLightningReceiveRequest:...`) Lightning invoice object containing: * `encodedInvoice`: The BOLT11-encoded string (e.g., `lnbc1...`) * `bitcoinNetwork`: Network identifier (`MAINNET` or `REGTEST`) * `paymentHash`: Unique payment identifier * `amount`: Object with `originalValue` (millisatoshis) and `originalUnit` * `createdAt`: Invoice creation timestamp * `expiresAt`: Invoice expiration timestamp * `memo`: Base64-encoded memo string Invoice status (e.g., `INVOICE_CREATED`, `TRANSFER_COMPLETED`) *** ## Spark Payment Integration Spark provides two ways to enable Spark-based payments alongside Lightning invoices: ### Option 1: Spark Invoice in Routing Hints By setting `includeSparkInvoice: true`, a Spark invoice is embedded in the routing hints section of the BOLT11 invoice. This allows Spark-compatible wallets to automatically detect and pay over Spark instead of Lightning, providing a seamless user experience: ```typescript theme={null} const invoice = await wallet.createLightningInvoice({ amountSats: 100, memo: "Invoice with Spark support", includeSparkInvoice: true, }); console.log("Invoice with Spark routing:", invoice); ``` When a payer uses this invoice: * Spark-compatible wallets can pay directly over Spark (faster, potentially lower fees) * Non-Spark wallets will pay via Lightning as normal * The payment is correlated to the original invoice ### Option 2: Spark Address in Fallback Field By passing in `true` for `includeSparkAddress`, a 36-byte string consisting of a recognizable header and a receiver's compressed identity public key `SPK:identitypubkey` will get embedded in the fallback address (f) field of a BOLT11 invoice: ```typescript theme={null} const invoice = await wallet.createLightningInvoice({ amountSats: 100, memo: "Invoice with Spark address", includeSparkAddress: true, }); console.log("Invoice with Spark address:", invoice); ``` ### Fallback Address Format The embedded Spark address in the fallback field will look something like this: ```javascript theme={null} { version: 31, address_hash: "53504b0250949ec35b022e3895fd37750102f94fe813523fa220108328a81790bf67ade5" } ``` **Important:** These two options are mutually exclusive. You cannot use both `includeSparkAddress` and `includeSparkInvoice` in the same invoice. *** ## Creating Invoices for Other Spark Users To generate an invoice for another Spark user, pass in the 33-byte compressed identity pubkey as a string to `receiverIdentityPubkey`: ```typescript theme={null} const invoice = await wallet.createLightningInvoice({ amountSats: 100, memo: "Invoice for another user", receiverIdentityPubkey: "023e33e2920326f64ea31058d44777442d97d7d5cbfcf54e3060bc1695e5261c93", }); console.log("Invoice for another user:", invoice); ``` If a wallet is generating an invoice for itself and wants to embed its own Spark identity in the invoice, it will not need to pass in a `receiverIdentityPubkey` to embed a Spark address. That will get taken care of on the backend. Passing it in shouldn't change anything though. The requesting wallet receives the `SPARK_LIGHTNING_RECEIVE_FINISHED` webhook for an invoice it creates on behalf of someone else. Register the webhook on that wallet; do not assume the receiver alone will receive the notification. The receive-request lookup is restricted to the requester or receiver. Preserve the requesting wallet's identity across process restarts, or query as the receiver. In the SDK, invoice creation uses `SparkWallet`, which also runs background claims and maintenance. See [wallet lifecycle](/wallets/create-wallet). *** ## Zero-Amount Invoices Spark supports creating zero-amount Lightning invoices. Zero-amount invoices don't have a fixed amount and allow the sender to specify the amount when making the payment. Zero-amount invoices are not widely supported across the Lightning Network. Some exchanges, such as Binance, currently do not support them. ### Creating Zero-Amount Invoices To create a zero-amount invoice, pass `0` for the `amountSats` parameter: ```typescript theme={null} // Create a zero-amount invoice const zeroAmountInvoice = await wallet.createLightningInvoice({ amountSats: 0, // Creates a zero-amount invoice memo: "Pay any amount you want", }); console.log("Zero-amount Invoice:", zeroAmountInvoice); ``` *** ## Monitor Lightning Payments Track incoming Lightning payments and their status using receive request monitoring. getLightningReceiveRequest(id) Gets the status of a Lightning receive request by ID. ```typescript theme={null} // Monitor a specific invoice const receiveRequest = await wallet.getLightningReceiveRequest(invoiceId); if (!receiveRequest) { throw new Error("Receive request not found or not accessible to this wallet"); } console.log("Payment status:", receiveRequest.status); console.log("Transfer amount:", receiveRequest.transfer?.totalAmount); // Check if payment is complete if (receiveRequest.status === "TRANSFER_COMPLETED") { console.log("Payment received successfully!"); } ``` The ID of the Lightning receive request The receive request details, or `null` if not found or not accessible to the querying wallet *** ## Match the invoice, request, and transfer Save the receive request's `id` and `invoice.paymentHash` when creating the invoice. The BOLT11 payment hash identifies the Lightning payment; the Spark transfer ID identifies the movement of funds on Spark. They are different identifiers. Once the receive request has a transfer, `request.transfer.sparkId` links it to operator transfer history: ```typescript theme={null} const request = await wallet.getLightningReceiveRequest(receiveRequestId); if (request?.transfer) { console.log("Lightning payment hash:", request.invoice.paymentHash); console.log("Spark transfer ID:", request.transfer.sparkId); } ``` The operator's `Transfer` does not carry the Lightning payment hash. If you start with a Spark transfer ID, use [`getTransferFromSsp()`](/api-reference/wallet/get-transfer-from-ssp) to retrieve its associated payment request. A plain Lightning receive can have no `sparkInvoice`; that optional field is not the correlation key, and `includeSparkAddress: false` does not populate it. Only the requester or receiver can look up the receive request. An unrelated wallet gets `null`, which does not establish that the invoice does not exist. A viewer grant for Bitcoin history does not grant access to Lightning receive requests. ### Amounts and units | Field | Unit | | - | - | | `createLightningInvoice({ amountSats })` | Satoshis | | `request.invoice.amount` | Read `originalValue` together with `originalUnit`; Lightning invoices use millisatoshis | | `request.transfer.totalAmount` | Currency amount object; Spark transfer amounts use satoshis | | Webhook `htlc_amount` | `{ value, unit }` or `null`; inspect `unit` instead of assuming millisatoshis | | Webhook `invoice_amount` | `{ value, unit }`; normally `SATOSHI` | For example, a 1,000-sat invoice has `originalValue: 1000000` with `originalUnit: "MILLISATOSHI"`. Do not compare bare amount values across these surfaces. The request has no `amountReceived` field. ### Completion and event order A Lightning receive request status such as `PAYMENT_PREIMAGE_RECOVERED` or `TRANSFER_COMPLETED`, an operator transfer status, and the wallet's `transfer:claimed` event describe different steps. A completed Lightning receive request does not establish that the receiver has claimed the funds. See [received versus spendable](/wallets/balances#received-does-not-mean-spendable). The incoming Spark transfer can appear before the receive request is finalized and its webhook is delivered. These describe successive parts of the receive flow. Your application may observe events and lookup responses at different times, so do not require a particular notification arrival order. Persist the identifiers, handle repeated notifications, and re-query the request if its transfer is not yet available. Stream heartbeats are connection activity, not payments; do not depend on a fixed heartbeat interval. For server notifications, see [Webhooks](/wallets/webhooks), including the difference between webhook IDs and SDK request IDs. ## Real-time Payment Monitoring Use event listeners to monitor Lightning payments in real-time. ```typescript theme={null} // Listen for transfer events (Lightning payments trigger transfer events) wallet.on("transfer:claimed", (transferId, updatedBalance) => { console.log(`Transfer ${transferId} claimed. New balance: ${updatedBalance} sats`); }); ``` # Estimate Fees Source: https://docs.spark.money/wallets/estimate-fees Fee breakdown for Lightning payments, cooperative exits, and swaps. ***
`For Bitcoin`

Transaction Type	Fee structure
L1 to Spark	On-chain fee paid by the user
Spark to Spark	Free. Small flat fee coming in 6-12 months
Spark to Lightning	0.25% + routing fee
Lightning to Spark	Free for the receiver. 0.15% for the sender (charged on routing nodes via route hints)
Send to L1	`250 × sats_per_vbyte + 750` where `sats_per_vbyte` is the fee rate based on exit speed (slow, medium, or fast)
Unilateral Exit	On-chain fee paid by the user

`For BTKN assets`

Transaction Type	Fee structure
Spark to Spark	Free
Unilateral Exit	On-chain fee + bond locked by user

Use the fee quote returned for the operation you are about to perform. Lightning routing fees can vary between payments. *** ## Fee Estimation Flow The complete process for estimating fees before making transactions: Determine which type of operation you want to estimate fees for. ```typescript theme={null} // Lightning payment const lightningInvoice = "lnbc..."; // Cooperative exit (withdrawal to L1) const withdrawalAmount = 10000; const withdrawalAddress = "bc1p..."; // Swap operation const swapAmount = 5000; ``` Call the appropriate fee estimation method. ```typescript theme={null} // Lightning send fee estimate const lightningFee = await wallet.getLightningSendFeeEstimate({ encodedInvoice: lightningInvoice }); // Cooperative exit fee estimate const exitFee = await wallet.getWithdrawalFeeQuote({ amountSats: withdrawalAmount, withdrawalAddress: withdrawalAddress }); // Swap fee estimate const swapFee = await wallet.getSwapFeeEstimate(swapAmount); ``` Examine the fee estimate response to understand costs. ```typescript theme={null} console.log("Lightning fee estimate:", lightningFee, "sats"); console.log("Exit fee estimate:", exitFee); console.log("Swap fee estimate:", swapFee); ``` Use the fee estimate to set appropriate limits for your transaction. ```typescript theme={null} // Use fee estimate for Lightning payment const payment = await wallet.payLightningInvoice({ invoice: lightningInvoice, maxFeeSats: lightningFee + 5 // Add buffer to fee estimate }); ``` *** ## Lightning Send Fee Estimates Estimate fees for sending Lightning payments before making the transaction. getLightningSendFeeEstimate(params) Gets an estimated fee for sending a Lightning payment. Note: the actual fee assessed may be different from the fee estimate as it will be determined by the actual Lightning node routing. ```typescript theme={null} const feeEstimateSats = await wallet.getLightningSendFeeEstimate({ encodedInvoice: "lnbcrt1u1pnm7ammpp4v84f05tl0kzt6g95g056athdpp8f8azvg6d7epz74z562ymer9jqsp5nc50gazvp0e98u42jlu653rw0eutcl067nqq924hf89q4la4kd9sxq9z0rgqnp4qdnmwu8v22cvq9xsv2l05cn9rre7xlcgdtntxawf8m0zxq3qemgzqrzjqtr2vd60g57hu63rdqk87u3clac6jlfhej4kldrrjvfcw3mphcw8sqqqqrj0q7ew45qqqqqqqqqqqqqq9qcqzpgdq5w3jhxapqd9h8vmmfvdjs9qyyssqj7lf2w4m587g04n4t0ferdv0vnwftzca0xuc9yxycng78cnhrvmyw2mzaa8t76jskpypqnwqhp9xh0vnwxz90jytd34vrmhcngsnl8qplz7ylk" }); console.log("Lightning send fee estimate:", feeEstimateSats, "sats"); ``` The BOLT11-encoded Lightning invoice Estimated fee in satoshis ### Example Response ```typescript theme={null} 100 // fee estimate in satoshis ``` *** ## Sending on L1 Fee Estimates Estimate fees for sending funds on the Bitcoin network. getWithdrawalFeeQuote(params) Gets a fee quote for a cooperative exit (on-chain withdrawal). The quote includes options for different speeds and an expiry time and must be passed to `withdraw` before it expires. ```typescript theme={null} const exitFeeEstimate = await wallet.getWithdrawalFeeQuote({ amountSats: 10000, withdrawalAddress: "bc1p5d7rjq7g6rdk2yhzks9smtbqtedr4dekq08ge8ztwac72sfr9rusxg3297" }); console.log("Cooperative exit fee estimate:", exitFeeEstimate); ``` The amount in satoshis to withdraw The Bitcoin address where the funds should be sent A fee quote for the withdrawal, or null if not available ### Example Response ```typescript theme={null} { feeEstimate: { originalValue: 1000, originalUnit: 'SATOSHI', preferredCurrencyUnit: 'USD', preferredCurrencyValueRounded: 0.50, preferredCurrencyValueApprox: 0.483 } } ``` *** ## Swap Fee Estimates Estimate fees for leaves swap operations. Leaves swaps are internal wallet optimization operations that consolidate or split your sats leaves. getSwapFeeEstimate(amountSats) Gets the estimated fee for a swap of leaves. ```typescript theme={null} const swapFeeEstimate = await wallet.getSwapFeeEstimate(5000); console.log("Swap fee estimate:", swapFeeEstimate); ``` The amount of sats to swap The estimated fee for the swap operation *** ## Fee Deduction Options For cooperative exits, you can choose how fees are handled: ### Deduct Fee from Withdrawal Amount When `deductFeeFromWithdrawalAmount` is set to `true`: ```typescript theme={null} import { ExitSpeed } from "@buildonspark/spark-sdk/types"; if (!feeQuote) throw new Error("No fee quote available"); const withdrawal = await wallet.withdraw({ onchainAddress: "bc1p...", exitSpeed: ExitSpeed.MEDIUM, amountSats: 10000, // Fee is deducted from this amount feeQuoteId: feeQuote.id, feeAmountSats: feeQuote.l1BroadcastFeeMedium.originalValue + feeQuote.userFeeMedium.originalValue, deductFeeFromWithdrawalAmount: true // Fee deducted from amount }); // You receive: 10000 sats - fee ``` ### Pay Fee Separately When `deductFeeFromWithdrawalAmount` is set to `false`: ```typescript theme={null} import { ExitSpeed } from "@buildonspark/spark-sdk/types"; if (!feeQuote) throw new Error("No fee quote available"); const withdrawal = await wallet.withdraw({ onchainAddress: "bc1p...", exitSpeed: ExitSpeed.MEDIUM, amountSats: 10000, // Recipient receives this amount feeQuoteId: feeQuote.id, feeAmountSats: feeQuote.l1BroadcastFeeMedium.originalValue + feeQuote.userFeeMedium.originalValue, deductFeeFromWithdrawalAmount: false // Fee paid separately }); // You receive: 10000 sats (fee paid from wallet balance) ``` # FAQ Source: https://docs.spark.money/wallets/faq ### What languages does it currently support? * **TypeScript** & **React Native** via the official Spark SDK * **Rust, Swift, Kotlin, Python, Flutter, Go, C#, WebAssembly** via the [Breez SDK](https://sdk-doc-spark.breez.technology/) ### What kinds of transfers can I do with Spark? You can perform the following types of transfers with Spark: * Deposit and withdraw funds to and from L1 (Bitcoin mainnet) to a Spark wallet. * Make native Spark-to-Spark transfers (between two Spark addresses). * Send and receive payments via the Lightning Network. ### Is Spark working on Regtest and Mainnet? Yes, we support both. Mainnet is already live and ready for you to use today. Internally, we run a custom Regtest network; if you’d like access, reach out to us directly. We’re also planning to release a Signet environment that anyone can spin up locally, removing the need to rely on our Regtest setup. ### Is the SDK self-custodial? Yes. The Spark Wallet SDK is fully self-custodial. Keys are generated on the user’s side. You have the flexibility to decide how you want to build your product, whether you prefer to manage custody of the funds or allow each user to own their own Spark wallet. ### Does it support MPC/multisig? Not yet. It's coming soon. ### Is there any limits in payment sizes? There are no hard limits on payment size. That said, Spark is still early, and we recommend starting with small amounts as the network matures. The only practical constraints arise if you're moving large amounts in or out of Spark via Lightning, or exiting through a cooperative exit. If you expect to move significant volume between Lightning and Spark, reach out to us. We're happy to work with you to make sure everything flows smoothly. # Identity Key Derivation Source: https://docs.spark.money/wallets/identity-key-derivation Spark wallets use a hierarchical deterministic (HD) key derivation scheme purpose-built for the Spark protocol. This follows the general principles of BIP43, using a custom purpose field derived from the SHA256 hash of "spark" to define application-specific key derivations. This derivation scheme is our recommendation so users can easily migrate between different wallet apps. You can implement a different scheme, but it will lose the ability to migrate to/from other Spark wallets. *** ## Derivation Scheme ### Base Derivation Path ``` m/8797555'/accountNumber'/keyType' ``` Where: * **8797555'**: Custom purpose field (derived from last 3 bytes of SHA256("spark") = 0x863d73) * **accountNumber'**: Account index (hardened derivation) * **keyType'**: Specific key type (hardened derivation) ### Key Types Spark derives 5 key types from the master seed: | Path | Key Type | Purpose | | - | - | - | | `m/8797555'/n'/0'` | **Identity Key** | Primary wallet identifier and Spark Address generation | | `m/8797555'/n'/1'` | **Signing HD Key** | Base key for leaf key derivation | | `m/8797555'/n'/2'` | **Deposit Key** | Receiving L1 Bitcoin deposits | | `m/8797555'/n'/3'` | **Static Deposit HD Key** | Reusable deposit addresses (static deposit flows) | | `m/8797555'/n'/4'` | **HTLC Preimage HD Key** | Lightning HTLC preimage generation | **Path:** `m/8797555'/n'/0'` Primary wallet identifier. Used for authentication, Spark Address generation, and message signing. **Path:** `m/8797555'/n'/1'` HD key used as the base for deriving leaf-specific signing keys. Each Spark leaf gets its own derived key. **Path:** `m/8797555'/n'/2'` Used for receiving L1 Bitcoin deposits into Spark. Single key, not HD-derived. **Path:** `m/8797555'/n'/3'` HD key for generating reusable static deposit addresses. Each index produces a different deposit address. **Path:** `m/8797555'/n'/4'` HD key for generating HTLC preimages in Lightning payments. The `htlcHMAC()` method uses this key. *** ## Account Number ### Default Behavior The `accountNumber` parameter controls which account's keys are derived. **The default value differs by network:** | Network | Default Account Number | | - | - | | REGTEST | `0` | | MAINNET | `1` | MAINNET defaults to `1` for backwards compatibility with legacy wallets created before multi-account support. If you're integrating with the SDK and using account `0` internally, account for this off-by-one behavior on mainnet. ### Using Account Numbers ```typescript theme={null} // Account 0 (first account) const { wallet: account0 } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic, accountNumber: 0, options: { network: "REGTEST" } }); // Account 1 (second account, same mnemonic) const { wallet: account1 } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic, accountNumber: 1, options: { network: "REGTEST" } }); // These are completely separate wallets const address0 = await account0.getSparkAddress(); const address1 = await account1.getSparkAddress(); console.log(address0 !== address1); // true ``` ### Explicit Account Numbers When building wallet software, always specify the account number explicitly to avoid confusion: ```typescript theme={null} // Explicit is better than implicit const { wallet } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic, accountNumber: 0, // Always specify options: { network: "MAINNET" } }); ``` *** ## Leaf Key Derivation When accepting transfers, Spark assigns a unique leaf ID to each UTXO. The signing key for that leaf is derived from the Signing HD Key using the leaf ID. ### Derivation Formula ```typescript theme={null} // 1. Hash the leaf ID const hash = sha256(leafId); // 2. Extract first 4 bytes as unsigned 32-bit integer (big-endian) const hashValue = hash.slice(0, 4).readUInt32BE(); // 3. Calculate derivation index (hardened) const leafIndex = (hashValue % 0x80000000) + 0x80000000; // 4. Derive child key const leafKey = signingHDKey.deriveChild(leafIndex); ``` ### Full Derivation Path ``` m/8797555'/{accountNumber}'/1'/{leafIndex}' ``` Where `leafIndex` is calculated from the leaf ID as shown above. ### Implementation ```typescript theme={null} import { createHash } from 'crypto'; function getLeafDerivationPath(leafId: string, accountNumber: number): string { // Step 1: Calculate SHA256 hash of leaf ID const hash = createHash('sha256').update(leafId).digest(); // Step 2: Convert first 4 bytes to number const hashValue = hash.readUInt32BE(0); // Step 3: Calculate hardened index const leafIndex = (hashValue % 0x80000000) + 0x80000000; // Step 4: Build derivation path return `m/8797555'/${accountNumber}'/1'/${leafIndex}'`; } // Example const path = getLeafDerivationPath("leaf-abc-123", 0); // Returns something like: m/8797555'/0'/1'/2147483747' ``` ### Using KeyDerivation In the SDK, you typically don't derive leaf keys manually. Instead, use the `KeyDerivation` type: ```typescript theme={null} import { KeyDerivationType } from "@buildonspark/spark-sdk"; // The signer handles derivation internally const publicKey = await signer.getPublicKeyFromDerivation({ type: KeyDerivationType.LEAF, path: leafId // The leaf ID, not the derivation path }); ``` *** ## Static Deposit Key Derivation Static deposit keys are derived from the Static Deposit HD Key at path `/3'`: ```typescript theme={null} // Derive static deposit key at index 5 const staticDepositPath = `m/8797555'/${accountNumber}'/3'/${index + 0x80000000}'`; ``` In the SDK: ```typescript theme={null} // Get static deposit key at index 5 const publicKey = await signer.getStaticDepositSigningKey(5); const privateKey = await signer.getStaticDepositSecretKey(5); ``` *** ## Deposit Address Flow For L1 Bitcoin deposits, the flow is: 1. **Generate Deposit Key**: Uses the Deposit Key at path `m/8797555'/n'/2'` 2. **Create Deposit Address**: Generate Bitcoin address from the key 3. **Receive Deposit**: User sends Bitcoin to the address 4. **Assign Leaf**: After tree creation, funds are assigned to a leaf with its own derived key ```typescript theme={null} // Get the deposit signing key const depositKey = await signer.getDepositSigningKey(); // The SDK handles address generation const depositAddress = await wallet.getSingleUseDepositAddress(); ``` *** ## Usage in SparkWallet ### Initialize with Specific Account ```typescript theme={null} import { SparkWallet } from "@buildonspark/spark-sdk"; const { wallet, mnemonic } = await SparkWallet.initialize({ mnemonicOrSeed: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about", accountNumber: 0, options: { network: "REGTEST", }, }); // Identity key is at m/8797555'/0'/0' const identityKey = await wallet.getIdentityPublicKey(); console.log("Identity key:", identityKey); ``` ### Multiple Accounts from Same Mnemonic ```typescript theme={null} const mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"; // Create two separate accounts const { wallet: wallet0 } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic, accountNumber: 0, options: { network: "REGTEST" } }); const { wallet: wallet1 } = await SparkWallet.initialize({ mnemonicOrSeed: mnemonic, accountNumber: 1, options: { network: "REGTEST" } }); // Each account has completely isolated keys console.log(await wallet0.getSparkAddress()); // Different address console.log(await wallet1.getSparkAddress()); // Different address ``` *** ## Custom Derivation Paths For non-standard use cases, you can provide a custom key generator: ```typescript theme={null} import { DefaultSparkSigner, SparkValidationError } from "@buildonspark/spark-sdk"; import { HDKey } from "@scure/bip32"; class DerivationPathKeysGenerator { constructor(private readonly basePathTemplate: string) {} async deriveKeysFromSeed(seed: Uint8Array, accountNumber: number) { const hdkey = HDKey.fromMasterSeed(seed); const basePath = this.basePathTemplate.replace("?", String(accountNumber)); const identityKey = hdkey.derive(`${basePath}/0'`); const signingKey = hdkey.derive(`${basePath}/1'`); const depositKey = hdkey.derive(`${basePath}/2'`); const staticDepositKey = hdkey.derive(`${basePath}/3'`); const htlcPreimageKey = hdkey.derive(`${basePath}/4'`); if ( !identityKey.privateKey || !identityKey.publicKey || !signingKey.privateKey || !signingKey.publicKey || !depositKey.privateKey || !depositKey.publicKey || !staticDepositKey.privateKey || !staticDepositKey.publicKey || !htlcPreimageKey.privateKey || !htlcPreimageKey.publicKey ) { throw new SparkValidationError("Failed to derive all required keys from seed"); } return { identityKey: { privateKey: identityKey.privateKey, publicKey: identityKey.publicKey, }, signingHDKey: { hdKey: signingKey, privateKey: signingKey.privateKey, publicKey: signingKey.publicKey, }, depositKey: { privateKey: depositKey.privateKey, publicKey: depositKey.publicKey, }, staticDepositHDKey: { hdKey: staticDepositKey, privateKey: staticDepositKey.privateKey, publicKey: staticDepositKey.publicKey, }, HTLCPreimageHDKey: { hdKey: htlcPreimageKey, privateKey: htlcPreimageKey.privateKey, publicKey: htlcPreimageKey.publicKey, }, }; } } // Custom derivation template (? is replaced with account number) const customGenerator = new DerivationPathKeysGenerator("m/44'/0'/?'"); const signer = new DefaultSparkSigner({ sparkKeysGenerator: customGenerator }); // The keys will be derived from the custom path: // Identity: m/44'/0'/n'/0' // Signing HD: m/44'/0'/n'/1' // Deposit: m/44'/0'/n'/2' // Static Deposit: m/44'/0'/n'/3' // HTLC Preimage: m/44'/0'/n'/4' ``` Custom derivation paths will not be compatible with other Spark wallets. Only use this if you have specific requirements that justify breaking compatibility. *** ## Migration Between Wallets The standardized derivation scheme enables wallet migration: ### Export ```typescript theme={null} // Save these securely const walletBackup = { mnemonic: "your 12 or 24 word phrase", accountNumber: 0 }; ``` ### Import ```typescript theme={null} const { wallet } = await SparkWallet.initialize({ mnemonicOrSeed: walletBackup.mnemonic, accountNumber: walletBackup.accountNumber, options: { network: "MAINNET" } }); // Same identity key, same Spark address const address = await wallet.getSparkAddress(); ``` *** ## Security Considerations ### Hardened Derivation All derivation paths use hardened derivation (indicated by the `'` suffix). This prevents: * **Key leakage**: Child public keys cannot be used to derive parent keys * **Chain code exposure**: Compromising a child key doesn't compromise siblings ### Key Isolation Each account number creates a completely isolated set of keys: ```typescript theme={null} // Account 0 and Account 1 share no key material const account0Keys = deriveAccountKeys(mnemonic, 0); const account1Keys = deriveAccountKeys(mnemonic, 1); // No cryptographic relationship between them assert(account0Keys.identity !== account1Keys.identity); ``` ### Mnemonic Security * Store mnemonic phrases securely (encrypted, offline if possible) * Never transmit mnemonics over the network * Consider using hardware wallets or secure enclaves for production *** ## Quick Reference | Key Type | Path | SDK Method | | - | - | - | | Identity | `m/8797555'/n'/0'` | `signer.getIdentityPublicKey()` | | Signing HD | `m/8797555'/n'/1'` | Internal (leaf derivation base) | | Deposit | `m/8797555'/n'/2'` | `signer.getDepositSigningKey()` | | Static Deposit | `m/8797555'/n'/3'/i'` | `signer.getStaticDepositSigningKey(i)` | | HTLC Preimage | `m/8797555'/n'/4'` | `signer.htlcHMAC(transferId)` | | Leaf | `m/8797555'/n'/1'/hash(leafId)'` | `signer.getPublicKeyFromDerivation({type: "leaf", path: leafId})` | # Overview Source: https://docs.spark.money/wallets/overview Create a Wallet

The Spark Wallet SDK lets you deploy Spark-native wallets in the most scalable and developer-friendly way possible. Whether you're building for your own custody or shipping self-custodial wallets for your users, the SDK is flexible by design. *** ## Installation ### Spark SDK The official Spark SDK for TypeScript and React Native applications. ### Breez SDK The [Breez](https://breez.technology) team has built a fully native SDK in Rust with bindings for Swift, Kotlin, Python, Flutter, Go, C#, and WebAssembly. If you need native mobile performance or a language not covered by the Spark SDK, use the Breez SDK. *** ## Fundamentals *** ## Tools # Privacy Mode Source: https://docs.spark.money/wallets/privacy Control public access to Bitcoin balances and transfer history Privacy Mode on SparkScan

*** ## Overview New wallets start with privacy off (`privateEnabled: false`). Public clients can query their Bitcoin balances and transfer history. Call `setPrivacyEnabled(true)` to restrict those wallet queries to the owner and a viewer the owner has authorized. Privacy mode applies to Bitcoin queries only. Token activity, including USDB transfers, remains public. It does not hide Bitcoin on-chain data or information already shared with another party. ## Enable privacy ```typescript theme={null} const settings = await wallet.setPrivacyEnabled(true); if (!settings?.privateEnabled) { throw new Error("Could not confirm that privacy is enabled"); } ``` To make wallet queries public again, call `wallet.setPrivacyEnabled(false)`. Check the setting from the owner's wallet with [`getWalletSettings()`](/api-reference/wallet/get-wallet-settings). A missing response is not confirmation that privacy is off. ```typescript theme={null} const settings = await wallet.getWalletSettings(); if (settings) { console.log("Privacy enabled:", settings.privateEnabled); console.log("Authorized viewer:", settings.viewerIdentityPublicKey); } ``` ## Grant a service read access A wallet can authorize **one viewer identity key at a time**. Setting a new key replaces the previous grant. The grant permits reads; it does not permit spending or claiming incoming transfers. Use a separate mnemonic or seed for the viewer. Do not give a service the owner's wallet mnemonic just to let it read balances. ```typescript theme={null} import { SparkReadonlyClient, deriveViewerIdentityPublicKey, } from "@buildonspark/spark-sdk"; const config = { network: "MAINNET" } as const; // On the service: derive its public identity from its own mnemonic. const viewerPublicKey = await deriveViewerIdentityPublicKey(config, viewerMnemonic); // On the owner's wallet: authorize the service's public key. const grant = await wallet.setViewerIdentityPublicKey(viewerPublicKey); if (grant?.viewerIdentityPublicKey !== viewerPublicKey) { throw new Error("Could not confirm the viewer grant"); } await wallet.setPrivacyEnabled(true); // On the service: authenticate with the same configuration and mnemonic. const client = await SparkReadonlyClient.createWithViewerKey(config, viewerMnemonic); const available = await client.getAvailableBalance(ownerSparkAddress); ``` The viewer identity is HD-derived. Use `deriveViewerIdentityPublicKey()` with the same network and account number as `createWithViewerKey()`; the public key of the seed itself is not the viewer identity. Granting a viewer does not enable privacy. While privacy is off, public clients can still read the wallet. To revoke the grant: ```typescript theme={null} await wallet.clearViewerIdentityPublicKey(); ``` Authentication alone does not grant access to someone else's private wallet: the owner must authorize that identity. ## Interpret empty responses Without owner or viewer authorization, private-wallet balance queries return `0n` and wallet transfer lists return empty arrays. This is intentional: returning a distinct permission error would reveal that a private wallet exists. These responses do not distinguish a private wallet from an empty wallet. Do not use a zero balance or an empty history as proof that a grant succeeded or failed. Authentication, network, and other request errors can still occur. Confirm the configured viewer key through the owner's `getWalletSettings()`. The read-only client has no public permission-check method. An event-stream error is not a supported permission probe; see [Wallet Viewer limitations](/wallets/readonly-client#events-and-client-boundaries). Privacy is a wallet-query setting, not a guarantee that every record of a transfer is hidden. Transfer details may also be accessible through another participant. Do not use `getTransfersByIds()` to test whether a wallet granted you access, and avoid exposing transfer IDs unnecessarily. ## Webhooks Webhooks report request outcomes independently of wallet-history read access. They do not grant access to private queries and do not claim incoming funds. See [Webhooks](/wallets/webhooks) for registration, signature verification, and payment matching. ## API reference * [`setPrivacyEnabled()`](/api-reference/wallet/set-privacy-enabled) * [`getWalletSettings()`](/api-reference/wallet/get-wallet-settings) * [`setViewerIdentityPublicKey()`](/api-reference/wallet/set-viewer-identity-public-key) * [`clearViewerIdentityPublicKey()`](/api-reference/wallet/clear-viewer-identity-public-key) * [`createWithViewerKey()`](/api-reference/readonly/create-with-viewer-key) # React Native SDK Source: https://docs.spark.money/wallets/react-native React Native SDK for iOS and Android wallet apps. Requires Xcode/iOS Simulator or Android Studio.

**Requirements:** React `>=18.2.0`, React Native `>=0.71.0`, iOS `>=12.0` Complete React Native example with wallet, transfers, and Lightning ## Getting Started To get started, follow the steps below. Install the Spark SDK packages using your package manager of choice. ```bash npm theme={null} npm install @buildonspark/spark-sdk ``` ```bash yarn theme={null} yarn add @buildonspark/spark-sdk ``` ```bash pnpm theme={null} pnpm add @buildonspark/spark-sdk ``` Install the required polyfills for React Native compatibility. ```bash npm theme={null} npm install react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding ``` ```bash yarn theme={null} yarn add react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding ``` ```bash pnpm theme={null} pnpm add react-native-get-random-values @azure/core-asynciterator-polyfill buffer text-encoding ``` **Critical:** Import polyfills at the very top of your `index.js` file, BEFORE importing your app or any other modules. The crypto module will fail to load if this order is wrong. ```js index.js theme={null} // These MUST be the first imports in your app entry point import 'react-native-get-random-values'; import '@azure/core-asynciterator-polyfill'; import { Buffer } from 'buffer'; global.Buffer = Buffer; // Now import your app import { AppRegistry } from 'react-native'; import App from './App'; import { name as appName } from './app.json'; AppRegistry.registerComponent(appName, () => App); ``` For iOS, you must install the native module dependencies. This step is required for bare React Native apps. ```bash theme={null} cd ios && pod install && cd .. ``` If you skip this step, you'll see errors like `Cannot read property 'decryptEcies' of null` when initializing the wallet. Create a wallet instance that will be used to interact with the Spark network. ```tsx wallet.jsx theme={null} import { SparkWallet } from "@buildonspark/spark-sdk"; export const initializeWallet = async () => { const { wallet, mnemonic } = await SparkWallet.initialize({ mnemonicOrSeed: "optional-mnemonic-or-seed", accountNumber: 0, // optional options: { network: "REGTEST" // or "MAINNET" } }); console.log("Wallet initialized successfully:", mnemonic); return wallet; }; ``` You're ready to start building. ```tsx App.jsx theme={null} import { useState, useEffect } from "react"; import { View, Text, Button } from "react-native"; import { SparkWallet } from "@buildonspark/spark-sdk"; export function WalletInfo() { const [wallet, setWallet] = useState(null); const [loading, setLoading] = useState(false); const createWallet = async () => { setLoading(true); try { const { wallet, mnemonic } = await SparkWallet.initialize({ options: { network: "REGTEST" } }); setWallet(wallet); console.log("Mnemonic:", mnemonic); } catch (error) { console.error("Failed to create wallet:", error); } finally { setLoading(false); } }; // Note: getSparkAddress() and getBalance() are async const [address, setAddress] = useState(""); const [balance, setBalance] = useState(0n); useEffect(() => { if (wallet) { wallet.getSparkAddress().then(setAddress); wallet.getBalance().then(b => setBalance(b.satsBalance.available)); } }, [wallet]); return ( Wallet Information {loading ? ( Loading... ) : wallet ? ( Address: {address} Balance: {balance.toString()} sats ) : (