@forgezero/runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeZero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# @forgezero/runtime
+
+**The machinery behind a request handler.** Background jobs that never overlap
+themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
+templated mail, encrypted backups, schema validation, and money that is never a
+floating-point number.
+
+Twenty-six modules. Each is its own entry point, so you install one package and
+your bundler includes only what you imported.
+
+```bash
+bun add @forgezero/runtime
+```
+
+```ts
+import { parseAmount } from '@forgezero/runtime/finance/money';
+import { createScheduler } from '@forgezero/runtime/jobs';
+
+// There is no root export. `import from '@forgezero/runtime'` is meant to fail
+// rather than resolve to whichever module happened to be listed first.
+```
+
+## What is in it
+
+| | |
+|---|---|
+| **Spine** | `jobs` `queue` `serial` `outbox` |
+| **Record** | `audit` `backup` `compliance` `calendar` |
+| **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
+| **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
+
+None of it knows what your product does. You bind your own rules to these; you
+do not fork them.
+
+## Three things worth knowing before you use it
+
+**Money is never a number.** An amount is minor units as a `bigint` with its
+asset attached, so two currencies cannot be added by accident and a rounding
+mode is always stated. `finance/storage` writes the same amount twice — the
+authoritative string, and a lossy double used for `ORDER BY` only. One ETH is
+10^18 minor units and a signed 64-bit column overflows around nine ETH, which is
+why the exact value is never the sortable one.
+
+```ts
+const fee = mulRate(parseAmount('1250.00', 'USD'), '0.015', 'down');
+formatAmount(fee);   // '18.75' — never 18.749999999
+toStored(fee);       // { units: '1875', value: '18.75', asset: 'USD', sort: 18.75 }
+```
+
+**A scheduler, never `setInterval`.** An interval fires whether or not the last
+run finished, so work slower than its period runs twice over the same data. The
+next run is scheduled after the current one completes. The lock is a lease with
+a fence, not a mutex — a process that dies does not block its job for ever.
+
+**The cursor advances only on a complete batch.** Fetch, process every item,
+then write the cursor — never per item, never before. Item three of ten throwing
+retries the whole batch from the same position, which means `process` must be
+idempotent, and idempotent retries beat records nobody ever looks at again.
+
+## Optional peers
+
+Nothing third-party is bundled — vendoring a crypto library means a fix for it
+never reaches you until this package republishes. Most subpaths need nothing:
+
+```bash
+bun add @noble/hashes                      # finance/custody
+bun add @noble/curves @noble/post-quantum  # identity
+bun add @sinclair/typebox                  # schema/typebox
+```
+
+## The Solidity ships with it
+
+`finance/custody` computes counterfactual CREATE2 deposit addresses; the
+contracts that make those addresses real are in the tarball, not in a repository
+you have to go find.
+
+```
+node_modules/@forgezero/runtime/contracts/src/
+  DepositProxy.sol     deployed lazily at first sweep — no key, no gas per address
+  DepositFactory.sol   CREATE2, salt opaque to the contract
+  ColdVault.sol        M-of-N EIP-712, signatures ordered by ascending signer
+```
+
+Full documentation: **https://forgezero.net/docs/runtime**
+
+## Licence
+
+MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+deploys — and usable entirely on its own, with no ForgeZero account.

package/contracts/foundry.toml

@@ -0,0 +1,9 @@
+[profile.default]
+src = "src"
+test = "test"
+out = "out"
+libs = []
+solc_version = "0.8.24"
+optimizer = true
+optimizer_runs = 200
+evm_version = "shanghai"

package/contracts/src/ColdVault.sol

