TLOAD (0x5c)

key (256-bit storage slot address)

value (256-bit value, or 0 if uninitialized)

key = pop()
value = transientStorage[msg.sender][key]  // 0 if never written
push(value)
gasRemaining -= 100

TLOAD(key)  // Returns 0 if key was never written

// Transaction 1
TSTORE(key, 0x1234)
TLOAD(key)  // 0x1234

// Transaction 2 (new transaction)
TLOAD(key)  // 0 (cleared from TX1)

import { tload } from '@voltaire/evm/storage';
import { createFrame } from '@voltaire/evm/Frame';
import { createMemoryHost } from '@voltaire/evm/Host';

const host = createMemoryHost();
const frame = createFrame({
  stack: [0x42n],  // Key to read
  gasRemaining: 3000n,
  address: contractAddr,
});

// Pre-populate transient storage (e.g., from TSTORE)
host.setTransientStorage(contractAddr, 0x42n, 0x1337n);

// Execute TLOAD
const error = tload(frame, host);

console.log(frame.stack);        // [0x1337n]
console.log(frame.gasRemaining); // 2900n (3000 - 100)
console.log(error);              // null

// Reentrancy guard using transient storage
const guardKey = 0x01n;

// Check guard is unlocked
const readFrame = createFrame({
  stack: [guardKey],
  gasRemaining: 3000n,
  address: contractAddr,
});
tload(readFrame, host);

if (readFrame.stack[0] !== 0n) {
  return { type: "ReentrancyDetected" };
}

// Lock before call
const lockFrame = createFrame({
  stack: [guardKey, 0x1n],
  gasRemaining: 3000n,
  address: contractAddr,
});
tstore(lockFrame, host);

// ... perform call ...

// Unlock after call
const unlockFrame = createFrame({
  stack: [guardKey, 0n],
  gasRemaining: 3000n,
  address: contractAddr,
});
tstore(unlockFrame, host);

// Store multiple values in transient storage
const keys = {
  FLAG: 0x01n,
  COUNTER: 0x02n,
  BALANCE: 0x03n,
};

// Read all values
const values = {};
for (const [name, key] of Object.entries(keys)) {
  const frame = createFrame({
    stack: [key],
    gasRemaining: 1000n,
    address: contractAddr,
  });
  tload(frame, host);
  values[name] = frame.stack[0];
}

console.log(values);
// {
//   FLAG: 0x0n,
//   COUNTER: 0x42n,
//   BALANCE: 0xDEADBEEFn
// }

// Within transaction: Persist across calls
const host = createMemoryHost();
const addr = contractAddr;

// Set value
let frame = createFrame({
  stack: [0x42n, 0x1337n],
  gasRemaining: 3000n,
  address: addr,
});
tstore(frame, host);

// Read value (same transaction, same call)
frame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: addr,
});
tload(frame, host);
console.log(frame.stack);  // [0x1337n]

// At transaction end: Automatically cleared
// endTransaction(host, addr);
//
// Next transaction:
// frame = createFrame({
//   stack: [0x42n],
//   gasRemaining: 3000n,
//   address: addr,
// });
// tload(frame, host);
// console.log(frame.stack);  // [0n] - cleared!

// Contract A stores data for contract B to read
contract A {
  function callB(address b) public {
    // Store context for B
    assembly {
      tstore(0x01, caller())  // Store caller
      tstore(0x02, 42)        // Store arbitrary data
    }

    // Call B (B can read transient storage)
    IContractB(b).doSomething();

    // Transient storage still available after call
    // (until transaction ends)
  }
}

contract B {
  function doSomething() public {
    // Read context from A
    address caller;
    uint256 data;
    assembly {
      caller := tload(0x01)
      data := tload(0x02)
    }

    // Use caller and data
    require(data == 42);
  }
}

const frame = createFrame({
  stack: [0x42n],
  gasRemaining: 50n,  // < 100
  address: contractAddr,
});

const error = tload(frame, host);
console.log(error);  // { type: "OutOfGas" }
console.log(frame.pc);  // 0 (unchanged, not executed)

TLOAD: 100 gas (transient, shared across calls)
MSTORE/MLOAD: 3 gas (local to call, memory-only)
SLOAD warm: 100 gas (persistent, per-transaction)
SLOAD cold: 2100 gas (persistent, expensive)

