crane-utilities

name	crane-utilities
description	This skill should be used when the user asks about "set collections", "AddressSet", "Bytes32Set", "math utilities", "ConstProdUtils", "AMM math", "hash functions", "BetterMath", "pagination", "EIP-712", "cryptography", or needs utility libraries for Crane Diamond development.

Crane Utility Libraries

Crane provides utility libraries for collections, math, cryptography, and common operations.

Collections (Sets)

Diamond storage-compatible set implementations for unique value collections.

Available Set Types

Type	File	Use Case
AddressSet	AddressSetRepo.sol	Unique addresses (operators, whitelist)
Bytes32Set	Bytes32SetRepo.sol	Unique hashes, identifiers
Bytes4Set	Bytes4SetRepo.sol	Function selectors, interface IDs
StringSet	StringSetRepo.sol	Unique strings
UInt256Set	UInt256SetRepo.sol	Unique numeric IDs

Set Operations

import {AddressSet, AddressSetRepo} from "@crane/contracts/utils/collections/sets/AddressSetRepo.sol";

// In your Repo
struct Storage {
    AddressSet operators;
}

// Operations
AddressSetRepo._add(set, value);        // Add value, idempotent
AddressSetRepo._remove(set, value);     // Remove value, idempotent
AddressSetRepo._contains(set, value);   // Check presence
AddressSetRepo._length(set);            // Get count
AddressSetRepo._index(set, idx);        // Get value at index
AddressSetRepo._indexOf(set, value);    // Get index of value
AddressSetRepo._asArray(set);           // Get all values as array

Pagination

For large sets, use pagination:

// Get page of results
(address[] memory page, bool hasMore) = AddressSetRepo._getPage(
    set,
    pageIndex,   // 0-based page number
    pageSize     // Items per page
);

Math Utilities

ConstProdUtils

Core AMM math for constant product pools (xy=k):

import {ConstProdUtils} from "@crane/contracts/utils/math/ConstProdUtils.sol";

using ConstProdUtils for uint256;

// Calculate output for swap
uint256 amountOut = ConstProdUtils._purchaseQuote(
    amountIn,         // Amount being sold
    reserveIn,        // Reserve of input token
    reserveOut,       // Reserve of output token
    feeNumerator      // Fee (e.g., 9970 for 0.3%)
);

// Calculate input needed for desired output
uint256 amountIn = ConstProdUtils._saleQuote(
    amountOut,
    reserveIn,
    reserveOut,
    feeNumerator
);

// Optimal swap amount for balanced deposit
uint256 saleAmt = ConstProdUtils._quoteSaleAmountIn(
    amountIn,
    reserveIn,
    reserveOut,
    feeNumerator
);

// Sort reserves by token address
(uint256 knownReserve, uint256 unknownReserve) = ConstProdUtils._sortReserves(
    knownToken,
    token0,
    reserve0,
    reserve1
);

BetterMath

Extended math operations including 512-bit arithmetic:

import {Uint512, BetterMath} from "@crane/contracts/utils/math/BetterMath.sol";

using BetterMath for uint256;
using BetterMath for Uint512;

// Safe operations
uint256 sum = a._add(b);              // Checked addition
uint256 diff = a._sub(b);             // Checked subtraction
uint256 prod = a._mul(b);             // Checked multiplication
uint256 quot = a._div(b);             // Checked division

// 512-bit multiplication (for intermediate precision)
Uint512 memory product = a._mul512(b);
uint256 result = product._div(c);

// Min/max
uint256 smaller = a._min(b);
uint256 larger = a._max(b);

// Percentage calculations
uint256 portion = total._mulDivDown(numerator, denominator);
uint256 portionUp = total._mulDivUp(numerator, denominator);

Cryptography

EIP-712 (Typed Data Hashing)

import {EIP712Repo} from "@crane/contracts/utils/cryptography/EIP712/EIP712Repo.sol";

// Initialize in DFPkg
EIP712Repo._initialize("MyContract", "1");

// Build domain separator
bytes32 domainSeparator = EIP712Repo._domainSeparator();

// Hash typed data
bytes32 digest = keccak256(abi.encodePacked(
    "\x19\x01",
    domainSeparator,
    structHash
));

BetterEfficientHashLib

Optimized hashing:

import {BetterEfficientHashLib} from "@crane/contracts/utils/BetterEfficientHashLib.sol";

using BetterEfficientHashLib for bytes;

// Hash bytes efficiently
bytes32 hash = someBytes._hash();

// Hash for CREATE3 salt
bytes32 salt = abi.encode(value)._hash();

String & Bytes Utilities

BetterStrings

import {BetterStrings} from "@crane/contracts/utils/BetterStrings.sol";

using BetterStrings for string;

string memory result = str1._concat(str2);
bool isEmpty = str._isEmpty();
uint256 len = str._length();

BetterBytes

import {BetterBytes} from "@crane/contracts/utils/BetterBytes.sol";

using BetterBytes for bytes;

bytes memory slice = data._slice(start, length);
bytes memory concat = data1._concat(data2);

Bytes32 & Bytes4

import {Bytes32} from "@crane/contracts/utils/Bytes32.sol";
import {Bytes4} from "@crane/contracts/utils/Bytes4.sol";

using Bytes32 for bytes32;
using Bytes4 for bytes4;

// Convert to hex string
string memory hex32 = someHash._toHexString();
string memory hex4 = someSelector._toHexString();

Address Utilities

import {BetterAddress} from "@crane/contracts/utils/BetterAddress.sol";

using BetterAddress for address;

// Check if address is contract
bool isContract = addr._isContract();

// Safe ETH transfer
addr._sendValue(amount);

Constants

Network and protocol constants:

import "@crane/contracts/constants/Constants.sol";

// Global constants
uint256 constant WAD = 1e18;
uint256 constant RAY = 1e27;

// Network-specific
import "@crane/contracts/constants/networks/BASE_MAIN.sol";
// Provides addresses for Base mainnet

// Protocol constants
import "@crane/contracts/constants/protocols/utils/permit2/PERMIT2_CONSTANTS.sol";
// Provides Permit2 addresses

File Organization

contracts/utils/
├── collections/
│   └── sets/
│       ├── AddressSetRepo.sol
│       ├── Bytes32SetRepo.sol
│       ├── Bytes4SetRepo.sol
│       ├── StringSetRepo.sol
│       └── UInt256SetRepo.sol
├── cryptography/
│   ├── EIP712/
│   │   └── EIP712Repo.sol
│   ├── ERC5267/
│   │   └── ERC5267Facet.sol
│   └── hash/
│       └── *.sol
├── math/
│   ├── BetterMath.sol
│   ├── ConstProdUtils.sol
│   └── [Protocol]Utils.sol
├── BetterAddress.sol
├── BetterBytes.sol
├── BetterEfficientHashLib.sol
├── BetterStrings.sol
├── Bytes32.sol
├── Bytes4.sol
└── UInt256.sol

Additional Resources

Reference Files

For detailed utility patterns and examples:

• references/utility-patterns.md - Complete usage patterns and examples