@@ -0,0 +1,206 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import { IERC20 } from './IERC20.sol';
+import { SafeTransferLib } from './SafeTransferLib.sol';
+
+/**
+ * Cold storage: M-of-N custodians, and nothing else can move anything.
+ *
+ * There is no operator role here, no owner who can withdraw, and no key held by
+ * any running process. Funds move only when M distinct custodians have each
+ * signed the same withdrawal off-chain — on a Ledger, on an air-gapped machine,
+ * on whatever they keep their key in. The signatures are collected however the
+ * platform likes and submitted by anyone; the submitter has no power beyond
+ * paying for gas.
+ *
+ * That is what makes it cold. Compromising every server the platform runs does
+ * not move a single token, because no server holds a key that can.
+ *
+ * ## EIP-712, so a custodian can read what they are signing
+ *
+ * A raw hash tells a hardware wallet nothing, and a custodian approving an
+ * opaque blob is a custodian who will eventually approve the wrong one. The
+ * typed structure shows the token, the destination and the amount on the
+ * device's own screen.
+ *
+ * ## What binds a signature to exactly one withdrawal
+ *
+ *   chainId              a testnet rehearsal cannot be replayed on mainnet
+ *   verifyingContract    a signature for one vault is void at another
+ *   nonce                each approval is spendable once, in order
+ *   token/to/amount      changing any of them invalidates every signature
+ *
+ * Without all four, a signature gathered once is a signature reusable forever.
+ */
+contract ColdVault {
+	using SafeTransferLib for address;
+
+	/* --------------------------------------------------------------- state --- */
+
+	mapping(address => bool) public isCustodian;
+	address[] private custodianList;
+	uint256 public threshold;
+	uint256 public nonce;
+
+	bytes32 private immutable DOMAIN_SEPARATOR;
+
+	bytes32 private constant WITHDRAW_TYPEHASH =
+		keccak256('Withdraw(address token,address to,uint256 amount,uint256 nonce)');
+
+	/* -------------------------------------------------------------- events --- */
+
+	event Withdrawn(address indexed token, address indexed to, uint256 amount, uint256 nonce);
+	event CustodiansChanged(address[] custodians, uint256 threshold);
+
+	/* -------------------------------------------------------------- errors --- */
+
+	error BadThreshold();
+	error DuplicateCustodian();
+	error ZeroAddress();
+	error NotEnoughSignatures(uint256 got, uint256 need);
+	error SignaturesOutOfOrder();
+	error NotACustodian(address signer);
+	error NativeSendFailed();
+	error OnlySelf();
+
+	constructor(address[] memory initialCustodians, uint256 requiredSignatures) {
+		_setCustodians(initialCustodians, requiredSignatures);
+		DOMAIN_SEPARATOR = keccak256(
+			abi.encode(
+				keccak256('EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)'),
+				keccak256('ForgeZeroColdVault'),
+				keccak256('1'),
+				block.chainid,
+				address(this)
+			)
+		);
+	}
+
+	/* ------------------------------------------------------------ withdraw --- */
+
+	/**
+	 * Move funds, given M valid custodian signatures over exactly this request.
+	 *
+	 * Signatures must be ordered by ascending signer address. That is not a style
+	 * choice: it is how the same custodian signing twice is rejected in one pass
+	 * without allocating a set, and without it an M-of-N vault is satisfied by
+	 * one custodian submitting M copies of their own approval.
+	 */
+	function withdraw(
+		address token,
+		address to,
+		uint256 amount,
+		bytes[] calldata signatures
+	) external {
+		if (to == address(0)) revert ZeroAddress();
+		if (signatures.length < threshold) revert NotEnoughSignatures(signatures.length, threshold);
+
+		bytes32 digest = keccak256(
+			abi.encodePacked(
+				'\x19\x01',
+				DOMAIN_SEPARATOR,
+				keccak256(abi.encode(WITHDRAW_TYPEHASH, token, to, amount, nonce))
+			)
+		);
+
+		address previous = address(0);
+		for (uint256 i = 0; i < signatures.length; ) {
+			address signer = _recover(digest, signatures[i]);
+			if (!isCustodian[signer]) revert NotACustodian(signer);
+			// Strictly increasing. Equal means the same custodian counted twice.
+			if (signer <= previous) revert SignaturesOutOfOrder();
+			previous = signer;
+			unchecked { ++i; }
+		}
+
+		// Bumped BEFORE the transfer, so every gathered signature is spent whether
+		// or not the token behaves, and a reverting token cannot be used to replay.
+		unchecked { ++nonce; }
+
+		if (token == address(0)) {
+			(bool ok, ) = to.call{ value: amount }('');
+			if (!ok) revert NativeSendFailed();
+		} else {
+			token.safeTransfer(to, amount);
+		}
+		emit Withdrawn(token, to, amount, nonce - 1);
+	}
+
+	/**
+	 * Rotate the custodian set — itself requiring the current quorum.
+	 *
+	 * Callable only by this contract, through `withdraw`-style quorum: the
+	 * platform submits a call to `address(this)` and the existing M must approve
+	 * it. A custodian set changeable by anything less than the set itself is not
+	 * a quorum.
+	 */
+	function setCustodians(address[] calldata nextCustodians, uint256 requiredSignatures) external {
+		if (msg.sender != address(this)) revert OnlySelf();
+		_setCustodians(nextCustodians, requiredSignatures);
+	}
+
+	function custodians() external view returns (address[] memory) {
+		return custodianList;
+	}
+
+	/** What a custodian's device should be asked to sign, for the next withdrawal. */
+	function digestFor(address token, address to, uint256 amount) external view returns (bytes32) {
+		return
+			keccak256(
+				abi.encodePacked(
+					'\x19\x01',
+					DOMAIN_SEPARATOR,
+					keccak256(abi.encode(WITHDRAW_TYPEHASH, token, to, amount, nonce))
+				)
+			);
+	}
+
+	/* ----------------------------------------------------------- internals --- */
+
+	function _setCustodians(address[] memory custodians_, uint256 requiredSignatures) private {
+		// A threshold of one is not a quorum, and a threshold above the set size
+		// is a vault nobody can ever open.
+		if (requiredSignatures < 2 || requiredSignatures > custodians_.length) revert BadThreshold();
+
+		for (uint256 i = 0; i < custodianList.length; ) {
+			isCustodian[custodianList[i]] = false;
+			unchecked { ++i; }
+		}
+		delete custodianList;
+
+		for (uint256 i = 0; i < custodians_.length; ) {
+			address who = custodians_[i];
+			if (who == address(0)) revert ZeroAddress();
+			if (isCustodian[who]) revert DuplicateCustodian();
+			isCustodian[who] = true;
+			custodianList.push(who);
+			unchecked { ++i; }
+		}
+
+		threshold = requiredSignatures;
+		emit CustodiansChanged(custodians_, requiredSignatures);
+	}
+
+	function _recover(bytes32 digest, bytes calldata signature) private pure returns (address) {
+		if (signature.length != 65) return address(0);
+		bytes32 r;
+		bytes32 s;
+		uint8 v;
+		assembly {
+			r := calldataload(signature.offset)
+			s := calldataload(add(signature.offset, 32))
+			v := byte(0, calldataload(add(signature.offset, 64)))
+		}
+		if (v < 27) v += 27;
+		// secp256k1 signatures are malleable: (r, s) and (r, n-s) both verify. A
+		// vault that accepted both would let a submitted approval be mutated into a
+		// second distinct signature by the same custodian.
+		if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) {
+			return address(0);
+		}
+		return ecrecover(digest, v, r, s);
+	}
+
+	receive() external payable {}
+}