const frame = createFrame({
  stack: [0xDEADBEEFn],  // Key never written
  gasRemaining: 3000n,
  address: contractAddr,
});

tload(frame, host);
console.log(frame.stack);  // [0n]

const MAX_KEY = (1n << 256n) - 1n;
const frame = createFrame({
  stack: [MAX_KEY],
  gasRemaining: 3000n,
  address: contractAddr,
});

tload(frame, host);
console.log(frame.stack);  // [0n] or stored value

// TLOAD not available before Cancun
// If hardfork < CANCUN:
const frame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: contractAddr,
  hardfork: "Shanghai",  // < Cancun
});

const error = tload(frame, host);
console.log(error);  // { type: "InvalidOpcode" }

// Stack overflow when full
const fullStack = new Array(1024).fill(0n);
const frame = createFrame({
  stack: fullStack,
  gasRemaining: 3000n,
  address: contractAddr,
});

const error = tload(frame, host);
console.log(error);  // { type: "StackOverflow" }

// EIP-1153 reentrancy guard (cheaper than storage)
contract Safe {
  uint256 private constant LOCKED = 1;

  function _nonReentrant() internal {
    assembly {
      // Check: guard must be unlocked (0)
      if tload(0) { revert(0, 0) }
      // Lock: set guard to LOCKED
      tstore(0, LOCKED)
    }
  }

  function _nonReentrantEnd() internal {
    assembly {
      // Unlock: clear guard
      tstore(0, 0)
    }
  }

  function safeTransfer(address to, uint256 amount) public {
    _nonReentrant();

    uint256 balance = balances[msg.sender];
    require(balance >= amount);

    balances[msg.sender] = balance - amount;

    // Reentrancy window: attacker re-enters, guard prevents nested call
    (bool ok, ) = to.call{value: amount}("");

    _nonReentrantEnd();
    require(ok);
  }
}

// Multicall pattern using transient storage
contract Multicall {
  function multicall(
    address[] calldata targets,
    bytes[] calldata data
  ) public {
    for (uint i = 0; i < targets.length; i++) {
      // Store callback context
      assembly {
        tstore(0x01, i)
        tstore(0x02, caller())
      }

      // Target can read context with TLOAD
      (bool ok, ) = targets[i].call(data[i]);
      require(ok);
    }
    // Context cleared at tx end
  }
}

contract Target {
  function execute(bytes calldata data) external {
    // Read callback context
    uint256 index;
    address caller;
    assembly {
      index := tload(0x01)
      caller := tload(0x02)
    }

    // Use index and caller for context-aware logic
  }
}

contract Counter {
  uint256 public globalCount;

  function batchIncrement(uint256 count) public {
    // Use transient counter for temp state (100 gas per operation)
    assembly {
      tstore(0x01, 0)  // temp counter = 0
    }

    for (uint i = 0; i < count; i++) {
      // Increment temp counter
      assembly {
        let c := tload(0x01)
        tstore(0x01, add(c, 1))
      }
    }

    // Write final count to storage once (20000 or 5000 gas)
    assembly {
      globalCount := tload(0x01)
    }
  }
}

// Store delegation context for called contracts
contract Delegator {
  function delegatedCall(
    address target,
    bytes calldata data,
    bytes calldata context
  ) public {
    // Store context for target
    assembly {
      tstore(0x01, context)
    }

    // Target executes knowing context
    (bool ok, bytes memory result) = target.call(data);
    require(ok);

    // Context automatically cleared by transaction end
  }
}

import { describe, it, expect } from 'vitest';
import { tload } from './0x5c_TLOAD.js';
import { tstore } from './0x5d_TSTORE.js';
import { createFrame } from '../../Frame/index.js';
import { createMemoryHost } from '../../Host/createMemoryHost.js';
import { from as addressFrom } from '../../../primitives/Address/index.js';

