@rootzero/contracts 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 Until the protocol reaches integration-stable status, minor versions may include
 breaking API changes. Breaking changes are called out explicitly.
 
+## 1.6.0
+
+### Added
+
+- Added `AdminBase` as the shared base for admin commands and exported it from
+  `Endpoints.sol`.
+- Added `Cursors.read1` and `Cursors.read2` for unchecked byte-sized calldata
+  reads.
+- Added `NativeAsset` as a reusable base for helpers that need the local native
+  asset ID without the full host runtime.
+- Added `Escrows` as a keyed ledger for amounts reserved outside normal
+  balances.
+- Added `Commitment(bytes32 indexed account, bytes32 key, bytes32 digest, uint status)`
+  and the `Commitments` core mixin for digest commitments and witness/recovery
+  flows.
+
 ## 1.5.0
 
 ### Breaking Changes

package/Core.sol

@@ -1,12 +1,14 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-// Aggregator: re-exports the core host, runtime, access, node-call, and validation layer.
+// Aggregator: re-exports the core host, runtime, access, ledger, node-call, and validation layer.
 // Import this file to bring the full rootzero host base layer into scope.
 
 import { AccessControl } from "./core/Access.sol";
 import { Balances, InsufficientFunds } from "./core/Balances.sol";
-import { Runtime } from "./core/Runtime.sol";
+import { Commitments } from "./core/Commitments.sol";
+import { Escrows, InsufficientEscrow } from "./core/Escrows.sol";
+import { NativeAsset, Runtime } from "./core/Runtime.sol";
 import { Host, IHostIntroduction } from "./core/Host.sol";
 import { FailedCall, NodeCalls } from "./core/Calls.sol";
 import { Payable } from "./core/Payable.sol";

package/Endpoints.sol

@@ -20,6 +20,7 @@ import { RelayPayable, DispatchPayableHook } from "./commands/Relay.sol";
 import { Withdraw, WithdrawHook } from "./commands/Withdraw.sol";
 
 // Admin commands
+import { AdminBase } from "./commands/admin/Base.sol";
 import { AllowAssets, AllowAssetsHook } from "./commands/admin/AllowAssets.sol";
 import { Allowance, AllowanceHook } from "./commands/admin/Allowance.sol";
 import { Appoint } from "./commands/admin/Appoint.sol";

package/Events.sol

@@ -10,6 +10,7 @@ import { Actions } from "./utils/Actions.sol";
 import { BalanceEvent } from "./events/Balance.sol";
 import { CommanderEvent } from "./events/Commander.sol";
 import { CommandEvent } from "./events/Command.sol";
+import { CommitmentEvent } from "./events/Commitment.sol";
 import { PositionEvent } from "./events/Position.sol";
 import { ReceivedEvent } from "./events/Received.sol";
 import { EventEmitter } from "./events/Emitter.sol";

package/blocks/Cursors.sol

@@ -599,6 +599,30 @@ library Cursors {
         cur.i += n;
     }
 
+    /// @notice Read the next byte from the cursor and advance by 1 byte.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 1 byte.
+    /// @return value Loaded bytes1 value.
+    function read1(Cur memory cur) internal pure returns (bytes1 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 1;
+    }
+
+    /// @notice Read the next 2 bytes from the cursor and advance by 2 bytes.
+    /// @dev Performs no bounds, key, length, or cursor checks.
+    /// @param cur Cursor whose current position is advanced by 2 bytes.
+    /// @return value Loaded bytes2 value.
+    function read2(Cur memory cur) internal pure returns (bytes2 value) {
+        uint abs = cur.offset + cur.i;
+        assembly ("memory-safe") {
+            value := calldataload(abs)
+        }
+        cur.i += 2;
+    }
+
     /// @notice Read the next 4 bytes from the cursor and advance by 4 bytes.
     /// @dev Performs no bounds, key, length, or cursor checks.
     /// @param cur Cursor whose current position is advanced by 4 bytes.