package/contracts/src/DepositFactory.sol

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import { IERC20 } from './IERC20.sol';
+import { DepositProxy } from './DepositProxy.sol';
+import { SafeTransferLib } from './SafeTransferLib.sol';
+
+/**
+ * Deterministic deposit addresses, and the sweep that collects them.
+ *
+ * ## The salt is opaque, deliberately
+ *
+ * This contract never learns what a salt MEANS. A platform that gives each user
+ * one lasting deposit address and a platform that mints a fresh address per
+ * invoice both work here unchanged, because the only thing this needs is a
+ * distinct 32-byte value. That is the difference between a runtime and one
+ * business's contract: encoding "user" or "invoice" here would force the choice
+ * on everybody who ever deployed it.
+ *
+ * The convention belongs to the caller — `keccak256("<app>:user:" || key)` or
+ * `keccak256("<app>:invoice:" || key)` — and both are just bytes32 to this
+ * contract.
+ *
+ * ## No chain write to create an address
+ *
+ * `computeAddress` is pure arithmetic over the deployer, the salt and the proxy
+ * init-code hash, so a platform derives a million deposit addresses with zero
+ * transactions and zero gas. The proxy is deployed lazily, at the first sweep,
+ * and only for addresses that actually received something.
+ *
+ * ## What this contract does NOT do
+ *
+ * It holds no policy. There is no per-user balance, no reserve, no fee, no
+ * notion of what is owed to whom — those are the platform's, and they belong in
+ * the platform's ledger where they can be changed without a redeploy. This moves
+ * tokens and nothing else.
+ */
+contract DepositFactory {
+	using SafeTransferLib for address;
+
+	address public owner;
+	address public pendingOwner;
+
+	/**
+	 * `keccak256(type(DepositProxy).creationCode)`, fixed at deploy.
+	 *
+	 * Exposed so an off-chain caller can mirror `computeAddress` byte for byte
+	 * instead of hardcoding a hash that silently stops matching after a compiler
+	 * upgrade.
+	 */
+	bytes32 public immutable PROXY_INIT_CODE_HASH;
+
+	event ProxyDeployed(bytes32 indexed salt, address indexed proxy);
+	event Swept(bytes32 indexed salt, address indexed token, uint256 amount);
+	event PaidOut(address indexed token, address indexed to, uint256 amount);
+	event OwnerProposed(address indexed newOwner);
+	event OwnerAccepted(address indexed previous, address indexed next);
+
+	error NotOwner();
+	error NotPendingOwner();
+	error ZeroAddress();
+	error Create2Failed();
+	error LengthMismatch();
+	error NativeSendFailed();
+
+	modifier onlyOwner() {
+		if (msg.sender != owner) revert NotOwner();
+		_;
+	}
+
+	constructor(address initialOwner) {
+		if (initialOwner == address(0)) revert ZeroAddress();
+		owner = initialOwner;
+		PROXY_INIT_CODE_HASH = keccak256(type(DepositProxy).creationCode);
+		emit OwnerAccepted(address(0), initialOwner);
+	}
+
+	/** The deposit address for a salt. Pure, so deriving costs nothing. */
+	function computeAddress(bytes32 salt) public view returns (address) {
+		return
+			address(
+				uint160(
+					uint256(
+						keccak256(
+							abi.encodePacked(bytes1(0xff), address(this), salt, PROXY_INIT_CODE_HASH)
+						)
+					)
+				)
+			);
+	}
+
+	/** Many at once, so a platform can reconcile a page of addresses in one call. */
+	function computeAddresses(bytes32[] calldata salts) external view returns (address[] memory out) {
+		out = new address[](salts.length);
+		for (uint256 i = 0; i < salts.length; ) {
+			out[i] = computeAddress(salts[i]);
+			unchecked { ++i; }
+		}
+	}
+
+	/**
+	 * Collect deposits into this contract, then pay out to the given destinations.
+	 *
+	 * One primitive rather than several, because every real operation is some
+	 * combination of the two halves:
+	 *
+	 *   withdraw for one user     salts=[one]   destinations=[external]
+	 *   consolidate to the float  salts=[many]  destinations=[hotAddress]
+	 *   move float to cold        salts=[]      destinations=[coldVault]
+	 *
+	 * Anything swept beyond what is paid out stays here as float, which is what
+	 * makes the middle case a single transaction instead of one per address.
+	 */
+	function sweepAndPay(
+		bytes32[] calldata salts,
+		address token,
+		address[] calldata destinations,
+		uint256[] calldata amounts
+	) external onlyOwner {
+		if (destinations.length != amounts.length) revert LengthMismatch();
+
+		for (uint256 i = 0; i < salts.length; ) {
+			address proxy = _ensureProxy(salts[i]);
+			uint256 before = _balanceOf(token);
+			DepositProxy(payable(proxy)).sweep(token, address(this));
+			// The DIFFERENCE, not a number passed in. A fee-on-transfer token
+			// delivers less than it was asked to send, and an event reporting the
+			// requested figure is a ledger entry for money that never arrived.
+			emit Swept(salts[i], token, _balanceOf(token) - before);
+			unchecked { ++i; }
+		}
+
+		for (uint256 j = 0; j < destinations.length; ) {
+			if (destinations[j] == address(0)) revert ZeroAddress();
+			_payOut(token, destinations[j], amounts[j]);
+			unchecked { ++j; }
+		}
+	}
+
+	/** Sweep only. The common case: consolidate into a vault held elsewhere. */
+	function sweepTo(bytes32[] calldata salts, address token, address destination)
+		external
+		onlyOwner
+	{
+		if (destination == address(0)) revert ZeroAddress();
+		for (uint256 i = 0; i < salts.length; ) {
+			DepositProxy(payable(_ensureProxy(salts[i]))).sweep(token, address(this));
+			unchecked { ++i; }
+		}
+		uint256 balance = _balanceOf(token);
+		if (balance > 0) _payOut(token, destination, balance);
+	}
+
+	function proposeOwner(address next) external onlyOwner {
+		if (next == address(0)) revert ZeroAddress();
+		pendingOwner = next;
+		emit OwnerProposed(next);
+	}
+
+	/**
+	 * Accepted by the new owner's own key.
+	 *
+	 * A one-step transfer to a mistyped address bricks every deposit address this
+	 * factory derives — the funds stay reachable only by a key nobody holds.
+	 */
+	function acceptOwnership() external {
+		if (msg.sender != pendingOwner) revert NotPendingOwner();
+		address previous = owner;
+		owner = msg.sender;
+		pendingOwner = address(0);
+		emit OwnerAccepted(previous, msg.sender);
+	}
+
+	function _ensureProxy(bytes32 salt) internal returns (address proxy) {
+		proxy = computeAddress(salt);
+		if (proxy.code.length == 0) {
+			bytes memory bytecode = type(DepositProxy).creationCode;
+			assembly {
+				proxy := create2(0, add(bytecode, 0x20), mload(bytecode), salt)
+			}
+			if (proxy == address(0)) revert Create2Failed();
+			emit ProxyDeployed(salt, proxy);
+		}
+	}
+
+	function _balanceOf(address token) internal view returns (uint256) {
+		return token == address(0) ? address(this).balance : IERC20(token).balanceOf(address(this));
+	}
+
+	function _payOut(address token, address to, uint256 amount) internal {
+		if (amount == 0) return;
+		if (token == address(0)) {
+			(bool ok, ) = to.call{ value: amount }('');
+			if (!ok) revert NativeSendFailed();
+		} else {
+			token.safeTransfer(to, amount);
+		}
+		emit PaidOut(token, to, amount);
+	}
+
+	receive() external payable {}
+}

