Build on Algorand
Build Algorand applications with TypeScript on both sides of the compilation
boundary:
- Contract TypeScript is the restricted Algorand TypeScript language that
PuyaTs compiles for the AVM. It is not general JavaScript.
- Client TypeScript runs off-chain and uses generated clients, AlgoKit Utils,
algosdk, and wallet signers.
Preserve that boundary. Never copy off-chain libraries, asynchronous code, or
ordinary JavaScript data models into a contract.
Start with the project
Read AGENTS.md, package.json, compiler configuration, and existing contract
and generated-client patterns before changing code. Use the project's pinned
dependencies and npm scripts. Do not introduce Python or the AlgoKit CLI, and
do not replace the project's stack or add a dependency when its existing tools
cover the task.
When working in a VibeKit-configured project, load use-vibekit for project
lifecycle, LocalNet, accounts, signing, network selection, deployment, and
on-chain operations. This skill covers the application code and design.
Choose the guide
| Task |
Guide |
| Reason about applications, Logic Signatures, execution budgets, resources, fees, or protocol capabilities |
AVM fundamentals |
| Write or review Algorand TypeScript contract types, methods, control flow, or ABI surfaces |
PuyaTs contracts |
| Choose state, use boxes, inspect group transactions, or emit inner transactions |
State and transactions |
| Generate or consume typed clients, test contracts, simulate calls, or debug failures |
Clients and testing |
| Connect a browser wallet or pass a wallet signer to a generated client |
Frontend wallets |
| Harden an implementation or perform an ordinary contract-safety review |
Security |
| Move from TEALScript, Algorand TypeScript beta, ARC-32, or older client APIs |
Migrations |
| Select an application, ASA, token, NFT, event, or multisig ARC |
Standards |
| Orient a TypeScript client or resource server to x402 on Algorand |
x402 |
Load only the references needed for the current task.
Load audit-algorand for a structured vulnerability assessment, threat model,
exploit analysis, mainnet-readiness review, or security finding report. This
skill remains the owner of implementation and routine defensive review.
Contract invariants
- Do not use the TypeScript
number type in contract code. Use AVM-native
types such as uint64, biguint, and bytes, or explicit ARC-4 types.
Numeric literals still need an AVM type from context or a constructor.
- Treat arrays, objects, byte strings, storage, and arithmetic according to
PuyaTs semantics. Use
clone(value) when an independent array or object is
required.
- Prefer ARC-4 ABI methods and an ARC-56 application specification for public
applications and generated clients. Accept ARC-32 only where existing tools
or artifacts require it.
- Validate every relevant field of transaction arguments. A transaction's
group position or type alone does not prove its sender, receiver, amount,
asset, application, close address, or rekey target.
- Account for opcode budget, program size, transaction fees, app-call
resources, box I/O budget, and minimum-balance changes during design.
- Make update, delete, opt-in, close-out, and clear-state behavior explicit.
Default-deny lifecycle actions the application does not need.
- On a compile error, read the installed
@algorandfoundation/algorand-typescript/*.d.ts declaration the error
names, or the linked example, before changing the code. Do not iterate from
memory. The package is split by topic: state.d.ts (Global/Local state),
box.d.ts, arc4/index.d.ts (abimethod, allowActions, ARC-4 types),
itxn.d.ts, gtxn.d.ts, op.d.ts (AVM ops), on-complete-action.d.ts.
- Compile and test the generated TEAL behavior. Use
simulate for execution
traces and fee/resource diagnosis; do not use removed dryrun or tealdbg
workflows.
Canonical starting points
Material adapted from an upstream MIT-licensed skill set is documented in
Attribution.
1---2name: build-on-algorand3description: Build and review TypeScript-only Algorand applications using the AVM, PuyaTs, generated clients, tests, browser wallets, and relevant ARCs. Use for contracts, assets and tokens, client or frontend integration, defensive implementation, migrations, and x402 orientation. Excludes structured security audits and finding reports, Python, project lifecycle, LocalNet, accounts, deployment operations, and VibeKit extension development.4---56# Build on Algorand78Build Algorand applications with TypeScript on both sides of the compilation9boundary:1011- **Contract TypeScript** is the restricted Algorand TypeScript language that12 PuyaTs compiles for the AVM. It is not general JavaScript.13- **Client TypeScript** runs off-chain and uses generated clients, AlgoKit Utils,14 algosdk, and wallet signers.1516Preserve that boundary. Never copy off-chain libraries, asynchronous code, or17ordinary JavaScript data models into a contract.1819## Start with the project2021Read `AGENTS.md`, `package.json`, compiler configuration, and existing contract22and generated-client patterns before changing code. Use the project's pinned23dependencies and npm scripts. Do not introduce Python or the AlgoKit CLI, and24do not replace the project's stack or add a dependency when its existing tools25cover the task.2627When working in a VibeKit-configured project, load `use-vibekit` for project28lifecycle, LocalNet, accounts, signing, network selection, deployment, and29on-chain operations. This skill covers the application code and design.3031## Choose the guide3233| Task | Guide |34| --- | --- |35| Reason about applications, Logic Signatures, execution budgets, resources, fees, or protocol capabilities | [AVM fundamentals](references/avm-fundamentals.md) |36| Write or review Algorand TypeScript contract types, methods, control flow, or ABI surfaces | [PuyaTs contracts](references/puyats-contracts.md) |37| Choose state, use boxes, inspect group transactions, or emit inner transactions | [State and transactions](references/state-and-transactions.md) |38| Generate or consume typed clients, test contracts, simulate calls, or debug failures | [Clients and testing](references/clients-and-testing.md) |39| Connect a browser wallet or pass a wallet signer to a generated client | [Frontend wallets](references/frontend-wallets.md) |40| Harden an implementation or perform an ordinary contract-safety review | [Security](references/security.md) |41| Move from TEALScript, Algorand TypeScript beta, ARC-32, or older client APIs | [Migrations](references/migrations.md) |42| Select an application, ASA, token, NFT, event, or multisig ARC | [Standards](references/standards.md) |43| Orient a TypeScript client or resource server to x402 on Algorand | [x402](references/x402.md) |4445Load only the references needed for the current task.4647Load `audit-algorand` for a structured vulnerability assessment, threat model,48exploit analysis, mainnet-readiness review, or security finding report. This49skill remains the owner of implementation and routine defensive review.5051## Contract invariants5253- Do not use the TypeScript `number` type in contract code. Use AVM-native54 types such as `uint64`, `biguint`, and `bytes`, or explicit ARC-4 types.55 Numeric literals still need an AVM type from context or a constructor.56- Treat arrays, objects, byte strings, storage, and arithmetic according to57 PuyaTs semantics. Use `clone(value)` when an independent array or object is58 required.59- Prefer ARC-4 ABI methods and an ARC-56 application specification for public60 applications and generated clients. Accept ARC-32 only where existing tools61 or artifacts require it.62- Validate every relevant field of transaction arguments. A transaction's63 group position or type alone does not prove its sender, receiver, amount,64 asset, application, close address, or rekey target.65- Account for opcode budget, program size, transaction fees, app-call66 resources, box I/O budget, and minimum-balance changes during design.67- Make update, delete, opt-in, close-out, and clear-state behavior explicit.68 Default-deny lifecycle actions the application does not need.69- On a compile error, read the installed70 `@algorandfoundation/algorand-typescript/*.d.ts` declaration the error71 names, or the linked example, before changing the code. Do not iterate from72 memory. The package is split by topic: `state.d.ts` (Global/Local state),73 `box.d.ts`, `arc4/index.d.ts` (`abimethod`, `allowActions`, ARC-4 types),74 `itxn.d.ts`, `gtxn.d.ts`, `op.d.ts` (AVM ops), `on-complete-action.d.ts`.75- Compile and test the generated TEAL behavior. Use `simulate` for execution76 traces and fee/resource diagnosis; do not use removed `dryrun` or `tealdbg`77 workflows.7879## Canonical starting points8081- [Smart-contract overview](https://dev.algorand.co/concepts/smart-contracts/overview/)82- [Algorand TypeScript language guide](https://dev.algorand.co/concepts/smart-contracts/languages/typescript/)83- [PuyaTs examples](https://github.com/algorandfoundation/puya-ts/tree/main/examples)84- [PuyaTs devportal examples](https://github.com/algorandfoundation/puya-ts/tree/main/examples/devportal)85- [AlgoKit Utils TypeScript examples](https://github.com/algorandfoundation/algokit-utils-ts/tree/docs-staging/examples)86- [ARC repository](https://github.com/algorandfoundation/ARCs/tree/main/ARCs)8788Material adapted from an upstream MIT-licensed skill set is documented in89[Attribution](ATTRIBUTION.md).
initlabsai