Algorand TypeScript SDK

What is Algorand TypeScript?

Algorand TypeScript is a partial implementation of the TypeScript programming language that runs on the Algorand Virtual Machine (AVM). It includes a statically typed framework for developing Algorand smart contracts and logic signatures, with TypeScript interfaces to underlying AVM functionality that works with standard TypeScript tooling.

It maintains the syntax and semantics of TypeScript, so a developer who knows TypeScript can make safe assumptions about the behavior of the compiled code when running on the AVM. Algorand TypeScript is also executable TypeScript that can be run and debugged on a Node.js virtual machine with transpilation to EcmaScript and run from automated tests.

Benefits of Using Algorand TypeScript

TypeScript Implementation for AVM

Algorand TypeScript maintains the syntax and semantics of TypeScript, supporting a subset of the language that will grow over time. However, due to the restricted nature of the AVM, it will never be a complete implementation.

Algorand TypeScript is compiled for execution on the AVM by PuyaTs, a TypeScript frontend for the Puya optimizing compiler that ensures the resulting AVM bytecode execution semantics that match the given TypeScript code. PuyaTs produces output directly compatible with AlgoKit-typed clients to simplify deployment and calling.

Key Differences from Standard TypeScript

// Standard: 1 results in int 1 in TEAL
const value = 1;

// Typed: 1 as uint8 results in byte 0x01
const typedValue = 1 as uint8;

Supported Primitives

Algorand TypeScript supports several primitive types and data structures that are optimized for blockchain operations. These primitives are designed to work efficiently with the AVM while maintaining familiar TypeScript syntax.

// Example: Array of 10 unsigned 64-bit integers
StaticArray<uint64, 10>

// Static arrays can be partially initialized
const x: StaticArray<uint64, 3> = [1]      // [1, undefined, undefined]
const y: StaticArray<uint64, 3> = [1, 0, 0] // [1, 0, 0]

// Iteration example
staticArrayIteration(): uint64 {
  const a: StaticArray<uint64, 3> = [1, 2, 3];
  let sum = 0;
  
  for (const v of a) {
    sum += v;
  }
  return sum; // 6
}

// These result in the same byteslice:
[uint64, uint8]
{ foo: uint64, bar: uint8 }

// Example usage
type MyType = { foo: uint64, bar: uint8 }
const x: MyType = { foo: 1, bar: 2}
const y: MyType = { bar: 2, foo: 1 }

Number Types

// Specific-width unsigned integers
uint8, uint16, uint32, uint64, uint128, uint256, uint512

// Correct: Unsigned 64-bit integer
const n1: UInt<64> = 1;

// Correct: Unsigned 8-bit integer
const n2: UInt<8> = 1;

// Correct: Unsigned 64-bit with two decimal places
const price: UFixed<64, 2> = 1.23;

// Incorrect: Missing type definition
const invalidPrice = 1.23; // ERROR: Missing type

// Incorrect: Precision exceeds defined decimal places
const invalidPrice2: UFixed<64, 2> = 1.234; // ERROR

Math Operations

Algorand TypeScript requires explicit handling of math operations to ensure type safety and prevent overflow errors. Basic arithmetic operations (+, -, *, /) are supported but require explicit type handling.

// Results must be explicitly typed using:

// Constructor
const sum = Uint64(x + y);

// Type annotation
const sum: uint64 = x + y;

// Return type annotation
function add(x: uint64, y: uint64): uint64 { 
  return x + y; 
}

// Overflow handling
const a = UintN8(255);
const b = UintN8(255);
const c = UintN8(a + b); // Error: Overflow

// Better performance approach
const a: uint64 = 255;
const b: uint64 = 255;
const c: uint64 = a + b;
return UintN8(c - 255); // Only convert at the end

Pass by Reference

All arrays and objects are passed by reference even if in contract state, much like TypeScript. Algorand TypeScript, however, will not let a function mutate an array that was passed as an argument. If you wish to pass by value you can use clone.

const x: uint64[] = [1, 2, 3];
const y = x;
y[0] = 4;

log(y); // [4, 2, 3]
log(x); // [4, 2, 3]

const z = clone(x);
z[1] = 5;

log(x); // [4, 2, 3] note x has NOT changed
log(z); // [4, 5, 3]

Limitations

PuyaTs Compiler

Algorand TypeScript is compiled for execution on the AVM by PuyaTs, a TypeScript frontend for the Puya optimizing compiler that ensures the resulting AVM bytecode execution semantics that match the given TypeScript code.

PuyaTs produces output that is directly compatible with AlgoKit typed clients to make deployment and calling easy. This seamless integration allows developers to use familiar TypeScript development workflows while targeting the Algorand blockchain.

Testing and Debugging

The algorand-typescript-testing package allows for efficient unit testing of Algorand TypeScript smart contracts in an offline environment. It emulates key AVM behaviors without requiring a network connection, offering fast and reliable testing capabilities with a familiar TypeScript interface.

// Example test structure
import { AlgodTestClient } from 'algorand-typescript-testing';

describe('MyContract', () => {
  it('should execute correctly', () => {
    const client = new AlgodTestClient();
    // Test your contract logic here
    expect(contract.method()).toBe(expectedResult);
  });
});

Best Practices