describe('TLOAD (0x5c)', () => {
  it('loads value from transient storage', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

    // Pre-populate transient storage
    host.setTransientStorage(addr, 0x42n, 0x1337n);

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr,
    });

    expect(tload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0x1337n]);
    expect(frame.pc).toBe(1);
    expect(frame.gasRemaining).toBe(900n);  // 1000 - 100
  });

  it('loads zero for uninitialized slot', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr,
    });

    expect(tload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0n]);
  });

  it('isolates transient storage by address', () => {
    const host = createMemoryHost();
    const addr1 = addressFrom("0x1111111111111111111111111111111111111111");
    const addr2 = addressFrom("0x2222222222222222222222222222222222222222");

    host.setTransientStorage(addr1, 0x42n, 0xAAAAn);
    host.setTransientStorage(addr2, 0x42n, 0xBBBBn);

    let frame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr1,
    });
    expect(tload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0xAAAAn]);

    frame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr2,
    });
    expect(tload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([0xBBBBn]);
  });

  it('consumes fixed 100 gas', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");
    host.setTransientStorage(addr, 0x42n, 0x1337n);

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 5000n,
      address: addr,
    });

    expect(tload(frame, host)).toBeNull();
    expect(frame.gasRemaining).toBe(4900n);  // 5000 - 100 (always)
  });

  it('returns StackUnderflow on empty stack', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [],
      gasRemaining: 1000n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(tload(frame, host)).toEqual({ type: "StackUnderflow" });
  });

  it('returns OutOfGas when insufficient gas', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 50n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(tload(frame, host)).toEqual({ type: "OutOfGas" });
  });

  it('returns StackOverflow when stack full', () => {
    const host = createMemoryHost();
    const fullStack = new Array(1024).fill(0n);

    const frame = createFrame({
      stack: fullStack,
      gasRemaining: 1000n,
      address: addressFrom("0x1111111111111111111111111111111111111111"),
    });

    expect(tload(frame, host)).toEqual({ type: "StackOverflow" });
  });

  it('loads max uint256 value', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");
    const MAX = (1n << 256n) - 1n;

    host.setTransientStorage(addr, 0x42n, MAX);

    const frame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr,
    });

    expect(tload(frame, host)).toBeNull();
    expect(frame.stack).toEqual([MAX]);
  });

  it('persists within transaction, clears on boundary', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

    // Write value
    const writeFrame = createFrame({
      stack: [0x42n, 0x1337n],
      gasRemaining: 1000n,
      address: addr,
      isStatic: false,
    });
    tstore(writeFrame, host);

    // Read value (same transaction)
    const readFrame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr,
    });
    expect(tload(readFrame, host)).toBeNull();
    expect(readFrame.stack).toEqual([0x1337n]);

    // After transaction boundary (cleared automatically)
    // host.endTransaction();
    // const newReadFrame = createFrame({
    //   stack: [0x42n],
    //   gasRemaining: 1000n,
    //   address: addr,
    // });
    // expect(tload(newReadFrame, host)).toBeNull();
    // expect(newReadFrame.stack).toEqual([0n]);
  });
});

function read(uint256 key) public view returns (uint256) {
  uint256 value;
  assembly {
    value := tload(key)  // Always safe, read-only
  }
  return value;
}

contract Safe {
  function guarded() public {
    assembly {
      if tload(0) { revert(0, 0) }  // Check guard
      tstore(0, 1)                  // Lock
    }

    // Call external contract
    (bool ok, ) = msg.sender.call("");
    require(ok);

    // Even if call fails here, guard is locked
    // Attacker cannot re-enter

    assembly {
      tstore(0, 0)  // Unlock
    }
  }
}

// Contract A cannot read/write Contract B's transient storage
contract A {
  function tryRead() public {
    uint256 value;
    assembly {
      value := tload(0x42)  // Reads A's transient storage
    }
    // Cannot access B's TSTORE values
  }
}

// No risk of incomplete state
function operation() public {
  assembly {
    tstore(0x01, 1)  // Temporary state
  }

  // Even if transaction reverts here:
  // TLOAD(0x01) returns 0 in next transaction
  // No leftover state to clean up
}

Storage-based guard:
- Check: SLOAD cold (2100) → warm (100)
- Set: SSTORE (20000 or 5000)
- Clear: SSTORE (5000 + 4800 refund)
- Total: ~22100 gas

Transient-based guard (EIP-1153):
- Check: TLOAD (100)
- Set: TSTORE (100)
- Clear: TSTORE (100)
- Total: 300 gas (73x cheaper!)