TSTORE (0x5d)

key (256-bit storage slot address)
value (256-bit value to store)

(none - consumes both inputs)

key = pop()
value = pop()

// Cannot be called in static context
if (isStatic) revert

transientStorage[msg.sender][key] = value
gasRemaining -= 100

// In STATICCALL context
TSTORE(key, value)  // WriteProtection error

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

const host = createMemoryHost();
const frame = createFrame({
  stack: [0x42n, 0x1337n],  // [key, value]
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

const error = tstore(frame, host);

console.log(error);              // null (success)
console.log(frame.gasRemaining); // 2900n (3000 - 100)

// Verify write
const readFrame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: contractAddr,
});
tload(readFrame, host);
console.log(readFrame.stack);    // [0x1337n]

// Set guard lock before external call
const guardKey = 0x01n;

const frame = createFrame({
  stack: [guardKey, 0x1n],  // [key, locked]
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

const error = tstore(frame, host);

console.log(error);              // null
console.log(frame.gasRemaining); // 2900n

// Now TLOAD(0x01) in reentrant call returns locked

// Clear guard after external call returns
const guardKey = 0x01n;

const frame = createFrame({
  stack: [guardKey, 0n],  // [key, unlocked]
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

const error = tstore(frame, host);

console.log(error);              // null
console.log(frame.gasRemaining); // 2900n

// Store multiple transient values
const writes = [
  { key: 0x01n, value: 0xAAAAAn },  // FLAG
  { key: 0x02n, value: 0xBBBBBn },  // COUNTER
  { key: 0x03n, value: 0xCCCCCn },  // BALANCE
];

let remaining = 5000n;
for (const { key, value } of writes) {
  const frame = createFrame({
    stack: [key, value],
    gasRemaining: remaining,
    address: contractAddr,
    isStatic: false,
  });

  const error = tstore(frame, host);
  if (error) {
    console.error(`Failed: ${error.type}`);
    break;
  }
  remaining -= 100n;
}

console.log(`Stored ${writes.length} values, gas remaining: ${remaining}`);

// TSTORE fails in static call context
const frame = createFrame({
  stack: [0x42n, 0x1337n],
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: true,  // Static call
});

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

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

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

const frame = createFrame({
  stack: [0x42n],  // Missing value
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

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

TSTORE: 100 gas (transient, auto-cleanup)
SSTORE set: 20000 gas (persistent, complex)
SSTORE update: 5000 gas (persistent, still expensive)
MSTORE: 3 gas (memory, not persistent)

const MAX = (1n << 256n) - 1n;
const frame = createFrame({
  stack: [0x42n, MAX],
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

const error = tstore(frame, host);
console.log(error);  // null

// Verify stored
const readFrame = createFrame({
  stack: [0x42n],
  gasRemaining: 3000n,
  address: contractAddr,
});
tload(readFrame, host);
console.log(readFrame.stack);  // [MAX]

// Writing 0 still costs 100 gas (no noop optimization)
const frame = createFrame({
  stack: [0x42n, 0n],  // [key, value=0]
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});

const error = tstore(frame, host);
console.log(frame.gasRemaining);  // 2900n (always 100 cost)

// Writing again to same key just overwrites (100 gas)
const frame1 = createFrame({
  stack: [0x42n, 0x1111n],
  gasRemaining: 3000n,
  address: contractAddr,
  isStatic: false,
});
tstore(frame1, host);

const frame2 = createFrame({
  stack: [0x42n, 0x2222n],  // Overwrite
  gasRemaining: 2900n,
  address: contractAddr,
  isStatic: false,
});
tstore(frame2, host);

// Reads 0x2222n now
const readFrame = createFrame({
  stack: [0x42n],
  gasRemaining: 2800n,
  address: contractAddr,
});
tload(readFrame, host);
console.log(readFrame.stack);  // [0x2222n]

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

// Would need hardfork check
// const error = tstore(frame, host);
// console.log(error);  // { type: "InvalidOpcode" }

// Complete reentrancy guard using TSTORE
contract ReentrancyGuard {
  uint256 constant private LOCKED = 1;

  modifier nonReentrant() {
    // Check guard is unlocked
    assembly {
      if tload(0) {
        revert(0, 0)
      }
      // Lock
      tstore(0, LOCKED)
    }

    _;

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

  function safeSend(address recipient, uint256 amount)
    public
    nonReentrant
  {
    uint256 balance = balances[msg.sender];
    require(balance >= amount);

    balances[msg.sender] = balance - amount;

    // Reentrancy window: attacker cannot re-enter due to guard
    (bool ok, ) = recipient.call{value: amount}("");
    require(ok);
  }
}

// Pass context to called contracts via transient storage
contract Router {
  function route(
    address target,
    bytes calldata data,
    bytes calldata context
  ) public returns (bytes memory) {
    // Store context for target
    assembly {
      let ctxPtr := mload(0x40)
      calldatacopy(ctxPtr, context.offset, context.length)
      tstore(0x01, ctxPtr)
    }

    // Target can read context with TLOAD
    (bool ok, bytes memory result) = target.call(data);
    require(ok);

    // Context auto-cleared at transaction end
    return result;
  }
}

contract Handler {
  function handle(bytes calldata data) external {
    // Read context from caller
    uint256 ctxPtr;
    assembly {
      ctxPtr := tload(0x01)
    }

    // Process data with context
    _process(data, ctxPtr);
  }
}

// Efficient counter for batch operations
contract Batcher {
  function batchProcess(
    address[] calldata items,
    bytes[] calldata operations
  ) public {
    // Initialize counter in transient storage (100 gas)
    assembly {
      tstore(0x01, 0)
    }

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

      // Process item
      _process(items[i], operations[i]);
    }

    // Read final count
    uint256 processed;
    assembly {
      processed := tload(0x01)
    }

    emit BatchCompleted(processed);
    // Counter auto-cleared at transaction end
  }
}

// Accumulate results across multiple calls
contract Accumulator {
  function aggregate(
    address[] calldata targets,
    bytes[] calldata calls
  ) public returns (uint256 total) {
    // Initialize accumulator
    assembly {
      tstore(0x01, 0)
    }

    for (uint i = 0; i < targets.length; i++) {
      // Call target
      (bool ok, bytes memory result) = targets[i].call(calls[i]);
      require(ok);

      // Accumulate result
      uint256 value = abi.decode(result, (uint256));
      assembly {
        let acc := tload(0x01)
        tstore(0x01, add(acc, value))
      }
    }

    // Read final accumulated value
    assembly {
      total := tload(0x01)
    }
  }
}

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

describe('TSTORE (0x5d)', () => {
  it('stores value to transient storage', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

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

    expect(tstore(frame, host)).toBeNull();
    expect(frame.gasRemaining).toBe(900n);  // 1000 - 100
    expect(frame.pc).toBe(1);

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

  it('overwrites existing transient value', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

    // First write
    let frame = createFrame({
      stack: [0x42n, 0x1111n],
      gasRemaining: 1000n,
      address: addr,
      isStatic: false,
    });
    expect(tstore(frame, host)).toBeNull();

    // Overwrite
    frame = createFrame({
      stack: [0x42n, 0x2222n],
      gasRemaining: 1000n,
      address: addr,
      isStatic: false,
    });
    expect(tstore(frame, host)).toBeNull();

    // Verify overwritten
    const readFrame = createFrame({
      stack: [0x42n],
      gasRemaining: 1000n,
      address: addr,
    });
    expect(tload(readFrame, host)).toBeNull();
    expect(readFrame.stack).toEqual([0x2222n]);
  });

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

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

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

  it('rejects write in static call', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [0x42n, 0x1337n],
      gasRemaining: 1000n,
      address: addressFrom("0x1234567890123456789012345678901234567890"),
      isStatic: true,
    });

    expect(tstore(frame, host)).toEqual({ type: "WriteProtection" });
    expect(frame.pc).toBe(0);  // Not executed
  });

  it('returns StackUnderflow on insufficient stack', () => {
    const host = createMemoryHost();
    const frame = createFrame({
      stack: [0x42n],  // Missing value
      gasRemaining: 1000n,
      address: addressFrom("0x1234567890123456789012345678901234567890"),
      isStatic: false,
    });

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

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

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

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

    // Write to addr1
    let frame = createFrame({
      stack: [0x42n, 0xAAAAn],
      gasRemaining: 1000n,
      address: addr1,
      isStatic: false,
    });
    expect(tstore(frame, host)).toBeNull();

    // Write to addr2 (same key)
    frame = createFrame({
      stack: [0x42n, 0xBBBBn],
      gasRemaining: 1000n,
      address: addr2,
      isStatic: false,
    });
    expect(tstore(frame, host)).toBeNull();

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

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

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

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

    expect(tstore(frame, host)).toBeNull();

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

  it('stores zero value', () => {
    const host = createMemoryHost();
    const addr = addressFrom("0x1234567890123456789012345678901234567890");

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

    expect(tstore(frame, host)).toBeNull();
    expect(frame.gasRemaining).toBe(900n);  // Still costs 100
  });

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

    // Write value
    let frame = createFrame({
      stack: [0x42n, 0x1337n],
      gasRemaining: 1000n,
      address: addr,
      isStatic: false,
    });
    expect(tstore(frame, host)).toBeNull();

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

    // After transaction boundary (auto-clear)
    // host.endTransaction();
    // readFrame = createFrame({
    //   stack: [0x42n],
    //   gasRemaining: 1000n,
    //   address: addr,
    // });
    // expect(tload(readFrame, host)).toBeNull();
    // expect(readFrame.stack).toEqual([0n]);
  });
});

// SAFE: Read-only function
function getData() public view returns (uint256) {
  uint256 value;
  assembly {
    value := tload(0x01)  // Read-only, safe
  }
  return value;
}

// UNSAFE: Attempting write in view function
function badFunction() public view returns (uint256) {
  assembly {
    tstore(0x01, 42)  // WriteProtection error
  }
  return 42;
}

contract Guard {
  function protected() public {
    assembly {
      // Guard must be clear
      if tload(0) {
        revert(0, 0)
      }
      // Lock guard
      tstore(0, 1)
    }

    // Call external function
    (bool ok, ) = msg.sender.call("");
    // Even if call reverts, guard is locked

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

// Attacker cannot bypass:
// - Cannot call protected() again (guard locked)
// - Cannot access transient storage from another contract
// - Guard auto-clears at transaction end (no lingering state)

contract NoLeakage {
  function operation() public {
    assembly {
      tstore(0x01, 42)  // Temporary value
    }

    // Even if transaction reverts here:
    revert("something");

    // In next transaction: TLOAD(0x01) = 0
    // No dangling state to clean up or cause issues
  }
}

// Contract A cannot read Contract B's transient storage
contract A {
  function tryRead() public {
    uint256 value;
    assembly {
      value := tload(0x01)  // Reads A's transient storage only
    }
    // Cannot access B's TSTORE values via staticcall or delegatecall
  }
}