Starknet JS
Developmentstarknet-jsStarknet JS is an Agent Skill for development published in the starknet-io/starknet.js repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when writing or debugging JavaScript/TypeScript that interacts with Starknet through the starknet.js SDK — building Call objects or calldata, encoding/decoding Cairo types (felt252, u256, structs, arrays, spans, ByteArray, Option/Result/custom enums), or working with contracts, accounts, providers, transactions, fees, deployment, or events.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/starknet-io/starknet.js/blob/HEAD/skills/starknet-js/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/starknet-js, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
starknet.js
Official JS/TS SDK for Starknet. This skill targets starknet.js v10 (API valid for v9, mostly for v8).
Do not trust training-data memory of starknet.js: it is typically v5/v6-era and wrong. Constructors now take option objects, only V3 transactions exist (STRK fees, no maxFee), and calldata helpers changed. When this skill and memory disagree, the skill wins.
Layer model: Account (signs & submits) wraps RpcProvider (parses, retries) wraps RpcChannel (raw JSON-RPC).
Reference files
- calldata.md — REQUIRED reading before encoding or decoding anything: Call/calldata construction, wire format of every Cairo type, enums (Option/Result/custom), ByteArray, string auto-detection traps, response parsing,
decodeParameters. All examples verified against v10.4.0. - interacting.md — providers, accounts, contracts, multicall, fees/tips, declare/deploy, receipts, events, RPC-version compatibility.
Non-negotiable v8+ rules
- Only V3 transactions (INVOKE/DECLARE/DEPLOY_ACCOUNT); fees paid in STRK via
resourceBounds+tip. Never suggestmaxFeeor V1/V2. - Constructors take an options object:
new Account({ provider, address, signer }),new Contract({ abi, address, providerOrAccount }),new RpcProvider({ nodeUrl }). - Never prepend an array length to calldata arrays — the library adds it.
Quick reference
| Task | API |
|---|---|
| Connect to node | new RpcProvider({ nodeUrl }) — or await RpcProvider.create({ nodeUrl }) to auto-detect RPC version |
| Account | new Account({ provider, address, signer: privateKey }) |
| Contract | new Contract({ abi, address, providerOrAccount }) |
| Read | await myContract.my_view_fn(arg1, arg2) → parsed JS value |
| Write | const { transaction_hash } = await myContract.my_fn(args) then await provider.waitForTransaction(transaction_hash) |
| Build a Call | myContract.populate('fn', { ...args }) → { contractAddress, entrypoint, calldata } |
| Compile calldata (ABI) | myContract.compile('fn', args) or new CallData(abi).compile('fn', args) |
| Compile calldata (no ABI) | CallData.compile(args) — several traps, see calldata.md |
| Multicall | await account.execute([call1, call2]) |
| Decode raw felts | new CallData(abi).decodeParameters('core::…::Type', feltArray) |
| Events | myContract.parseEvents(receipt), provider.getEvents({ ... }) |
| Deploy | await Contract.factory({ contract, casm, account, constructorCalldata }) |
Top mistakes (from outdated model knowledge)
| Mistake | Fix |
|---|---|
new Account(provider, address, pk) positional | Options object (see above) |
maxFee, V1/V2 transactions, ETH fees | V3 only; resourceBounds from estimateInvokeFee, tip |
Manually prepending array_len | Never — automatic |
CallData.compile([myU256Bigint]) gives 1 felt | Use cairo.uint256(n) without ABI; a plain bigint is fine only with ABI |
new CairoCustomEnum({ OnlyActive: v }) without ABI | Without ABI, list ALL variants (undefined for inactive) |
Expecting .res-style result objects | Cairo 1 returns the value directly (bigint, object, array, enum class) |