package/commands/admin/AllowAssets.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 abstract contract AllowAssetsHook {
@@ -16,7 +15,7 @@ abstract contract AllowAssetsHook {
 /// @title AllowAssets
 /// @notice Admin command that permits a list of assets via a virtual hook.
 /// Each ASSET block in the request calls `allowAsset`. Only callable by the admin account.
-abstract contract AllowAssets is CommandBase, AdminEvent, AllowAssetsHook {
+abstract contract AllowAssets is AdminBase, AllowAssetsHook {
     uint internal immutable allowAssetsId = commandId(this.allowAssets.selector);
 
     constructor() {

package/commands/admin/Allowance.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandBase, CommandContext, Keys} from "../Base.sol";
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
 import {Cursors, Cur, Schemas} from "../../Cursors.sol";
-import {AdminEvent} from "../../events/Admin.sol";
 using Cursors for Cur;
 
 abstract contract AllowanceHook {
@@ -20,7 +19,7 @@ abstract contract AllowanceHook {
 /// @title Allowance
 /// @notice Admin command that applies cross-host allowance entries via a virtual hook.
 /// Each ALLOWANCE block grants or updates a host-scoped asset cap. Only callable by the admin account.
-abstract contract Allowance is CommandBase, AdminEvent, AllowanceHook {
+abstract contract Allowance is AdminBase, AllowanceHook {
     uint internal immutable allowanceId = commandId(this.allowance.selector);
 
     constructor() {

package/commands/admin/Appoint.sol

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 /// @title Appoint
 /// @notice Admin command that grants guardian status to a list of account IDs.
 /// Each ACCOUNT block in the request is enabled as a guardian on the host.
 /// Only callable by the admin account.
-abstract contract Appoint is CommandBase, AdminEvent {
+abstract contract Appoint is AdminBase {
     uint internal immutable appointId = commandId(this.appoint.selector);
 
     constructor() {

package/commands/admin/Authorize.sol

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 /// @title Authorize
 /// @notice Admin command that grants authorization to a list of node IDs.
 /// Each NODE block in the request is authorized on the host.
 /// Only callable by the admin account.
-abstract contract Authorize is CommandBase, AdminEvent {
+abstract contract Authorize is AdminBase {
     uint internal immutable authorizeId = commandId(this.authorize.selector);
 
     constructor() {

package/commands/admin/Base.sol

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommandBase, CommandContext, Keys} from "../Base.sol";
+import {AdminEvent} from "../../events/Admin.sol";
+
+/// @title AdminBase
+/// @notice Shared base for admin commands.
+abstract contract AdminBase is CommandBase, AdminEvent {}

package/commands/admin/DenyAssets.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 abstract contract DenyAssetsHook {
@@ -16,7 +15,7 @@ abstract contract DenyAssetsHook {
 /// @title DenyAssets
 /// @notice Admin command that blocks a list of assets via a virtual hook.
 /// Each ASSET block in the request calls `denyAsset`. Only callable by the admin account.
-abstract contract DenyAssets is CommandBase, AdminEvent, DenyAssetsHook {
+abstract contract DenyAssets is AdminBase, DenyAssetsHook {
     uint internal immutable denyAssetsId = commandId(this.denyAssets.selector);
 
     constructor() {

package/commands/admin/Destroy.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 
 using Cursors for Cur;
 
@@ -16,7 +15,7 @@ abstract contract DestroyHook {
 /// @title Destroy
 /// @notice Admin command that runs host teardown logic via a virtual hook.
 /// The full request is passed to `destroy` as a cursor. Only callable by the admin account.
-abstract contract Destroy is CommandBase, AdminEvent, DestroyHook {
+abstract contract Destroy is AdminBase, DestroyHook {
     uint internal immutable destroyId = commandId(this.destroy.selector);
 
     constructor(string memory input) {

package/commands/admin/Dismiss.sol

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 /// @title Dismiss
 /// @notice Admin command that revokes guardian status from a list of account IDs.
 /// Each ACCOUNT block in the request is disabled as a guardian on the host.
 /// Only callable by the admin account.
-abstract contract Dismiss is CommandBase, AdminEvent {
+abstract contract Dismiss is AdminBase {
     uint internal immutable dismissId = commandId(this.dismiss.selector);
 
     constructor() {

package/commands/admin/Execute.sol

@@ -1,10 +1,9 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandBase, CommandContext, Keys} from "../Base.sol";
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
 import {Payable} from "../../core/Payable.sol";
 import {Cursors, Cur, Schemas} from "../../Cursors.sol";
-import {AdminEvent} from "../../events/Admin.sol";
 import {Budget} from "../../utils/Value.sol";
 import {Nodes} from "../../utils/Nodes.sol";
 
@@ -15,7 +14,7 @@ using Cursors for Cur;
 /// Each CALL block specifies a target node ID, chain resources, and raw calldata payload.
 /// Only callable by the admin account.
 /// Unspent top-level `msg.value` remains on this host.
-abstract contract ExecutePayable is CommandBase, Payable, AdminEvent {
+abstract contract ExecutePayable is AdminBase, Payable {
     uint internal immutable executePayableId = commandId(this.executePayable.selector);
 
     constructor() {

package/commands/admin/Init.sol

@@ -1,9 +1,8 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 
 using Cursors for Cur;
 
@@ -16,7 +15,7 @@ abstract contract InitHook {
 /// @title Init
 /// @notice Admin command that runs host initialization logic via a virtual hook.
 /// The full request is passed to `init` as a cursor. Only callable by the admin account.
-abstract contract Init is CommandBase, AdminEvent, InitHook {
+abstract contract Init is AdminBase, InitHook {
     uint internal immutable initId = commandId(this.init.selector);
 
     constructor(string memory input) {

package/commands/admin/Label.sol

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import {CommandBase, CommandContext, Keys} from "../Base.sol";
+import {AdminBase, CommandContext, Keys} from "./Base.sol";
 import {Cursors, Cur, Schemas} from "../../Cursors.sol";
-import {AdminEvent} from "../../events/Admin.sol";
 using Cursors for Cur;
 
 /// @title Label
 /// @notice Admin command that publishes namespaced labels for node IDs.
 /// Each LABEL block in the request emits one `Labeled` event. Only callable by
 /// the admin account.
-abstract contract Label is CommandBase, AdminEvent {
+abstract contract Label is AdminBase {
     uint internal immutable labelId = commandId(this.label.selector);
 
     constructor() {

package/commands/admin/Unauthorize.sol

@@ -1,16 +1,15 @@
 // SPDX-License-Identifier: GPL-3.0-only
 pragma solidity ^0.8.33;
 
-import { CommandBase, CommandContext, Keys } from "../Base.sol";
+import { AdminBase, CommandContext, Keys } from "./Base.sol";
 import { Cursors, Cur, Schemas } from "../../Cursors.sol";
-import { AdminEvent } from "../../events/Admin.sol";
 using Cursors for Cur;
 
 /// @title Unauthorize
 /// @notice Admin command that revokes authorization from a list of node IDs.
 /// Each NODE block in the request is deauthorized on the host.
 /// Only callable by the admin account.
-abstract contract Unauthorize is CommandBase, AdminEvent {
+abstract contract Unauthorize is AdminBase {
     uint internal immutable unauthorizeId = commandId(this.unauthorize.selector);
 
     constructor() {

package/core/Commitments.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import {CommitmentEvent} from "../events/Commitment.sol";
+
+/// @title Commitments
+/// @notice On-chain registry for account-scoped digest commitments.
+abstract contract Commitments is CommitmentEvent {
+    /// @dev key -> committed digest.
+    mapping(bytes32 key => bytes32 digest) internal commitments;
+
+    /// @notice Clear the commitment under `key` and return the removed digest.
+    /// @param key Commitment lookup key.
+    /// @return digest Removed digest.
+    function uncommit(bytes32 key) internal returns (bytes32 digest) {
+        digest = commitments[key];
+        delete commitments[key];
+    }
+}

package/core/Escrows.sol

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+/// @dev Thrown when a debit would reduce an escrow below zero.
+error InsufficientEscrow();
+
+/// @title Escrows
+/// @notice On-chain ledger for amounts reserved outside normal spendable balances.
+abstract contract Escrows {
+    /// @dev key -> escrowed amount.
+    mapping(bytes32 key => uint amount) internal escrows;
+
+    /// @notice Add `amount` to an escrow and return the new balance.
+    /// @param key Escrow key derived by the caller.
+    /// @param amount Amount to reserve.
+    /// @return balance New escrow balance after the credit.
+    function creditEscrow(bytes32 key, uint amount) internal returns (uint balance) {
+        balance = escrows[key] += amount;
+    }
+
+    /// @notice Deduct `amount` from an escrow and return the new balance.
+    /// Reverts with `InsufficientEscrow` if the current balance is less than `amount`.
+    /// @param key Escrow key derived by the caller.
+    /// @param amount Amount to release.
+    /// @return balance New escrow balance after the debit.
+    function debitEscrow(bytes32 key, uint amount) internal returns (uint balance) {
+        balance = escrows[key];
+        if (balance < amount) revert InsufficientEscrow();
+        unchecked {
+            balance -= amount;
+        }
+        escrows[key] = balance;
+    }
+}

package/core/Runtime.sol

@@ -4,11 +4,16 @@ pragma solidity ^0.8.33;
 import {Assets} from "../utils/Assets.sol";
 import {Nodes} from "../utils/Nodes.sol";
 
+/// @title NativeAsset
+/// @notice Shared native asset identity for host helpers.
+abstract contract NativeAsset {
+    /// @dev Asset ID for the native chain coin/token, bound to the current chain at deployment.
+    bytes32 internal immutable nativeAsset = Assets.toNative();
+}
+
 /// @title Runtime
 /// @notice Shared runtime for host identity and native asset identity.
-abstract contract Runtime {
+abstract contract Runtime is NativeAsset {
     /// @dev This contract's host node ID, set to `Nodes.toHost(address(this))` at construction.
     uint public immutable host = Nodes.toHost(address(this));
-    /// @dev Asset ID for the native chain coin/token, bound to the current chain at deployment.
-    bytes32 internal immutable nativeAsset = Assets.toNative();
 }

package/events/Commitment.sol

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: GPL-3.0-only
+pragma solidity ^0.8.33;
+
+import { EventEmitter } from "./Emitter.sol";
+
+/// @notice Emitted when an account-scoped commitment is updated.
+abstract contract CommitmentEvent is EventEmitter {
+    string private constant ABI = "event Commitment(bytes32 indexed account, bytes32 key, bytes32 digest, uint status)";
+
+    /// @param account Account associated with the commitment.
+    /// @param key Commitment lookup key.
+    /// @param digest Committed digest. Zero may be used when clearing without revealing the previous digest.
+    /// @param status Commitment status. Zero means cleared; nonzero means committed or application-defined.
+    event Commitment(bytes32 indexed account, bytes32 key, bytes32 digest, uint status);
+
+    constructor() {
+        emit EventAbi(ABI);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rootzero/contracts",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Solidity contracts and protocol building blocks for rootzero hosts and commands.",
   "private": false,
   "license": "GPL-3.0-only",