菜单
Reference for integrating or maintaining applications built with keep-starknet-strange/starkzap, including StarkSDK setup, onboarding, wallet lifecycle, sponsored transactions, ERC20 flows, staking, and transaction builder usage.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/keep-starknet-strange/starknet-agentic --skill starkzap-sdk命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | starkzap-sdk |
| description | Reference for integrating or maintaining applications built with keep-starknet-strange/starkzap, including StarkSDK setup, onboarding, wallet lifecycle, sponsored transactions, ERC20 flows, staking, and transaction builder usage. |
| license | Apache-2.0 |
| metadata | {"author":"keep-starknet-strange","version":"1.0.0","org":"keep-starknet-strange"} |
| compatibility | Node.js 20+, TypeScript 5+, starkzap repository workflows |
| keywords | ["starknet","starkzap","sdk","typescript","onboarding","wallet","privy","cartridge","paymaster","erc20","staking","tx-builder"] |
| allowed-tools | ["Bash","Read","Write","Glob","Grep","Task"] |
| user-invocable | true |
Project-focused guide for https://github.com/keep-starknet-strange/starkzap.
Use this skill when requests involve Starkzap SDK code, examples, or docs.
Trigger for tasks like:
Primary implementation:
src/sdk.ts - top-level orchestration (StarkSDK)src/wallet/* - wallet implementations and lifecyclesrc/signer/* - StarkSigner, PrivySigner, signer adaptersrc/tx/* - Tx and TxBuildersrc/erc20/* - token helpers, balance/transfer logicsrc/staking/* - staking operations and pool discoverysrc/types/* - shared domain types (Address, Amount, config)Operational and docs:
tests/* and tests/integration/*examples/web, examples/server, examples/mobile, examples/flappy-birdscripts/* for generated artifacts in the Starkzap repodocs/* and mintlify-docs/*Skill resources:
skills/starkzap-sdk/references/signer-integration.md - signer trust boundaries and auth assumptionsskills/starkzap-sdk/references/sponsored-transactions.md - paymaster flow and fee mode behaviorskills/starkzap-sdk/references/erc20-helpers.md - Amount semantics and transfer patternsskills/starkzap-sdk/references/staking-reliability.md - pool discovery and timeout/abort safetyskills/starkzap-sdk/scripts/wallet-execute-example.ts - wallet readiness and execute flowskills/starkzap-sdk/scripts/staking-pool-discovery.ts - staking pool discovery and diagnosticsCommon 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:
| 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. |
See also:
skills/starkzap-sdk/references/* for implementation-specific troubleshootingskills/starkzap-sdk/scripts/* for runnable diagnostic examplesStarkSDK and Connect WalletsCommon API path:
StarkSDK with network or rpcUrl + chainId.sdk.onboard(...) or sdk.connectWallet(...).wallet.ensureReady({ deploy: "if_needed" }) before user-pays writes.Supported onboarding strategies:
OnboardStrategy.SignerOnboardStrategy.PrivyOnboardStrategy.CartridgeFor Cartridge:
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" });
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:
OnboardStrategy.Cartridge is web-only).user_pays and sponsored branches in tests.ERC20 notes (starkzap-sdk internal token operations, no avnu required):
Amount with the token preset used for the call.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):
enter, add, exit intent, exit.For general DeFi operations (swaps, DCA, lending) and STRK staking via the avnu aggregator, use the starknet-defi skill.
Check for drift between:
examples/web/main.tsexamples/server/server.tsREADME and docs linksSpecifically verify endpoint and auth consistency for Privy + paymaster proxy flows.
Do not hand-edit generated files:
src/erc20/token/presets.tssrc/erc20/token/presets.sepolia.tssrc/staking/validator/presets.tssrc/staking/validator/presets.sepolia.tsdocs/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:
src/index.ts.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.
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:
examples/*.Bug fix in wallet lifecycle:
src/wallet/index.ts, src/wallet/utils.tstests/wallet*.test.tsPrivy auth/signature issue:
src/signer/privy.tsexamples/server/server.tstests/privy-signer.test.tsStaking regression:
src/staking/staking.ts, src/staking/presets.tstests/integration/staking.test.ts"Use this skill to fix Starkzap sponsored execution for undeployed accounts, add tests, and list behavior changes."