@rootzero/contracts 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.5.0
+
+### Breaking Changes
+
+- Refactored account, asset, and node IDs around the shared convention that
+  first byte `0x00` means opaque and nonzero means structured.
+- Replaced the previous generic ID helpers with `Nodes` for structured host,
+  chain, command, peer, query, and guard node IDs.
+- Changed assets to single-word IDs: `bytes32 asset` is now the unique asset key
+  without a separate metadata field or asset slot.
+- `Payout` now passes destination accounts through to the hook unchanged; payout
+  account policy is the hook implementation's responsibility.
+
+### Added
+
+- Added `Ids` as the shared helper library for opaque IDs, including
+  `Ids.isOpaque`, `Ids.opaque`, `Ids.toKeccak`, and `Ids.matchKeccak`.
+- Added opaque account, asset, and node helper wrappers in `Accounts`, `Assets`,
+  and `Nodes`.
+- Added `Asset(uint indexed host, bytes32 asset, bytes preimage)` for declaring
+  opaque asset preimages.
+- Documented opaque preimages as `[formatHash:1][payload...]`, where `0x01`
+  means keccak256.
+
+## 1.4.0
+
+### Breaking Changes
+
+- Replaced the `Chain` discovery event with `Commander(uint indexed host, uint chain, bytes32 native, bytes32 admin)`.
+- Removed the `Transfer` flow event; account flows should be represented with `Spent` and `Received`.
+- Renamed the indexed `Labeled` event parameter from `id` to `entity` in the published ABI string.
+
+### Added
+
+- Added `Route(uint indexed host, uint chain, uint context)` for generic cross-chain route discovery.
+- Added `Actions.Refund` for unused payable command value returned through settlement hooks.
+
 ## 1.3.0
 
 ### Breaking Changes

package/Endpoints.sol

@@ -36,11 +36,12 @@ import { Unauthorize } from "./commands/admin/Unauthorize.sol";
 import { PeerBase, encodePeerCall } from "./peer/Base.sol";
 import { PeerAllowAssets, IPeerAllowAssets } from "./peer/AllowAssets.sol";
 import { PeerAllowance, IPeerAllowance } from "./peer/Allowance.sol";
-import { PeerBalancePull, BalancePullHook, IPeerBalancePull } from "./peer/BalancePull.sol";
-import { PeerCreditTo, IPeerCreditTo } from "./peer/Credit.sol";
-import { PeerDebitFrom, IPeerDebitFrom } from "./peer/Debit.sol";
+import { PeerRedeemBalance, RedeemBalanceHook, IPeerRedeemBalance } from "./peer/Redeem.sol";
+import { PeerCreditAccount, IPeerCreditAccount } from "./peer/Credit.sol";
+import { PeerDebitAccount, IPeerDebitAccount } from "./peer/Debit.sol";
 import { PeerDenyAssets, IPeerDenyAssets } from "./peer/DenyAssets.sol";
 import { PeerPipePayable, IPeerPipePayable } from "./peer/Pipe.sol";
+import { PeerRecover, RecoverHook, IPeerRecover } from "./peer/Recover.sol";
 import { PeerDispatchPayable, IPeerDispatchPayable } from "./peer/Dispatch.sol";
 import { PeerSettle, IPeerSettle } from "./peer/Settle.sol";
 

package/Events.sol

@@ -5,10 +5,10 @@ pragma solidity ^0.8.33;
 // Import this file to get access to every event emitter in one import.
 
 import { AdminEvent } from "./events/Admin.sol";
-import { AssetStatusEvent } from "./events/Asset.sol";
+import { AssetEvent, AssetStatusEvent } from "./events/Asset.sol";
 import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
-import { ChainEvent } from "./events/Chain.sol";
+import { CommanderEvent } from "./events/Commander.sol";
 import { CommandEvent } from "./events/Command.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
@@ -22,8 +22,8 @@ import { NodeEvent } from "./events/Node.sol";
 import { PeerEvent } from "./events/Peer.sol";
 import { QueryEvent } from "./events/Query.sol";
 import { RootedEvent } from "./events/Rooted.sol";
+import { RouteEvent } from "./events/Route.sol";
 import { SpentEvent } from "./events/Spent.sol";
-import { TransferEvent } from "./events/Transfer.sol";
 import { UnlockedEvent } from "./events/Unlocked.sol";
 
 

package/README.md

@@ -36,14 +36,13 @@ pragma solidity ^0.8.33;
 
 import { Host, Balances } from "@rootzero/contracts/Core.sol";
 import { Deposit } from "@rootzero/contracts/Endpoints.sol";
