@fastish/contracts 0.1.0

package/README.md

@@ -0,0 +1,134 @@
+# fastish
+
+`fastish` is the Solidity library used to build hosts and commands for the Fastish protocol.
+
+It contains the reusable contracts, utilities, and encoding helpers that Fastish applications compose on top of. If you are building a Fastish host, a command contract, or a small protocol extension that needs to speak Fastish's id, asset, and block formats, this repo is the shared foundation.
+
+## What You Build With It
+
+- `Host` contracts that register with Fastish discovery and expose trusted command endpoints
+- `Command` contracts that execute protocol actions such as transfer, deposit, withdraw, settlement, and admin flows
+- Shared request/response block parsing and writing logic
+- Shared id, asset, account, and event encoding used across the protocol
+
+## Main Entry Points
+
+Most consumers should start from the barrel files in `contracts/`:
+
+- `contracts/Core.sol`: core host and validation building blocks
+- `contracts/Commands.sol`: base command contract plus standard command mixins
+- `contracts/Blocks.sol`: block schema, readers, and writers
+- `contracts/Utils.sol`: ids, assets, accounts, layout, strings, and value helpers
+- `contracts/Events.sol`: reusable event emitters and event contracts
+
+## Start Here
+
+If you are new to Fastish, read [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) first.
+
+It walks through:
+
+- the host and command mental model
+- which built-in commands expect `request` vs `state`
+- a minimal host example
+- a built-in command example
+- a custom command example
+- simple TypeScript request encoding
+
+## Typical Usage
+
+### Build a Host
+
+Extend `Host` when you want a Fastish host contract with admin command support and optional discovery registration.
+
+```solidity
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {Host} from "fastish/contracts/Core.sol";
+
+contract ExampleHost is Host {
+    constructor(address fastish)
+        Host(fastish, 1, "example")
+    {}
+}
+```
+
+`fastish` is the trusted Fastish runtime. If it is a contract, the host also announces itself there during deployment. Use `address(0)` for a self-managed host that does not auto-register.
+
+`Host` already layers in the standard admin command flows used by Fastish hosts:
+
+- `Authorize`
+- `Unauthorize`
+- `Relocate`
+
+### Build a Command
+
+Extend `CommandBase` when you want a Fastish command mixin that runs inside the protocol's trusted call model. Commands are abstract contracts mixed into a host or composed as a standalone module.
+
+```solidity
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandBase, CommandContext} from "fastish/contracts/Commands.sol";
+
+string constant NAME = "myCommand";
+string constant ROUTE = "route(uint foo, uint bar)";
+
+abstract contract ExampleCommand is CommandBase {
+    uint internal immutable myCommandId = commandId(NAME);
+
+    constructor() {
+        emit Command(host, NAME, ROUTE, myCommandId, 0, 0);
+    }
+
+    function myCommand(
+        CommandContext calldata c
+    ) external payable onlyCommand(myCommandId, c.target) returns (bytes memory) {
+        return "";
+    }
+}
+```
+
+`CommandBase` gives you the common Fastish command context:
+
+- trusted caller enforcement
+- admin checks
+- expiry checks
+- command-to-command or command-to-host calls through encoded Fastish node ids
+- shared command events
+
+## Repo Layout
+
+- `contracts/core`: host, access control, balances, and validation primitives
+- `contracts/commands`: standard command building blocks and admin commands
+- `contracts/peer`: peer protocol surfaces for inter-host asset flows
+- `contracts/blocks`: request/response block encoding and decoding
+- `contracts/utils`: shared protocol encoding helpers
+- `contracts/events`: protocol event contracts and emitters
+- `contracts/interfaces`: discovery interfaces and shared external protocol surfaces
+
+## Install And Compile
+
+```bash
+npm install @fastish/contracts
+npm run compile
+```
+
+The stable import surface for consumers is:
+
+- `fastish/contracts/Core.sol`
+- `fastish/contracts/Commands.sol`
+- `fastish/contracts/Blocks.sol`
+- `fastish/contracts/Utils.sol`
+- `fastish/contracts/Events.sol`
+
+## When To Use This Repo
+
+Use `fastish` if you want to:
+
+- create a new Fastish host
+- implement a new Fastish command
+- reuse Fastish's block format and wire encoding
+- share protocol-level Solidity code across multiple Fastish applications
+
+If you are looking for a full end-user app or deployment repo, this library is the lower-level protocol package rather than the full product surface.

