Mandant Developer Hub & Architecture Specification

import { DynamicStructuredTool } from "@langchain/core/tools"
import { z } from "zod"
import { MandantClient } from "@mandant/sdk"
import { keccak256, toHex } from "viem"

export function createMandantEscrowTool(client: MandantClient, workerMandateId: `0x${string}`) {
  return new DynamicStructuredTool({
    name: "mandant_outcome_escrow",
    description: "Funds an ERC-8183 escrow for paid computation with onchain hash verification",
    schema: z.object({
      providerAddress: z.string().describe("Recipient service provider address"),
      amountUsdc: z.number().describe("Budget in USDC (e.g. 250)"),
      expectedDeliverableText: z.string().describe("Expected JSON schema or hash contract"),
    }),
    func: async ({ providerAddress, amountUsdc, expectedDeliverableText }) => {
      const expectedHash = keccak256(toHex(expectedDeliverableText))
      const amountUnits = BigInt(amountUsdc * 1e6)

      // 1. Lock funds into onchain JobAdapter
      const lockTx = await client.fundJob({
        mandateId: workerMandateId,
        provider: providerAddress as `0x${string}`,
        amount: amountUnits,
        deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
        expectedDeliverableHash: expectedHash,
      })

      return `Escrow locked in tx ${lockTx}. Funds protected by MandateTree balance conservation.`
    },
  })
}

from crewai.tools import BaseTool
from web3 import Web3

class CrewAIMandantTool(BaseTool):
    name: str = "delegate_budget_to_peer"
    description: str = "Delegates an attenuated micro-budget to a sub-worker agent in the swarm"

    def _run(self, peer_agent_address: str, budget_usdc: float) -> str:
        # Spawns depth-2 child mandate via MandateTree.spawn()
        print(f"Spawning child mandate for {peer_agent_address} with {budget_usdc} USDC limit")
        return f"Child mandate active on BNB Testnet. Invariant preserved: Idle - {budget_usdc} USDC."

import { type Plugin, type Action, type IAgentRuntime, type Memory } from "@elizaos/core"

export const mandantEscrowPlugin: Plugin = {
  name: "mandant-escrow",
  description: "Enforces hierarchical budget constraints and outcome-verified settlement on ElizaOS agents",
  actions: [
    {
      name: "MANDANT_ESCROW_PAY",
      similes: ["PAY_VENDOR_WITH_ESCROW", "LOCK_BUDGET_FOR_TASK"],
      validate: async (runtime: IAgentRuntime, message: Memory) => true,
      handler: async (runtime, message, state, options, callback) => {
        callback?.({
          text: "Locked $250 USDC in ERC-8183 escrow. Release conditioned upon hash verification.",
        })
        return true
      },
    },
  ],
}

function _sync(bytes32 mandateId) internal {
    MandateNode storage node = nodes[mandateId];
    if (node.status == NodeStatus.REVOKED) return;

    // 1. Check self expiry
    if (block.timestamp >= node.expiry && node.status == NodeStatus.ACTIVE) {
        node.status = NodeStatus.EXPIRED;
        _sweepIdleUp(mandateId);
        return;
    }

    if (node.parentId == bytes32(0)) return;

    // 2. Multi-hop ancestor walk up to MAX_DEPTH (5 hops)
    bytes32 curr = node.parentId;
    bool shouldRevoke = false;
    for (uint8 d = 0; d < MAX_DEPTH && curr != bytes32(0); d++) {
        MandateNode storage anc = nodes[curr];
        if (anc.status == NodeStatus.REVOKED || anc.status == NodeStatus.EXPIRED || block.timestamp >= anc.expiry) {
            shouldRevoke = true;
            break;
        }
        curr = anc.parentId;
    }

    // 3. Lazy revocation cascade and capital sweep
    if (shouldRevoke) {
        node.status = NodeStatus.REVOKED;
        _sweepIdleUp(mandateId);
    }
}

function _sweepIdleUp(bytes32 mandateId) internal returns (uint128 swept) {
    MandateNode storage node = nodes[mandateId];
    swept = node.idle;
    node.idle = 0;

    if (node.parentId == bytes32(0) || swept == 0) return swept;

    bytes32 curr = node.parentId;
    while (curr != bytes32(0)) {
        MandateNode storage ancestor = nodes[curr];
        if (ancestor.status == NodeStatus.ACTIVE) {
            ancestor.idle += swept;
            if (ancestor.childGranted >= swept) {
                ancestor.childGranted -= swept;
            } else {
                ancestor.childGranted = 0;
            }
            break;
        }
        curr = ancestor.parentId;
    }
}