-import { Assets } from "@rootzero/contracts/Utils.sol";
 
 contract ExampleHost is Host, Balances, Deposit {
     constructor(address rootzero) Host(rootzero) {}
 
-    function deposit(bytes32 account, bytes32 asset, bytes32 meta, uint amount) internal override {
-        uint balance = creditTo(account, Assets.slot(asset, meta), amount);
-        emit Balance(account, asset, meta, balance, int(amount), depositId);
+    function deposit(bytes32 account, bytes32 asset, uint amount) internal override {
+        uint balance = creditTo(account, asset, amount);
+        emit Balance(account, asset, balance, int(amount), depositId);
     }
 }
 ```
@@ -58,7 +57,7 @@ implementations):
 const host = await ethers.deployContract("ExampleHost", [deployer.address]);
 
 const account = encodeUserAccount(user.address); // receiving account
-const request = encodeAmountBlock(asset, meta, 100n); // what to deposit
+const request = encodeAmountBlock(asset, 100n); // what to deposit
 await host.deposit({ account, state: "0x", request }); // emits Balance
 ```
 
@@ -79,10 +78,10 @@ The key is `bytes4(keccak256("#name"))`, and the payload layout is described by
 a schema string. For example, the block that requests a deposit:
 
 ```txt
-#amount { bytes32 asset, bytes32 meta, uint amount }
+#amount { bytes32 asset, uint amount }
 ```
 
-is 104 bytes on the wire: an 8-byte header followed by three big-endian 32-byte
+is 72 bytes on the wire: an 8-byte header followed by two big-endian 32-byte
 fields. There is no ABI encoding and no chain-specific type anywhere in the
 format — field types are chain-neutral integers, bytes, and booleans. A deposit
 request built for an EVM host is byte-for-byte the request a CosmWasm or Solana
@@ -114,8 +113,8 @@ import { concat } from "ethers";
 import { encodeAmountBlock } from "./helpers/blocks";
 
 const request = concat([
-  encodeAmountBlock(usdc, meta, 250_000_000n),
-  encodeAmountBlock(dai, meta, 250n * 10n ** 18n),
+  encodeAmountBlock(usdc, 250_000_000n),
+  encodeAmountBlock(dai, 250n * 10n ** 18n),
 ]);
 // deposit(request) returns two #balance blocks, one per #amount
 ```
@@ -124,29 +123,57 @@ Everything downstream keeps this shape: commands loop over request blocks,
 settlement loops over transactions, pipelines loop over steps. Batching is
 never a special case.
 
-## IDs, Accounts, and Assets
+## IDs, Accounts, Assets, and Nodes
 
-Everything the protocol touches — accounts, assets, chains, hosts, endpoints —
-is identified by a self-describing 256-bit ID:
+Everything the protocol touches - accounts, assets, chains, hosts, endpoints -
+is identified by one 32-byte word. The first byte selects the convention:
+
+- `0x00`: opaque ID, encoded as `0x00 || bytes31(hash)`. The hash preimage is
+  not recoverable from the ID; use a lookup table or witness data when the
+  native account, asset metadata, or node target is needed.
+- nonzero: structured ID. The value can be deconstructed according to its
+  layout.
+
+Opaque preimages start with:
+
+```txt
+[uint8 formatHash][payload...]
+```
+
+Only the first byte is protocol-level convention for now. `0x01` means
+keccak256. The remaining payload format is host/domain-specific until a future
+standard defines it.
+
+The field supplies the role for opaque IDs: a `bytes32 asset` with first byte
+`0x00` is still an asset, but its native metadata must come from lookup or
+witness data. The Solidity helpers below construct and deconstruct structured
+EVM IDs.
+
+Structured EVM IDs use:
 
 ```txt
 [uint32 type][uint32 chainid][192-bit payload]
 ```
 
-where `type` packs `[vm][width][category][subtype]`. Any ID therefore announces
-what it is (an account, an asset, a node) and which chain it lives on, and the
-payload usually embeds the underlying address. User accounts are
-chain-agnostic; admin and guardian accounts are chain-local. Assets cover the
-native coin, ERC-20, ERC-721, and ERC-1155; wide identities carry a second
-`meta` word (an ERC-721 token id, for example). Nodes are hosts, commands,
-peers, queries, and guards.
+where `type` packs `[uint16 representation][uint8 category][uint8 subtype]`. A
+structured ID announces what it is (an account, an asset, a node) and which
+chain it lives on, and the payload usually embeds the underlying address. User
+accounts are chain-agnostic; admin and guardian accounts are chain-local.
+Assets are unique IDs in the same single-word form as accounts and nodes.
+Nodes are hosts, commands, peers, queries, and guards.
+
+Opaque asset declarations use `Asset(host, asset, preimage)`. The preimage
+starts with a one-byte format/hash tag, letting offchain indexers or witnesses
+verify and resolve `0x00 || bytes31(hash(preimage))` assets. `0x01` means
+keccak256.
 
 The `Utils.sol` entry point provides the constructors and inspectors:
 
 ```solidity
 bytes32 account = Accounts.toUser(msg.sender); // chain-agnostic user account
 bytes32 asset = Assets.toErc20(tokenAddress);  // ERC-20 asset ID
-uint hostId = Ids.toHost(address(this));       // host node ID
+uint hostId = Nodes.toHost(address(this));       // host node ID
+bytes32 opaque = Ids.toKeccak(preimage);  // 0x00-prefixed opaque ID
 ```
 
 ## Hosts
@@ -197,9 +224,9 @@ function deposit(CommandContext calldata c) external onlyCommand returns (bytes
     Writer memory writer = Writers.allocBalances(groups);
 
     while (request.i < request.len) {
-        (bytes32 asset, bytes32 meta, uint amount) = request.unpackAmount();
-        deposit(c.account, asset, meta, amount); // host policy hook
-        writer.appendBalance(asset, meta, amount);
+        (bytes32 asset, uint amount) = request.unpackAmount();
+        deposit(c.account, asset, amount); // host policy hook
+        writer.appendBalance(asset, amount);
     }
 
     request.complete();
@@ -270,8 +297,8 @@ standard `getBalances` query takes a run of positions and answers each one in
 order:
 
 ```txt
-request:  #accountAsset { bytes32 account, bytes32 asset, bytes32 meta }
-response: #accountAmount { bytes32 account, bytes32 asset, bytes32 meta, uint amount }
+request:  #accountAsset { bytes32 account, bytes32 asset }
+response: #accountAmount { bytes32 account, bytes32 asset, uint amount }
 ```
 
 Like commands, every query announces its request and response schemas at
@@ -283,7 +310,7 @@ Peers are the host-to-host surfaces, callable only by trusted hosts. The two
 central ones are batches all the way down:
 
 - `peerSettle` consumes `#transaction { bytes32 from, bytes32 to, bytes32 asset,
-  bytes32 meta, uint amount }` blocks, debiting `from` and crediting `to` per
+  uint amount }` blocks, debiting `from` and crediting `to` per
   block — how two hosts record settlement between their ledgers.
 - `peerPipePayable` consumes `#pipe` blocks, each carrying an account, an
   initial state, and a run of steps — a complete pipeline delivered by another
