starkzap-sdk

Original：🇺🇸 English

Translated

3 scriptsChecked / no sensitive code detected

Use when integrating or maintaining applications built with keep-starknet-strange/starkzap. Covers StarkSDK setup, onboarding (Signer/Privy/Cartridge), wallet lifecycle, sponsored transactions, ERC20 transfers, staking flows, tx builder batching, examples, tests, and generated presets.

1installs

Sourcekeep-starknet-strange/starknet-agentic

Added on2026-02-26

NPX Install

npx skill4agent add keep-starknet-strange/starknet-agentic starkzap-sdk

SKILL.md Content

View Translation Comparison →

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):

typescript

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);

typescript

// 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:

Error Class	Typical Signal	Immediate Recovery
`VALIDATION_ERROR`	`Invalid token decimals` , `Amount.parse(...)` failure	Re-check token decimals/symbol, parse from known token preset, avoid mixing token types.
`UNDEPLOYED_ACCOUNT`	`Account is not deployed` on `wallet.execute(...)`	Run `wallet.ensureReady({ deploy: "if_needed" })` before `user_pays` writes.
`RPC_OR_NETWORK`	timeout, 429, provider mismatch	Retry with backoff, confirm `rpcUrl` and `chainId` , switch to stable RPC for production.
`TX_REVERTED`	`preflight.ok === false` or reverted receipt	Run `wallet.preflight({ calls })` , inspect reason, reduce batch size, verify call ordering.
`AUTH_OR_PERMISSION`	Privy 401/403, invalid signature response	Verify signer server auth, headers/body resolver, and trusted `serverUrl` .

Core Workflows

1) Configure

StarkSDK

and Connect Wallets

Common API path:

Instantiate
```
StarkSDK
```
with
```
network
```
or
```
rpcUrl + chainId
```
.
Use
```
sdk.onboard(...)
```
or
```
sdk.connectWallet(...)
```
.

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.

typescript

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.

typescript

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();

typescript

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.

typescript

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:

bash

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:

bash

npm run typecheck
npm test

Run broader checks when behavior is cross-cutting:

bash

npm run build
npm run test:all

Integration tests may require local devnet/fork setup:

bash

npm run test:integration

If not run, clearly report why.

Error Codes & Recovery

Map observed errors to actionable recovery:

Error Class	Typical Trigger	Recovery Steps
`VALIDATION_ERROR`	`Amount.parse(...)` /token mismatch, malformed address, invalid config	Confirm token decimals/symbol, re-create `Amount` from known token presets, validate config against `src/types/*` and `src/sdk.ts` .
`RPC_OR_NETWORK`	RPC timeout, `429` , transient JSON-RPC failures, chain mismatch	Retry with exponential backoff, check `rpcUrl` / `chainId` , verify provider health, reduce batch size for retries.
`TX_REVERTED`	`wallet.preflight(...)` fails or receipt is reverted	Run `wallet.preflight({ calls, feeMode })` first, inspect revert reason, reorder calls in `wallet.tx()` , split large multicalls.
`RATE_LIMIT_OR_TIMEOUT`	`tx.watch` timeout, stalled polling, pool resolution timeout	Increase timeout where appropriate, add abort handling, retry on fresh provider session, avoid parallel heavy queries.
`AUTH_OR_PERMISSION`	Privy signing errors, 401/403, invalid signature payloads	Verify signer server auth headers/body, validate trusted `serverUrl` , check `examples/server/server.ts` auth middleware alignment.
`UNDEPLOYED_ACCOUNT`	`wallet.execute(..., { feeMode: "user_pays" })` on undeployed account	Run `wallet.ensureReady({ deploy: "if_needed" })` , then retry execution; use sponsored mode only when paymaster path is configured.
`GENERATED_ASSET_DRIFT`	Preset/docs changes diverge from source of truth	Regenerate via `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` .

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."

starkzap-sdk

NPX Install

Tags

SKILL.md Content

Starkzap SDK

When To Use

Repository Map

Quick Reference

Core Workflows

1) Configure
`StarkSDK`
and Connect Wallets

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

3) ERC20 and Staking Scope

4) Examples + Integration Surfaces

Guardrails

Validation Checklist

Error Codes & Recovery

Useful Task Patterns

Example Prompt

starkzap-sdk

NPX Install

Tags

SKILL.md Content

Starkzap SDK

When To Use

Repository Map

Quick Reference

Core Workflows

1) Configure StarkSDK and Connect Wallets

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

3) ERC20 and Staking Scope

4) Examples + Integration Surfaces

Guardrails

Validation Checklist

Error Codes & Recovery

Useful Task Patterns

Example Prompt

1) Configure
`StarkSDK`
and Connect Wallets

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