package/contracts/Blocks.sol

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {
+    ALLOCATION,
+    ALLOCATION_KEY,
+    AMOUNT,
+    AMOUNT_KEY,
+    ASSET,
+    ASSET_KEY,
+    AUTH,
+    AUTH_KEY,
+    BALANCE,
+    BALANCE_KEY,
+    BOUNTY,
+    BOUNTY_KEY,
+    BlockRef,
+    CUSTODY,
+    CUSTODY_KEY,
+    DataRef,
+    DataPairRef,
+    FUNDING,
+    FUNDING_KEY,
+    HostAmount,
+    LISTING,
+    LISTING_KEY,
+    Listing,
+    MAXIMUM,
+    MAXIMUM_KEY,
+    MINIMUM,
+    MINIMUM_KEY,
+    MemRef,
+    NODE,
+    NODE_KEY,
+    QUANTITY,
+    QUANTITY_KEY,
+    PARTY,
+    PARTY_KEY,
+    RATE,
+    RATE_KEY,
+    RECIPIENT,
+    RECIPIENT_KEY,
+    ROUTE,
+    ROUTE_EMPTY,
+    ROUTE_KEY,
+    STEP,
+    STEP_KEY,
+    TX,
+    TX_KEY,
+    Tx,
+    Writer,
+    AssetAmount
+} from "./blocks/Schema.sol";
+import {Blocks} from "./blocks/Readers.sol";
+import {Data} from "./blocks/Data.sol";
+import {Mem} from "./blocks/Mem.sol";
+import {
+    InvalidBlock,
+    MalformedBlocks,
+    UnexpectedAsset,
+    UnexpectedHost,
+    UnexpectedMeta,
+    ZeroNode,
+    ZeroRecipient
+} from "./blocks/Errors.sol";
+import {
+    BALANCE_BLOCK_LEN,
+    CUSTODY_BLOCK_LEN,
+    IncompleteWriter,
+    TX_BLOCK_LEN,
+    Writers,
+    WriterOverflow
+} from "./blocks/Writers.sol";

package/contracts/Commands.sol

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandBase, CommandContext} from "./commands/Base.sol";
+import {NoOperation} from "./core/Operation.sol";
+import {BALANCES, CLAIMS, CUSTODIES, PIPE, SETUP, TRANSACTIONS} from "./utils/Channels.sol";
+import {BorrowAgainstBalanceToBalance, BorrowAgainstCustodyToBalance} from "./commands/Borrow.sol";
+import {Burn} from "./commands/Burn.sol";
+import {Create} from "./commands/Create.sol";
+import {CreditBalanceToAccount} from "./commands/CreditTo.sol";
+import {DebitAccountToBalance} from "./commands/DebitFrom.sol";
+import {Deposit} from "./commands/Deposit.sol";
+import {Remove} from "./commands/Remove.sol";
+import {Fund} from "./commands/Fund.sol";
+import {
+    AddLiquidityFromBalancesToBalances,
+    AddLiquidityFromCustodiesToBalances,
+    RemoveLiquidityFromBalanceToBalances,
+    RemoveLiquidityFromCustodyToBalances
+} from "./commands/Liquidity.sol";
+import {LiquidateFromBalanceToBalances, LiquidateFromCustodyToBalances} from "./commands/Liquidate.sol";
+import {MintToBalances} from "./commands/Mint.sol";
+import {Pipe} from "./commands/Pipe.sol";
+import {Provision} from "./commands/Provision.sol";
+import {ReclaimToBalances} from "./commands/Reclaim.sol";
+import {RedeemFromBalanceToBalances, RedeemFromCustodyToBalances} from "./commands/Redeem.sol";
+import {RepayFromBalanceToBalances, RepayFromCustodyToBalances} from "./commands/Repay.sol";
+import {Settle} from "./commands/Settle.sol";
+import {StakeBalanceToBalances, StakeCustodyToBalances, StakeCustodyToPosition} from "./commands/Stake.sol";
+import {Supply} from "./commands/Supply.sol";
+import {SwapExactBalanceToBalance, SwapExactCustodyToBalance} from "./commands/Swap.sol";
+import {Transfer} from "./commands/Transfer.sol";
+import {UnstakeBalanceToBalances} from "./commands/Unstake.sol";
+import {Withdraw} from "./commands/Withdraw.sol";
+import {AllowAssets} from "./commands/admin/AllowAssets.sol";
+import {Destroy} from "./commands/admin/Destroy.sol";
+import {Authorize} from "./commands/admin/Authorize.sol";
+import {DenyAssets} from "./commands/admin/DenyAssets.sol";
+import {Init} from "./commands/admin/Init.sol";
+import {Relocate} from "./commands/admin/Relocate.sol";
+import {Allocate} from "./commands/admin/Allocate.sol";
+import {Unauthorize} from "./commands/admin/Unauthorize.sol";
+import {PeerBase} from "./peer/Base.sol";
+import {PeerAllowAssets} from "./peer/AllowAssets.sol";
+import {PeerDenyAssets} from "./peer/DenyAssets.sol";
+import {PeerPull} from "./peer/Pull.sol";
+import {PeerPush} from "./peer/Push.sol";

package/contracts/Core.sol

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AccessControl} from "./core/Access.sol";
+import {Balances} from "./core/Balances.sol";
+import {Host} from "./core/Host.sol";
+import {FailedCall, NoOperation, OperationBase} from "./core/Operation.sol";
+import {Validator} from "./core/Validator.sol";
+import {HostDiscovery} from "./core/Host.sol";
+import {IHostDiscovery} from "./interfaces/IHostDiscovery.sol";

