Overview

export type BrandedStorageKey = {
  readonly address: AddressType;
  readonly slot: bigint;
};

import * as State from 'tevm/State';
import * as Address from 'tevm/Address';

// Create storage key
const contractAddr = Address("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");
const key = State.StorageKey(contractAddr, 0n);

// Use in storage maps
const storage = new Map<string, bigint>();
storage.set(State.StorageKey.toString(key), 1000000000n);

// Retrieve value
const value = storage.get(State.StorageKey.toString(key)); // 1000000000n

import * as State from 'tevm/State';

const key = State.StorageKey(contractAddress, 42n);

// Convert to string for map keys
const keyStr = State.StorageKey.toString(key);
// "0x742d35cc6634c0532925a3b844bc9e7595f51e3e:42"

// Parse from string
const parsed = State.StorageKey(keyStr);
// { address: AddressType(...), slot: 42n }

// Round-trip conversion
State.StorageKey.equals(key, parsed); // true

import * as State from 'tevm/State';
import * as Address from 'tevm/Address';
import { Keccak256 } from 'tevm/crypto';

// USDC contract
const usdcAddress = Address("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48");

// Storage slot 0: total supply
const totalSupplyKey = State.StorageKey(usdcAddress, 0n);

// Mapping storage: balanceOf[userAddress]
// Slot = keccak256(abi.encode(userAddress, balanceSlot))
const userAddress = Address("0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e");
const balanceSlot = 1n;

// Compute mapping slot (Solidity storage layout)
const mappingSlotBytes = Bytes64();
mappingSlotBytes.set(userAddress, 0);          // First 32 bytes (padded address)
mappingSlotBytes.set(encodeBigInt(balanceSlot, 32), 32); // Last 32 bytes

const computedSlot = BigInt(Hex.fromBytes(
  Keccak256.hash(mappingSlotBytes)
).toString('hex'));

const userBalanceKey = State.StorageKey(usdcAddress, computedSlot);

import * as State from 'tevm/State';

// Track state across multiple contracts
const stateDb = new Map<string, bigint>();

// USDC total supply
const usdcKey = State.StorageKey(usdcAddress, 0n);
stateDb.set(State.StorageKey.toString(usdcKey), 1000000000n);

// DAI total supply
const daiKey = State.StorageKey(daiAddress, 0n);
stateDb.set(State.StorageKey.toString(daiKey), 5000000000n);

// Query by contract
for (const [keyStr, value] of stateDb.entries()) {
  const key = State.StorageKey(keyStr);
  if (Address.equals(key.address, usdcAddress)) {
    console.log(`USDC slot ${key.slot}: ${value}`);
  }
}

import * as State from 'tevm/State';

function processStorage(key: unknown) {
  if (State.StorageKey.is(key)) {
    // TypeScript knows key is BrandedStorageKey
    console.log(`Address: ${Address.toHex(key.address)}`);
    console.log(`Slot: ${key.slot}`);
  }
}

// Import specific functions (tree-shakeable)
import { StorageKey, toString, fromString } from 'tevm/State';

const key = StorageKey(contractAddress, 0n);
const keyStr = toString(key);
const parsed = fromString(keyStr);

// Only these 3 functions included in bundle