How Cairn works

// SPDX-License-Identifier: MIT
pragma solidity 0.8.26;

/// @title Cairn — recurring buys of Robinhood stock tokens.
/// @notice A plan says: every `every` seconds, spend `amount` USDG on `stock` through one Uniswap v3 pool, `count`
/// times. The contract holds nothing between buys. It pulls each buy's dollars from the owner by ALLOWANCE at the
/// moment of the buy, sends the shares straight to the owner, and pays whoever pressed the button a tip the owner set.
/// Anyone may run a due buy. What stops a stranger running it at a bad price is a floor taken from the price feed the
/// owner chose: the swap must return at least (1 - slip) of the shares that feed says the dollars are worth.
/// No owner, no fee, no upgrade, no storage of anyone's tokens. Revoke the allowance and every plan stops.
interface IERC20 {
    function transferFrom(address, address, uint256) external returns (bool);
    function transfer(address, uint256) external returns (bool);
    function approve(address, uint256) external returns (bool);
}
interface IScaled { function uiMultiplier() external view returns (uint256); }
interface IFeed {
    function decimals() external view returns (uint8);
    function latestRoundData() external view returns (uint80, int256, uint256, uint256, uint80);
}
interface IRouter {
    struct ExactInputSingleParams {
        address tokenIn; address tokenOut; uint24 fee; address recipient;
        uint256 amountIn; uint256 amountOutMinimum; uint160 sqrtPriceLimitX96;
    }
    function exactInputSingle(ExactInputSingleParams calldata) external payable returns (uint256);
}

contract Cairn {
    address public constant USDG = 0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168;
    address public constant ROUTER = 0xCaf681a66D020601342297493863E78C959E5cb2; // Uniswap SwapRouter02
    uint256 public constant MAX_AGE = 4 days;     // stock feeds stop printing when the market shuts; a long weekend is ~88 h
    uint256 public constant MAX_SLIP_BPS = 1000;  // 10%
    uint256 public constant MIN_EVERY = 1 hours;

    struct Plan {
        address owner;   uint64 next;   uint32 every;              // slot 0
        address stock;   uint24 fee;    uint16 slipBps; uint32 left; // slot 1
        address feed;                                              // slot 2
        uint128 amount;  uint128 tip;                              // slot 3 (USDG, 6 decimals)
    }

    Plan[] internal _plans;
    uint256 private _entered; // 0 = free, 1 = inside a buy. Zero is the resting state, so no initialiser is needed.

    event Created(uint256 indexed id, address indexed owner, address indexed stock, uint24 fee, address feed,
                  uint128 amount, uint128 tip, uint32 every, uint32 count, uint16 slipBps, uint64 first);
    event Bought(uint256 indexed id, address indexed runner, uint256 spent, uint256 shares, uint256 floor, uint128 tip, uint32 left, uint64 next);
    event Cancelled(uint256 indexed id);

    error BadPlan();
    error NotOwner();
    error NotDue();
    error Finished();
    error BadPrice();
    error StalePrice();
    error Reentrant();
    error TransferFailed();

    function create(address stock, uint24 fee, address feed, uint128 amount, uint128 tip, uint32 every,
                    uint32 count, uint16 slipBps, uint64 first) external returns (uint256 id) {
        if (stock == address(0) || stock == USDG || feed == address(0) || amount == 0 || count == 0
            || every < MIN_EVERY || slipBps > MAX_SLIP_BPS || tip > amount / 100) revert BadPlan();
        if (first < block.timestamp) first = uint64(block.timestamp);
        id = _plans.length;
        _plans.push(Plan(msg.sender, first, every, stock, fee, slipBps, count, feed, amount, tip));
        emit Created(id, msg.sender, stock, fee, feed, amount, tip, every, count, slipBps, first);
    }

    function cancel(uint256 id) external {
        Plan storage p = _plans[id];
        if (p.owner != msg.sender) revert NotOwner();
        p.left = 0;
        emit Cancelled(id);
    }

    /// @notice The fewest raw token units this plan's next buy may return, from the owner's feed, now.
    function floorOf(uint256 id) public view returns (uint256) {
        Plan storage p = _plans[id];
        (, int256 answer,, uint256 updatedAt,) = IFeed(p.feed).latestRoundData();
        if (answer <= 0) revert BadPrice();
        if (updatedAt + MAX_AGE < block.timestamp) revert StalePrice();
        // shares (18 decimals) the dollars are worth at the feed: amount·1e12 · 10^fd / answer
        uint256 shares = uint256(p.amount) * 1e12 * (10 ** IFeed(p.feed).decimals()) / uint256(answer);
        shares = shares * (10_000 - p.slipBps) / 10_000;
        // Robinhood stock tokens are ERC20ScaledUI: shares = raw · uiMultiplier / 1e18, so raw = shares · 1e18 / m.
        return shares * 1e18 / IScaled(p.stock).uiMultiplier();
    }

    function run(uint256 id) external returns (uint256 got) {
        if (_entered != 0) revert Reentrant();
        _entered = 1;
        Plan storage p = _plans[id];
        if (p.left == 0) revert Finished();
        if (block.timestamp < p.next) revert NotDue();
        uint256 floor = floorOf(id);
        uint64 next = p.next + p.every;
        if (next <= block.timestamp) next = uint64(block.timestamp) + p.every; // missed buys are not caught up in a burst
        p.next = next;
        uint32 left = --p.left;
        address owner = p.owner;
        uint128 amount = p.amount; uint128 tip = p.tip;

        _pull(owner, uint256(amount) + tip);
        _call(USDG, abi.encodeCall(IERC20.approve, (ROUTER, amount)));
        got = IRouter(ROUTER).exactInputSingle(IRouter.ExactInputSingleParams(
            USDG, p.stock, p.fee, owner, amount, floor, 0));
        if (tip != 0) _call(USDG, abi.encodeCall(IERC20.transfer, (msg.sender, tip)));
        emit Bought(id, msg.sender, amount, got, floor, tip, left, next);
        _entered = 0;
    }

    function plan(uint256 id) external view returns (Plan memory) { return _plans[id]; }
    function count() external view returns (uint256) { return _plans.length; }

    function _pull(address from, uint256 amt) private {
        _call(USDG, abi.encodeCall(IERC20.transferFrom, (from, address(this), amt)));
    }
    function _call(address token, bytes memory data) private {
        (bool ok, bytes memory ret) = token.call(data);
        if (!ok || (ret.length != 0 && !abi.decode(ret, (bool)))) revert TransferFailed();
    }
}