@@ -313,8 +340,8 @@ drop a trusted node immediately.
 Hosts are self-describing. At deployment a host emits the ABI of every event it
 uses (`EventAbi`), a discovery event per endpoint with its full schemas, and
 labels for human-readable names. State changes then follow evented
-conventions: `Balance` for every ledger change and flow events (`Transfer`,
-`Received`, `Spent`) for value movement, each tagged with the endpoint that
+conventions: `Balance` for every ledger change and flow events (`Received`,
+`Spent`, `Locked`, `Unlocked`) for value movement, each tagged with the endpoint that
 caused it. An indexer can reconstruct the entire repository — endpoints,
 names, access sets, balances — from logs alone, with no artifact files.
 
@@ -328,8 +355,8 @@ Import from the package entry points rather than deep paths:
   mixins and their hooks
 - `@rootzero/contracts/Cursors.sol` — `Cur` cursor reader, `Writers`, `Schemas`,
   `Keys`
-- `@rootzero/contracts/Utils.sol` — `Ids`, `Assets`, `Accounts`, layout and
-  value helpers
+- `@rootzero/contracts/Utils.sol` — `Ids`, `Nodes`, `Assets`, `Accounts`,
+  layout and value helpers
 - `@rootzero/contracts/Events.sol` — protocol event contracts
 
 Repo layout:
@@ -340,7 +367,7 @@ Repo layout:
 - `contracts/guards` — guardian direct actions
 - `contracts/queries` — read-only query endpoints
 - `contracts/blocks` — block schema, cursor parsing, writers
-- `contracts/utils` — IDs, assets, accounts, layout, ECDSA
+- `contracts/utils` — ids, nodes, assets, accounts, layout, ECDSA
 - `contracts/events` — event contracts and emitters
 - `docs` — [`Schema.md`](docs/Schema.md) (wire format and schema DSL)
 

package/Utils.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Layout, Utils, Value).
+// Aggregator: re-exports all utility libraries (Keys, Accounts, Actions, Assets, ECDSA, Ids, Nodes, Layout, Utils, Value).
 // Import this file to access the full utility surface without managing individual paths.
 
 import { Keys } from "./blocks/Keys.sol";
@@ -9,10 +9,11 @@ import { Accounts } from "./utils/Accounts.sol";
 import { Actions } from "./utils/Actions.sol";
 import { Amounts, Assets } from "./utils/Assets.sol";
 import { ECDSA } from "./utils/ECDSA.sol";
-import { Ids, Selectors } from "./utils/Ids.sol";
+import { Ids } from "./utils/Ids.sol";
+import { Nodes } from "./utils/Nodes.sol";
 import { Layout } from "./utils/Layout.sol";
 import { Schemas } from "./blocks/Schema.sol";
-import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, isLocalChain, isLocalFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toLocalFamily, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
+import { addrOr, applyBps, beforeBps, bytes32ToInt, bytes32ToString, divisible, hash32, intToBytes32, isFamily, matchesBase, MAX_BPS, max8, max16, max24, max32, max40, max64, max96, max128, max160, NotDivisible, retryTicket, toLocalBase, toUnspecifiedBase, ValueOverflow } from "./utils/Utils.sol";
 import { Budget, Values } from "./utils/Value.sol";