Starkzap SDK

Project-focused guide for https://github.com/keep-starknet-strange/starkzap.

Use this skill when requests involve Starkzap SDK code, examples, or docs.

When To Use

Trigger for tasks like:

• “Add a new onboarding flow in Starkzap”
• “Fix sponsored transaction behavior in wallet.execute”
• “Update staking pool logic or validator presets”
• “Patch Privy signer/server integration”
• “Review Starkzap tests/docs/examples”

Repository Map

Primary implementation:

• src/sdk.ts – top-level orchestration (StarkSDK)
• src/wallet/* – wallet implementations and lifecycle
• src/signer/* – StarkSigner, PrivySigner, signer adapter
• src/tx/* – Tx and TxBuilder
• src/erc20/* – token helpers, balance/transfer logic
• src/staking/* – staking operations and pool discovery
• src/types/* – shared domain types (Address, Amount, config)

Operational and docs:

• tests/* and tests/integration/*
• examples/web, examples/server, examples/mobile, examples/flappy-bird
• scripts/* for generated artifacts in the Starkzap repo
• docs/* and mintlify-docs/*

Skill resources:

• skills/starkzap-sdk/references/signer-integration.md – signer trust boundaries and auth assumptions
• skills/starkzap-sdk/references/sponsored-transactions.md – paymaster flow and fee mode behavior
• skills/starkzap-sdk/references/erc20-helpers.md – Amount semantics and transfer patterns
• skills/starkzap-sdk/references/staking-reliability.md – pool discovery and timeout/abort safety
• skills/starkzap-sdk/scripts/wallet-execute-example.ts – wallet readiness and execute flow
• skills/starkzap-sdk/scripts/staking-pool-discovery.ts – staking pool discovery and diagnostics

Quick Reference

Common starknet.js patterns (provider/account/call/execute/listen):

import { Account, Contract, RpcProvider } from "starknet";

const provider = await RpcProvider.create({
  nodeUrl: process.env.RPC_URL!,
});

const account = new Account({
  provider,
  address: process.env.ACCOUNT_ADDRESS!,
  signer: process.env.PRIVATE_KEY!,
  cairoVersion: "1",
});

const contract = new Contract({
  abi,
  address: process.env.CONTRACT_ADDRESS!,
  providerOrAccount: account,
});
await contract.call("balance_of", [account.address]); // read

const tx = await account.execute([
  {
    contractAddress: process.env.CONTRACT_ADDRESS!,
    entrypoint: "do_work",
    calldata: [],
  },
]);
await provider.waitForTransaction(tx.transaction_hash);

// With Starkzap Tx wrapper
const submitted = await wallet.execute(calls, { feeMode: "user_pays" });
const stop = submitted.watch(
  ({ finality, execution }) => console.log(finality, execution),
  { pollIntervalMs: 5000, timeoutMs: 120000 }
);
// stop(); // call to unsubscribe early

Common error classes and immediate recovery:

See also:

• skills/starkzap-sdk/references/* for implementation-specific troubleshooting
• skills/starkzap-sdk/scripts/* for runnable diagnostic examples

Core Workflows

1) Configure StarkSDK and Connect Wallets

Common API path:

1. Instantiate StarkSDK with network or rpcUrl + chainId.
2. Use sdk.onboard(...) or sdk.connectWallet(...).
3. Call wallet.ensureReady({ deploy: "if_needed" }) before user-pays writes.

Supported onboarding strategies:

• OnboardStrategy.Signer
• OnboardStrategy.Privy
• OnboardStrategy.Cartridge

For Cartridge:

• Treat as web-only runtime.
• Expect popup/session behavior and policy scoping requirements.

import {
  ChainId,
  OnboardStrategy,
  StarkSDK,
  StarkSigner,
} from "starkzap";

const sdk = new StarkSDK({ network: "sepolia" });

const customSdk = new StarkSDK({
  rpcUrl: process.env.RPC_URL!,
  chainId: ChainId.SEPOLIA,
});

const signerResult = await sdk.onboard({
  strategy: OnboardStrategy.Signer,
  account: { signer: new StarkSigner(process.env.PRIVATE_KEY!) },
  feeMode: "user_pays",
  deploy: "if_needed",
});

const privyResult = await sdk.onboard({
  strategy: OnboardStrategy.Privy,
  privy: {
    resolve: async () => ({
      walletId: process.env.PRIVY_WALLET_ID!,
      publicKey: process.env.PRIVY_PUBLIC_KEY!,
      serverUrl: process.env.PRIVY_SIGNER_URL!,
    }),
  },
  feeMode: "sponsored",
});

const cartridgeResult = await sdk.onboard({
  strategy: OnboardStrategy.Cartridge,
  cartridge: {
    preset: "controller",
    policies: [{ target: "0xPOOL", method: "stake" }],
  },
});

const wallet = await sdk.connectWallet({
  account: { signer: new StarkSigner(process.env.PRIVATE_KEY!) },
  feeMode: "sponsored",
});

await wallet.ensureReady({ deploy: "if_needed" });

2) Execute Transactions (wallet.execute, wallet.preflight, wallet.tx)

Use:

• wallet.execute(calls, options) for direct execution.
• wallet.preflight({ calls, feeMode }) for simulation checks.
• wallet.tx() (TxBuilder) for batched operations with deterministic ordering.

const calls = [
  {
    contractAddress: process.env.CONTRACT_ADDRESS!,
    entrypoint: "do_work",
    calldata: [],
  },
];

const preflight = await wallet.preflight({
  calls,
  feeMode: "user_pays",
});
if (!preflight.ok) {
  throw new Error(`Preflight failed: ${preflight.reason}`);
}

const userPaysTx = await wallet.execute(calls, { feeMode: "user_pays" });
await userPaysTx.wait();

const sponsoredTx = await wallet.execute(calls, { feeMode: "sponsored" });
await sponsoredTx.wait();

const batchedTx = await wallet
  .tx()
  .add(...calls)
  .send({ feeMode: "sponsored" });
await batchedTx.wait();

function getSdkErrorClass(error: unknown): string {
  const message = error instanceof Error ? error.message : String(error);
  if (message.includes("not deployed")) return "UNDEPLOYED_ACCOUNT";
  if (message.includes("timed out") || message.includes("429")) {
    return "RPC_OR_NETWORK";
  }
  if (message.includes("signature") || message.includes("Privy")) {
    return "AUTH_OR_PERMISSION";
  }
  if (message.includes("Invalid") || message.includes("Amount")) {
    return "VALIDATION_ERROR";
  }
  return "UNKNOWN";
}

try {
  await wallet.execute(calls, { feeMode: "user_pays" });
} catch (error) {
  const kind = getSdkErrorClass(error);
  if (kind === "UNDEPLOYED_ACCOUNT") {
    await wallet.ensureReady({ deploy: "if_needed" });
  }
  throw error;
}

When changing execution behavior:

• Audit deploy vs execute path for undeployed accounts.
• Verify runtime constraints (OnboardStrategy.Cartridge is web-only).
• Cover both user_pays and sponsored branches in tests.

3) ERC20 and Staking Scope

ERC20 notes (starkzap-sdk internal token operations, no avnu required):

• Validate Amount with the token preset used for the call.
• Keep multicall ordering explicit for batched transfers.

import { Amount } from "starkzap";

const usdcAmount = Amount.parse("25", USDC);

try {
  const tx = await wallet
    .tx()
    .transfer(USDC, [
      { to: recipientA, amount: usdcAmount },
      { to: recipientB, amount: Amount.parse("5", USDC) },
    ])
    .send({ feeMode: "user_pays" });
  await tx.wait();
} catch (error) {
  // Re-parse Amount from the expected token preset before retrying.
  throw error;
}

Staking notes (starkzap-specific staking flows):

• Membership-sensitive operations: enter, add, exit intent, exit.
• Validate staking config and chain presets before execution.
• Verify timeout/abort behavior where pool resolution is involved.

For general DeFi operations (swaps, DCA, lending) and STRK staking via the avnu aggregator, use the starknet-defi skill.

4) Examples + Integration Surfaces

Check for drift between:

• examples/web/main.ts
• examples/server/server.ts
• README and docs links

Specifically verify endpoint and auth consistency for Privy + paymaster proxy flows.

Guardrails

Do not hand-edit generated files:

• src/erc20/token/presets.ts
• src/erc20/token/presets.sepolia.ts
• src/staking/validator/presets.ts
• src/staking/validator/presets.sepolia.ts
• docs/api/**
• docs/export/**

Regenerate with scripts:

npm run generate:tokens
npm run generate:tokens:sepolia
npm run generate:validators
npm run generate:validators:sepolia
npm run docs:api
npm run docs:export

Keep API export changes explicit:

• If new public API is added/removed, update src/index.ts.

Validation Checklist

Run minimal set first:

npm run typecheck
npm test

Run broader checks when behavior is cross-cutting:

npm run build
npm run test:all

Integration tests may require local devnet/fork setup:

npm run test:integration

If not run, clearly report why.

Error Codes & Recovery

Map observed errors to actionable recovery:

If a fix is uncertain:

• Reproduce with the closest example in examples/*.
• Capture command, environment, and failing test IDs.
• Report exact file/path + remediation attempted.

Useful Task Patterns

• Bug fix in wallet lifecycle:

  • inspect src/wallet/index.ts, src/wallet/utils.ts
  • patch
  • update tests/wallet*.test.ts

• Privy auth/signature issue:

  • inspect src/signer/privy.ts
  • align with examples/server/server.ts
  • update tests/privy-signer.test.ts

• Staking regression:

  • inspect src/staking/staking.ts, src/staking/presets.ts
  • add/adjust integration assertions in tests/integration/staking.test.ts

Example Prompt

“Use this skill to fix Starkzap sponsored execution for undeployed accounts, add tests, and list behavior changes.”