package/contracts/Events.sol

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {AccessEvent} from "./events/Access.sol";
+import {AssetEvent} from "./events/Asset.sol";
+import {BalanceEvent} from "./events/Balance.sol";
+import {CollateralEvent} from "./events/Collateral.sol";
+import {CommandEvent} from "./events/Command.sol";
+import {DebtEvent} from "./events/Debt.sol";
+import {DepositEvent} from "./events/Deposit.sol";
+import {EventEmitter} from "./events/Emitter.sol";
+import {GovernedEvent} from "./events/Governed.sol";
+import {HostAnnouncedEvent} from "./events/HostAnnounced.sol";
+import {ListingEvent} from "./events/Listing.sol";
+import {PeerEvent} from "./events/Peer.sol";
+import {QuoteEvent} from "./events/Quote.sol";
+import {FastishEvent} from "./events/Fastish.sol";
+import {WithdrawalEvent} from "./events/Withdraw.sol";

package/contracts/Schema.sol

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {
+    ALLOCATION,
+    ALLOCATION_KEY,
+    AMOUNT,
+    AMOUNT_KEY,
+    ASSET,
+    ASSET_KEY,
+    AUTH,
+    AUTH_KEY,
+    AUTH_PROOF_LEN,
+    AUTH_TOTAL_LEN,
+    BALANCE,
+    BALANCE_KEY,
+    BOUNTY,
+    BOUNTY_KEY,
+    BlockPairRef,
+    BlockRef,
+    CUSTODY,
+    CUSTODY_KEY,
+    DataPairRef,
+    DataRef,
+    FUNDING,
+    FUNDING_KEY,
+    HostAmount,
+    UserAmount,
+    LISTING,
+    LISTING_KEY,
+    Listing,
+    MAXIMUM,
+    MAXIMUM_KEY,
+    MINIMUM,
+    MINIMUM_KEY,
+    MemRef,
+    NODE,
+    NODE_KEY,
+    QUANTITY,
+    QUANTITY_KEY,
+    PARTY,
+    PARTY_KEY,
+    RATE,
+    RATE_KEY,
+    RECIPIENT,
+    RECIPIENT_KEY,
+    ROUTE,
+    ROUTE_EMPTY,
+    ROUTE_KEY,
+    STEP,
+    STEP_KEY,
+    TX,
+    TX_KEY,
+    Tx,
+    Writer,
+    AssetAmount
+} from "./blocks/Schema.sol";

package/contracts/Utils.sol

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {
+    CLAIMS,
+    BALANCES,
+    CUSTODIES,
+    PIPE,
+    SETUP,
+    TRANSACTIONS
+} from "./utils/Channels.sol";
+import {
+    ACCOUNT_FAMILY,
+    accountEvmAddr,
+    accountPrefix,
+    addrOr,
+    ADMIN_PREFIX,
+    ensureEvmAccount,
+    InvalidAccount,
+    isAdminAccount,
+    toAdminAccount,
+    toUserAccount,
+    USER_PREFIX
+} from "./utils/Accounts.sol";
+import {
+    BadAmount,
+    ensureAmount,
+    ensureAssetRef,
+    ensureBalanceRef,
+    ERC20_PREFIX,
+    ERC721_PREFIX,
+    InvalidAsset,
+    isAsset32,
+    localErc20Addr,
+    localErc721Issuer,
+    resolveAmount,
+    toErc20Asset,
+    toErc721Asset,
+    toValueAsset,
+    VALUE_PREFIX,
+    ZeroAmount
+} from "./utils/Assets.sol";
+import {ECDSA} from "./utils/ECDSA.sol";
+import {
+    COMMAND_ARGS,
+    COMMAND_PREFIX,
+    ensureCommand,
+    ensureHost,
+    HOST_PREFIX,
+    InvalidId,
+    isCommand,
+    isHost,
+    isPeer,
+    localHostAddr,
+    localNodeAddr,
+    NODE_FAMILY,
+    PEER_ARGS,
+    PEER_PREFIX,
+    toCommandId,
+    toCommandSelector,
+    toHostId,
+    toPeerId,
+    toPeerSelector
+} from "./utils/Ids.sol";
+import {
+    ACCOUNT,
+    ADMIN,
+    ASSET,
+    COMMAND,
+    ERC20,
+    ERC721,
+    EVM32,
+    EVM64,
+    HOST,
+    NODE,
+    PEER,
+    USER,
+    VALUE
+} from "./utils/Layout.sol";
+import {bytes32ToString} from "./utils/Strings.sol";
+import {
+    applyBps,
+    beforeBps,
+    isFamily,
+    isLocal,
+    isLocalFamily,
+    matchesBase,
+    MAX_BPS,
+    max8,
+    max16,
+    max24,
+    max32,
+    max40,
+    max64,
+    max96,
+    max128,
+    max160,
+    routeSchema1,
+    routeSchema2,
+    toLocalBase,
+    toLocalFamily,
+    toUnspecifiedBase,
+    ValueOverflow
+} from "./utils/Utils.sol";
+import {InsufficientValue, msgValue, useValue, ValueBudget} from "./utils/Value.sol";