Introduction

Quick start

TypeSOL is not on npm yet. Install it from this repository:

git clone https://github.com/typesol/typesol.git && cd typesol
pnpm install && pnpm build && npm link       # puts `typesol` on your PATH

You also need the Agave CLI (sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"). Run cargo-build-sbf --version once; this downloads the platform-tools that TypeSOL compiles with. Rust is not needed.

typesol init my-app --name counter      # typesol.json, programs/counter.ts, tests/counter.test.ts, tsconfig
cd my-app && npm install ../typesol      # path to your clone (later: plain `npm install`)
npm test                                # builds the program and runs it in LiteSVM, an in-process Solana runtime
typesol build                           # target/counter/{counter.so, counter.json (IDL), counter.build.json}
typesol deploy --url http://127.0.0.1:8899 --keypair ~/.config/solana/id.json

Deploying again upgrades the program in place. Keep target/deploy/<name>-keypair.json: that keypair is your program's address.

How it works

counter.ts ─▶ tsc typecheck ─▶ subset check ─▶ C + typesol_rt.h ─▶ clang -target sbf ─▶ counter.so
                                      └────────────────────────────────────────────────▶ counter.json (Anchor IDL)

1. Typecheck. The TypeScript compiler checks your code against lib/typesol.d.ts, which declares every TypeSOL type and built-in.
2. Subset check. TypeSOL rejects anything outside the language (floats, closures, classes, any, foreign imports) with a file:line:col diagnostic. Nothing is half-supported.
3. Lower. Instruction bodies become C. Account validation, checked arithmetic, Borsh encoding and CPI plumbing come from runtime/typesol_rt.h.
4. Build. The Agave platform-tools clang and ld.lld produce the .so (SBPF v0 by default; v1 and v2 with --sbpf).

Runtime failures point back to your source: Error 6000 Unauthorized (counter.ts:21), or TypeSOL: arithmetic overflow (vault.ts:42).

Requirements

• Node.js 22.12 or later.
• The Agave CLI with platform-tools.
• macOS or Linux. On Windows, use WSL2.

TypeSOL finds the SDK under ~/.local/share/solana/install/active_release or next to cargo-build-sbf on PATH. Set TYPESOL_SBF_SDK to override the location. See docs/troubleshooting.md.

Status

0.10 is a release candidate.

• The compiler, runtime and tooling have been through internal security reviews and are covered by the tests above.
• They have not been audited by an independent firm. Do not put significant value behind programs built with TypeSOL until such an audit is published.
• Audit your own programs as you would any Solana program.
• Report vulnerabilities as described in SECURITY.md.

Not supported yet: see the end of docs/language.md.