package/contracts/src/DepositProxy.sol

@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+import { IERC20 } from './IERC20.sol';
+import { SafeTransferLib } from './SafeTransferLib.sol';
+
+/**
+ * A deposit address that needs no key, no gas and no approval.
+ *
+ * This is the whole reason the CREATE2 pattern beats the obvious alternative.
+ * Sweeping from an ordinary account requires that account to sign an approval,
+ * which means every deposit address must first be funded with native coin and
+ * must have a private key derived, held and used. With a thousand deposit
+ * addresses that is a thousand gas top-ups and a thousand keys.
+ *
+ * A CREATE2 address holds balances before any code exists at it. The factory
+ * deploys this contract there only at the moment of the first sweep, and the
+ * constructor records the deployer, so nothing but that factory can ever move
+ * the funds.
+ *
+ * ## Never change this file
+ *
+ * The address depends on `keccak256(type(DepositProxy).creationCode)`. Adding a
+ * field, a function, or even changing the compiler settings changes the init
+ * code hash, which changes EVERY derived deposit address. Funds already sent to
+ * the old addresses stay recoverable only by the old factory. A change here is
+ * a new contract, deployed by a new factory, with addresses re-derived.
+ */
+contract DepositProxy {
+	using SafeTransferLib for address;
+
+	/** The factory that deployed this. Immutable, and the only caller allowed. */
+	address public immutable factory;
+
+	event Swept(address indexed token, address indexed to, uint256 amount);
+
+	error OnlyFactory();
+	error NativeSendFailed();
+
+	constructor() {
+		factory = msg.sender;
+	}
+
+	/**
+	 * Move the whole balance of `token` to `to`. `address(0)` means native coin.
+	 *
+	 * Returns silently on a zero balance rather than reverting, so a batch across
+	 * many addresses is not undone by the ones that were already swept.
+	 *
+	 * The amount is read from the chain rather than passed in: a figure computed
+	 * off-chain is stale by the time it mines, and a fee-on-transfer token would
+	 * make it wrong even if it were not.
+	 */
+	function sweep(address token, address to) external {
+		if (msg.sender != factory) revert OnlyFactory();
+		uint256 amount;
+		if (token == address(0)) {
+			amount = address(this).balance;
+			if (amount == 0) return;
+			(bool ok, ) = to.call{ value: amount }('');
+			if (!ok) revert NativeSendFailed();
+		} else {
+			amount = IERC20(token).balanceOf(address(this));
+			if (amount == 0) return;
+			token.safeTransfer(to, amount);
+		}
+		emit Swept(token, to, amount);
+	}
+
+	/** Native coin sent to a deposit address lands here without hitting a fallback. */
+	receive() external payable {}
+}

