ZK Wallet SDK

Account Abstraction + Bundler Interface • Trade Intent Generation & Stealth Address Management

---

SnarkSide’s ZK Wallet SDK is the gateway for developers building privacy-native frontends, trading bots, or wallet integrations into the encrypted perp ecosystem. Unlike traditional SDKs that assume public transaction flow, the ZK Wallet SDK enables full participation in SnarkSide’s private execution layer while preserving:

• User privacy (vaults, intents, addresses)

• Protocol correctness (circuit-bound proofs)

• Flexibility across client-side and bundler-based flows

This document outlines the architecture, components, and responsibilities of the SDK, along with implementation examples and advanced usage patterns.

---

Core Features

Component	Description
IntentBuilder	Constructs encrypted trade intents based on user strategy and margin status
StealthAddressManager	Generates shielded, unlinkable vault addresses and nullifiers
ZKSigner	Hashes, salts, and signs inputs with deterministic Poseidon-compatible keys
BundlerInterface	Prepares and submits batches to intent relayers
VaultStateHandler	Reads + updates vault witness for Merkle root tracking
ProofClient	Local/remote prover integration (optional)

---

1. Account Abstraction with Stealth Vaults

SnarkSide supports vault-based account abstraction, decoupling user identity from public addresses.

Each account is represented by a UTXO-style vault committed into a global Merkle tree:

type VaultNote = {
  vaultHash: Field,
  positionHash: Field,
  ownerPublicKey: PubKey,
  salt: Field,
  timestamp: number,
}

All account operations—deposit, trade, update, close—are generated locally via the SDK and verified via ZK circuits. No public EVM address is exposed on-chain.

Vault Creation:

const vault = VaultNote.create({
  amount: 100_000,
  leverage: 10,
  direction: 'long',
  expiry: futureTimestamp(),
});

const vaultCommitment = vault.hash(); // Poseidon

---

2. Intent Generation

SnarkSide trades are expressed as intent objects, not transactions.

Each intent is signed, blinded, and submitted to a relayer off-chain.

const intent = IntentBuilder.build({
  action: 'open',
  market: 'ETH-USD',
  size: 50_000,
  leverage: 5,
  maxSlippage: 0.5,
  vaultCommitment: vault.hash(),
  expiry: Date.now() + 30 * 60 * 1000, // 30 mins
});

const signedIntent = ZKSigner.sign(intent);

The resulting object is not a transaction—it’s a cryptographically sealed payload containing:

• Vault reference

• Trade spec

• Max execution constraints

• Validity window

• Fee commitment (optional)

Intent Bundle Submit:

await BundlerInterface.submit({
  intents: [signedIntent],
  zkFeeTip: 0.02, // optional SNSD reward tip
});

---

3. Stealth Address Management

Vaults must be unlinkable. The SDK uses deterministic key derivation (based on Poseidon-friendly secrets) to generate one-time stealth addresses.

const stealthKeypair = StealthAddressManager.derive({
  userSeed: entropy,
  salt: vault.salt,
});

vault.ownerPublicKey = stealthKeypair.pub;

These addresses are never posted or reused, and cannot be linked by external observers.

---

4. Bundler Interface & Relayer Routing

To decouple wallet clients from relayer endpoints, the SDK includes a Bundler abstraction:

const relayer = BundlerInterface.connect({
  region: 'eu-central',
  authToken: zkAuthToken,
});

await relayer.sendIntents([signedIntent]);

Future modules will support:

• Intent gossiping

• Batch fee optimization

• Encrypted relay fallback

---

5. ZK Proof Integration (Optional)

Advanced clients may wish to locally prove trade intents and vault updates for high-trust workflows. The SDK includes:

• Circom circuit bindings (wasm + zkey)

• Witness calculators

• Local prover runner (Groth16 or Halo2)

const witness = await Prover.computeWitness({
  intent,
  vault,
  oracleCommitment,
});

const proof = await Prover.generate({
  circuit: 'intentProof',
  witness,
});

await submitToVerifier(proof);

---

6. Light Clients and Mobile Compatibility

The SDK is optimized for:

• Browser environments (WebAssembly fallback)

• Mobile wallets (via QR intent bundling)

• Server-side bots (with batching + tip logic)

Builds are modular and tree-shakable, with support for ESM, CJS, and browser targets.

---

7. Planned Enhancements

Module	Description
zkFeeManager	Auto-set fee bids per market volatility
RecoveryKit	Key rotation + vault regeneration
zkOracleClient	Local proof of oracle bounds
IntentDSL	Declarative trade scripting language

---

Conclusion

The SnarkSide ZK Wallet SDK is the core toolkit for developers looking to build privacy-preserving perp trading apps, bots, and wallets. It abstracts away the cryptographic complexity while exposing:

• Full vault control

• Trade intent generation

• Gasless relay submission

• Optional zk proof workflows

It does not sign transactions. It generates ZK-valid trade expressions—which are matched privately, settled cryptographically, and verified without trust.

Welcome to the dark side of intent-based trading.