# Message Signing, Events, Errors, Issuance Smaller topics consolidated into one reference. Load when working on any of: signing/verifying messages, listening for transfer/deposit events, handling SDK errors, or minting new tokens. ## Message Signing Spark wallets can sign and verify messages using their identity key. Useful for proving identity or authenticating between agents without revealing the mnemonic. ### Sign ```javascript const signature = await wallet.signMessageWithIdentityKey("I am agent-007"); // Optional: pass `true` as a 2nd arg for compact (64-byte) encoding instead of DER. ``` ### Verify (own signature only) `validateMessageWithIdentityKey` validates against the *calling wallet's own* identity key — there is no parameter for verifying against an external public key. ```javascript const isValid = await wallet.validateMessageWithIdentityKey("I am agent-007", signature); ``` ### Verify someone else's signature Only for a signature from another key: checking your own, `validateMessageWithIdentityKey` (or the wrapper's `agent.verifyOwnSignature`) is the whole check, so don't add this as a second one. For external verification, use `secp256k1.verify` directly: ```javascript import { secp256k1 } from "@noble/curves/secp256k1"; import { sha256 } from "@noble/hashes/sha2"; import { hexToBytes } from "@noble/curves/utils"; const valid = secp256k1.verify( hexToBytes(signature), sha256(new TextEncoder().encode("I am agent-007")), hexToBytes(theirPublicKeyHex), ); ``` ## Event Listeners The wallet emits events for real-time updates. Useful for agents that need to react to incoming payments, with one gap: `transfer:claimed` (and `agent.onTransferReceived`, which wraps it) fires only for payments claimed while the wallet is connected. The SDK also claims as the wallet opens and as its stream reconnects, without emitting (REGTEST, 2026-10-28), so a bot that acknowledges payments from this event misses every one made while it was offline. After boot, read `getTransfers()` for those, and `getBalance()`'s `incomingSats` for any still being claimed (`references/agent-class.md` → Receiving). ```javascript wallet.on("transfer:claimed", (transferId, balance) => { console.log(`transfer ${transferId} received. balance: ${balance}`); }); wallet.on("deposit:confirmed", (depositId, balance) => { console.log(`deposit ${depositId} confirmed. balance: ${balance}`); }); wallet.on("token-balance:update", (event) => { // event.tokenBalances is the updated TokenBalanceMap }); wallet.on("stream:connected", () => console.log("connected")); wallet.on("stream:disconnected", (reason) => console.log("disconnected:", reason)); ``` The `SparkWalletEvent` enum exports the canonical event names (`SparkWalletEvent.BalanceUpdate`, `SparkWalletEvent.TransferClaimed`, etc.) — prefer these over string literals for forward-compatibility. ## Error Handling ```javascript import { ValidationError, NetworkError, AuthenticationError, ConfigurationError, RPCError, } from "@buildonspark/spark-sdk"; try { await wallet.transfer({ receiverSparkAddress: "sp1p...", amountSats: 1000 }); } catch (err) { if (err instanceof ValidationError) console.log("invalid input:", err.message); else if (err instanceof NetworkError) console.log("network issue:", err.message); else if (err instanceof AuthenticationError) console.log("auth failed:", err.message); else if (err instanceof ConfigurationError) console.log("config problem:", err.message); else if (err instanceof RPCError) console.log("RPC error:", err.message); else throw err; } ``` Error types: - **ValidationError** — invalid parameters, malformed addresses - **NetworkError** — connection failures, timeouts - **AuthenticationError** — key/token issues - **ConfigurationError** — missing config, initialization problems - **RPCError** — gRPC communication failures All inherit from `SparkSdkError`, which has a `context` property carrying additional debug fields. ## Token Issuance (`@buildonspark/issuer-sdk`) Minting new tokens requires the separate `IssuerSparkWallet`. Spark splits wallet and issuer concerns deliberately — the wallet SDK has no `createToken` method because issuance requires holding the issuer key (a different security boundary). ```bash npm install @buildonspark/issuer-sdk ``` ### Mint a token ```javascript import { IssuerSparkWallet } from "@buildonspark/issuer-sdk"; import { loadMnemonicFromEnv, sparkWalletOptions } from "sparkbtcbot-skill"; const mnemonic = await loadMnemonicFromEnv(); // reads SPARK_PASSPHRASE const { wallet } = await IssuerSparkWallet.initialize({ mnemonicOrSeed: mnemonic, options: sparkWalletOptions("REGTEST"), // the SDK's fee ladders off }); // One token per wallet — check first let tokenId; try { tokenId = await wallet.getIssuerTokenIdentifier(); } catch {} if (!tokenId) { await wallet.createToken({ tokenName: "ExampleToken", tokenTicker: "EXMPL", maxSupply: 1_000_000_000_000n, decimals: 6, isFreezeable: false, }); tokenId = await wallet.getIssuerTokenIdentifier(); } await wallet.mintTokens({ tokenAmount: 1_000n, tokenIdentifier: tokenId }); // mint 0.001 token at 6 decimals to issuer's own balance // Then transfer with wallet.transferTokens(...) just like any token ``` ### Other issuer operations - `wallet.burnTokens({ tokenAmount, tokenIdentifier })` — destroy supply you hold - `wallet.freezeTokens(...)` / `wallet.unfreezeTokens(...)` — only if `isFreezeable: true` at create time - `wallet.getIssuerTokenBalance()` — issuer-side balance accounting - `wallet.getIssuerTokenDistribution()` — supply distribution across holders The issuance flow shown here is intended for testing and experimentation. Production token issuance is out of scope for this skill — that's a different problem with different operational requirements (custody, supply policy, key rotation, regulatory considerations).