package/contracts/src/IERC20.sol

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+interface IERC20 {
+	function balanceOf(address account) external view returns (uint256);
+	function transfer(address to, uint256 amount) external returns (bool);
+}

package/contracts/src/MockTokens.sol

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+contract MockToken {
+	event Transfer(address indexed from, address indexed to, uint256 value);
+	mapping(address => uint256) public balanceOf;
+	function mint(address to, uint256 a) external { balanceOf[to] += a; emit Transfer(address(0), to, a); }
+	function transfer(address to, uint256 a) external returns (bool) {
+		balanceOf[msg.sender] -= a; balanceOf[to] += a; emit Transfer(msg.sender, to, a); return true;
+	}
+}
+
+/** USDT: `transfer` returns NOTHING. */
+contract MockNoReturnToken {
+	event Transfer(address indexed from, address indexed to, uint256 value);
+	mapping(address => uint256) public balanceOf;
+	function mint(address to, uint256 a) external { balanceOf[to] += a; emit Transfer(address(0), to, a); }
+	function transfer(address to, uint256 a) external {
+		balanceOf[msg.sender] -= a; balanceOf[to] += a; emit Transfer(msg.sender, to, a);
+	}
+}
+
+/** Takes a 1% cut on the way through. Delivers less than it was asked to send. */
+contract MockFeeToken {
+	event Transfer(address indexed from, address indexed to, uint256 value);
+	mapping(address => uint256) public balanceOf;
+	function mint(address to, uint256 a) external { balanceOf[to] += a; emit Transfer(address(0), to, a); }
+	function transfer(address to, uint256 a) external returns (bool) {
+		uint256 fee = a / 100;
+		balanceOf[msg.sender] -= a; balanceOf[to] += a - fee; emit Transfer(msg.sender, to, a - fee); return true;
+	}
+}

package/contracts/src/SafeTransferLib.sol

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.24;
+
+/**
+ * ERC-20 transfer that survives the tokens people actually hold.
+ *
+ *   returns true     -> pass
+ *   returns NOTHING  -> pass   (USDT on Ethereum, and it is not alone)
+ *   returns false    -> revert
+ *   reverts          -> revert
+ *
+ * The empty-returndata case is the one that matters. A call typed to return
+ * `bool` reverts on decode against USDT, and that failure appears only on a
+ * chain where real money is moving.
+ *
+ * Pair this with balanceOf-based sweeping — as the proxy and factory do — so a
+ * fee-on-transfer token moves what is ACTUALLY held rather than an overstated
+ * figure. Otherwise the platform pays out coins it does not have.
+ */
+library SafeTransferLib {
+	bytes4 private constant TRANSFER_SELECTOR = 0xa9059cbb;
+
+	error TransferFailed();
+
+	function safeTransfer(address token, address to, uint256 amount) internal {
+		(bool ok, bytes memory data) = token.call(
+			abi.encodeWithSelector(TRANSFER_SELECTOR, to, amount)
+		);
+		if (!ok || (data.length != 0 && !abi.decode(data, (bool)))) revert TransferFailed();
+	}
+}