Skip to main content

U256 - Unsigned 256-bit Integer

The U256 type represents an unsigned 256-bit integer, the fundamental numeric type for handling large values in AssemblyScript Stylus smart contracts. It provides essential arithmetic and comparison operations for financial calculations and numeric logic.

Import​

import { U256, U256Factory } from '@as-stylus/as-stylus';

Overview​

U256 provides:

  • Range: 0 to 2^256 - 1
  • Basic arithmetic operations (add, subtract)
  • Comparison operations for conditional logic
  • String conversion for display and formatting
  • Factory methods for creation

Available Operations​

Based on the interface, U256 supports these operations:

Arithmetic Operations​

  • add(other: U256): U256 - Addition
  • sub(other: U256): U256 - Subtraction

Comparison Operations​

  • greaterThan(other: U256): boolean
  • greaterThanOrEqual(other: U256): boolean
  • lessThan(other: U256): boolean
  • lessThanOrEqual(other: U256): boolean
  • equals(other: U256): boolean - Equality comparison
  • Native operators: <, >, <=, >= - For use in comparisons

Conversion​

  • toString(): string - Convert to string representation
  • Automatic conversion for return values

Factory Methods​

  • U256Factory.create(): U256 - Create new U256 instance (value 0)
  • U256Factory.fromString(value: string): U256 - Create from string

Creation and Basic Usage​

Creating U256 Values​

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-nocheck

import { U256, U256Factory } from '@as-stylus/as-stylus';

// Create new U256 instance (value 0)
const zero = U256Factory.create();

// Create from string
const largeNumber = U256Factory.fromString("1000000000000000000000");
const smallNumber = U256Factory.fromString("42");

Basic Arithmetic​

const a = U256Factory.fromString("100");
const b = U256Factory.fromString("30");

// Addition
const sum = a.add(b); // 130

// Subtraction
const difference = a.sub(b); // 70

Comparison Operations​

const num1 = U256Factory.fromString("100");
const num2 = U256Factory.fromString("50");

// Using comparison methods
const isGreater = num1.greaterThan(num2);          // true
const isGreaterEqual = num1.greaterThanOrEqual(num2); // true
const isLess = num1.lessThan(num2);                // false
const isLessEqual = num1.lessThanOrEqual(num2);    // false
const isEqual = num1.equals(num2);                 // false

// Using native operators (recommended for readability)
if (num1 > num2) { /* logic here */ }
if (num1 < num2) { /* logic here */ }
if (num1.equals(num2)) { /* use equals for equality */ }

Contract Integration​

Basic Counter​

// eslint-disable-next-line @typescript-eslint/ban-ts-comment
// @ts-nocheck

@Contract
export class Counter {
  static counter: U256;

  constructor() {
    counter = U256Factory.create(); // Initialize to 0
  }

  @External
  static increment(): void {
    const delta = U256Factory.fromString("1");
    counter = counter.add(delta);
  }

  @External
  static decrement(): void {
    const delta = U256Factory.fromString("1");
    // Check underflow before subtracting
    if (counter >= delta) {
      counter = counter.sub(delta);
    }
  }

  @External
  static add(amount: U256): void {
    counter = counter.add(amount);
  }

  @External
  static set(value: U256): void {
    counter = value;
  }

  @View
  static get(): U256 {
    return counter;
  }

  @View
  static getAsString(): string {
    return counter.toString();
  }
}

Safe Operations​

Underflow Protection​

function safeSub(a: U256, b: U256): U256 {
  if (a < b) {
    // Revert with custom error
    const error = new InsufficientBalance();
    error.requested = b;
    error.available = a;
    error.revert();
  }
  return a.sub(b);
}

Range Validation​

function validateRange(value: U256, min: U256, max: U256): void {
  if (value < min) {
    const error = new InvalidAmount();
    error.provided = value;
    error.minimum = min;
    error.revert();
  }
  if (value > max) {
    const error = new InvalidAmount();
    error.provided = value;
    error.minimum = max; // Using minimum for maximum allowed
    error.revert();
  }
}

📦 More Data Types

U256Unsigned 256-bit integersI256Signed 256-bit integersAddressEthereum addressesStringText data handlingBooleanLogical true/false values