shll-skills 3.1.0 → 4.0.0

package/dist/chunk-EUGNHCIP.mjs

@@ -0,0 +1,502 @@
+// node_modules/shll-policy-sdk/dist/index.js
+import {
+  createPublicClient,
+  createWalletClient,
+  http
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { bsc, bscTestnet } from "viem/chains";
+var PolicyGuardV4Abi = [
+  {
+    name: "validate",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "nfa", type: "address" },
+      { name: "tokenId", type: "uint256" },
+      { name: "agentAccount", type: "address" },
+      { name: "caller", type: "address" },
+      {
+        name: "action",
+        type: "tuple",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [
+      { name: "ok", type: "bool" },
+      { name: "reason", type: "string" }
+    ]
+  },
+  {
+    name: "getActivePolicies",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "instanceId", type: "uint256" }],
+    outputs: [{ name: "", type: "address[]" }]
+  },
+  {
+    name: "getTemplatePolicies",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "templateId", type: "bytes32" }],
+    outputs: [{ name: "", type: "address[]" }]
+  },
+  {
+    name: "instanceTemplateId",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "instanceId", type: "uint256" }],
+    outputs: [{ name: "", type: "bytes32" }]
+  }
+];
+var AgentNFAAbi = [
+  {
+    name: "execute",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      { name: "tokenId", type: "uint256" },
+      {
+        name: "action",
+        type: "tuple",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [{ name: "result", type: "bytes" }]
+  },
+  {
+    name: "executeBatch",
+    type: "function",
+    stateMutability: "payable",
+    inputs: [
+      { name: "tokenId", type: "uint256" },
+      {
+        name: "actions",
+        type: "tuple[]",
+        components: [
+          { name: "target", type: "address" },
+          { name: "value", type: "uint256" },
+          { name: "data", type: "bytes" }
+        ]
+      }
+    ],
+    outputs: [{ name: "results", type: "bytes[]" }]
+  },
+  {
+    name: "accountOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "userOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "userExpires",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "operatorOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "address" }]
+  },
+  {
+    name: "operatorExpiresOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "operatorNonceOf",
+    type: "function",
+    stateMutability: "view",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: [{ name: "", type: "uint256" }]
+  },
+  {
+    name: "setOperatorWithSig",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      {
+        name: "req",
+        type: "tuple",
+        components: [
+          { name: "tokenId", type: "uint256" },
+          { name: "renter", type: "address" },
+          { name: "operator", type: "address" },
+          { name: "expires", type: "uint64" },
+          { name: "nonce", type: "uint256" },
+          { name: "deadline", type: "uint256" }
+        ]
+      },
+      { name: "signature", type: "bytes" }
+    ],
+    outputs: []
+  },
+  {
+    name: "clearOperator",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "tokenId", type: "uint256" }],
+    outputs: []
+  }
+];
+var IPolicyAbi = [
+  {
+    name: "policyType",
+    type: "function",
+    stateMutability: "pure",
+    inputs: [],
+    outputs: [{ name: "", type: "bytes32" }]
+  },
+  {
+    name: "renterConfigurable",
+    type: "function",
+    stateMutability: "pure",
+    inputs: [],
+    outputs: [{ name: "", type: "bool" }]
+  },
+  {
+    name: "check",
+    type: "function",
+    stateMutability: "view",
+    inputs: [
+      { name: "instanceId", type: "uint256" },
+      { name: "caller", type: "address" },
+      { name: "target", type: "address" },
+      { name: "selector", type: "bytes4" },
+      { name: "callData", type: "bytes" },
+      { name: "value", type: "uint256" }
+    ],
+    outputs: [
+      { name: "ok", type: "bool" },
+      { name: "reason", type: "string" }
+    ]
+  }
+];
+var POLICY_TYPE_NAMES = {
+  // keccak256(abi.encodePacked("spending_limit"))
+  "0xfc881f20d88f7ec7e942f0b796f40ce121974015a83f091cd5ef2cf146443d4e": "spending_limit",
+  // keccak256(abi.encodePacked("cooldown"))
+  "0x7230b2ae91f8efdf9ea182e9a9d1fef92adfda3e61d5512778c2f81580b13d10": "cooldown",
+  // keccak256(abi.encodePacked("receiver_guard"))
+  "0xccead04e892f4bd05d3e2491948809479bf4641d233bf37f3fac8411960a97de": "receiver_guard",
+  // keccak256(abi.encodePacked("dex_whitelist"))
+  "0xb5ba0ef255153fe2c4c7201fbd5f2658f86e25a723f1844d5bf64a5c48e0c9ed": "dex_whitelist",
+  // keccak256(abi.encodePacked("defi_guard"))
+  "0xe109b0d2bf06e570d9aecb2cd18dafe849a5c1d8b9b9f6ecd8b9ed727f816bb9": "defi_guard",
+  // keccak256(abi.encodePacked("token_whitelist"))
+  "0xf4717a1c69e76a67584dd6d514cc591ec961b52113ec085dfe157bd9e238e1f3": "token_whitelist"
+};
+var PolicyClient = class {
+  publicClient;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _walletClient;
+  _operatorAddress;
+  agentNfaAddress;
+  policyGuardAddress;
+  constructor(config) {
+    const chain = config.chainId === 97 ? bscTestnet : bsc;
+    this.publicClient = createPublicClient({
+      chain,
+      transport: http(config.rpcUrl)
+    });
+    this.agentNfaAddress = config.agentNfaAddress;
+    this.policyGuardAddress = config.policyGuardAddress;
+    if (config.operatorPrivateKey) {
+      const account = privateKeyToAccount(config.operatorPrivateKey);
+      this._operatorAddress = account.address;
+      this._walletClient = createWalletClient({
+        account,
+        chain,
+        transport: http(config.rpcUrl)
+      });
+    } else {
+      this._operatorAddress = null;
+      this._walletClient = null;
+    }
+  }
+  // ═══════════════════════════════════════════════════════
+  //                     VALIDATION
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Validate an action against all active on-chain policies.
+   * This is an off-chain simulation — saves gas by catching rejections before submission.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param action - The action to validate
+   * @param callerOverride - Optional caller address override (defaults to operator)
+   */
+  async validate(tokenId, action, callerOverride) {
+    const caller = callerOverride ?? this._operatorAddress;
+    if (!caller) {
+      return { ok: false, reason: "No caller address \u2014 provide operatorPrivateKey or callerOverride" };
+    }
+    const vault = await this.getVault(tokenId);
+    try {
+      const [ok, reason] = await this.publicClient.readContract({
+        address: this.policyGuardAddress,
+        abi: PolicyGuardV4Abi,
+        functionName: "validate",
+        args: [
+          this.agentNfaAddress,
+          tokenId,
+          vault,
+          caller,
+          { target: action.target, value: action.value, data: action.data }
+        ]
+      });
+      return { ok, reason: reason || void 0 };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Simulation reverted";
+      return { ok: false, reason: `Simulation reverted: ${message.slice(0, 300)}` };
+    }
+  }
+  // ═══════════════════════════════════════════════════════
+  //                     EXECUTION
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Execute a single action through AgentNFA.
+   * Simulates first, then submits if validation passes.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param action - The action to execute
+   * @param skipValidation - Skip pre-flight validation (default: false)
+   */
+  async execute(tokenId, action, skipValidation = false) {
+    this.requireWallet();
+    if (!skipValidation) {
+      const sim = await this.validate(tokenId, action);
+      if (!sim.ok) {
+        throw new Error(`Policy rejected: ${sim.reason}`);
+      }
+    }
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "execute",
+      args: [tokenId, { target: action.target, value: action.value, data: action.data }]
+    });
+    return { hash };
+  }
+  /**
+   * Execute multiple actions atomically via AgentNFA.executeBatch().
+   * Useful for approve+swap in a single transaction.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @param actions - Array of actions to execute
+   * @param skipValidation - Skip per-action pre-flight validation (default: false)
+   */
+  async executeBatch(tokenId, actions, skipValidation = false) {
+    this.requireWallet();
+    if (!skipValidation) {
+      for (const action of actions) {
+        const sim = await this.validate(tokenId, action);
+        if (!sim.ok) {
+          throw new Error(`Policy rejected action (target=${action.target}): ${sim.reason}`);
+        }
+      }
+    }
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "executeBatch",
+      args: [
+        tokenId,
+        actions.map((a) => ({ target: a.target, value: a.value, data: a.data }))
+      ]
+    });
+    return { hash };
+  }
+  // ═══════════════════════════════════════════════════════
+  //                    POLICY QUERIES
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Get all active policies for an agent instance, with type info.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @returns Array of PolicyInfo objects
+   */
+  async getPolicies(tokenId) {
+    const addresses = await this.publicClient.readContract({
+      address: this.policyGuardAddress,
+      abi: PolicyGuardV4Abi,
+      functionName: "getActivePolicies",
+      args: [tokenId]
+    });
+    const results = [];
+    for (const addr of addresses) {
+      try {
+        const [policyType, renterConfigurable] = await Promise.all([
+          this.publicClient.readContract({
+            address: addr,
+            abi: IPolicyAbi,
+            functionName: "policyType"
+          }),
+          this.publicClient.readContract({
+            address: addr,
+            abi: IPolicyAbi,
+            functionName: "renterConfigurable"
+          })
+        ]);
+        const typeName = POLICY_TYPE_NAMES[policyType] ?? "unknown";
+        results.push({
+          address: addr,
+          policyType,
+          policyTypeName: typeName,
+          renterConfigurable
+        });
+      } catch {
+        results.push({
+          address: addr,
+          policyType: "0x",
+          policyTypeName: "unknown",
+          renterConfigurable: false
+        });
+      }
+    }
+    return results;
+  }
+  // ═══════════════════════════════════════════════════════
+  //                  OPERATOR PERMIT
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Read the current operator state for a token — useful for constructing permits.
+   *
+   * @param tokenId - Agent NFA token ID
+   * @returns Current operator, renter, vault, and nonce info
+   */
+  async getOperatorState(tokenId) {
+    const [operator, operatorExpires, renter, renterExpires, vault, operatorNonce] = await Promise.all([
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorExpiresOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "userOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "userExpires",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "accountOf",
+        args: [tokenId]
+      }),
+      this.publicClient.readContract({
+        address: this.agentNfaAddress,
+        abi: AgentNFAAbi,
+        functionName: "operatorNonceOf",
+        args: [tokenId]
+      })
+    ]);
+    return { operator, operatorExpires, renter, renterExpires, vault, operatorNonce };
+  }
+  /**
+   * Submit a signed OperatorPermit on-chain to authorize this runner as operator.
+   *
+   * @param permit - The OperatorPermit struct
+   * @param signature - EIP-712 signature from the renter
+   */
+  async setOperatorWithPermit(permit, signature) {
+    this.requireWallet();
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "setOperatorWithSig",
+      args: [
+        {
+          tokenId: permit.tokenId,
+          renter: permit.renter,
+          operator: permit.operator,
+          expires: permit.expires,
+          nonce: permit.nonce,
+          deadline: permit.deadline
+        },
+        signature
+      ]
+    });
+    return { hash };
+  }
+  /**
+   * Clear the operator permit for a token.
+   *
+   * @param tokenId - Agent NFA token ID
+   */
+  async clearOperator(tokenId) {
+    this.requireWallet();
+    const hash = await this._walletClient.writeContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "clearOperator",
+      args: [tokenId]
+    });
+    return { hash };
+  }
+  // ═══════════════════════════════════════════════════════
+  //                      HELPERS
+  // ═══════════════════════════════════════════════════════
+  /**
+   * Get the vault (AgentAccount) address for a token.
+   */
+  async getVault(tokenId) {
+    return await this.publicClient.readContract({
+      address: this.agentNfaAddress,
+      abi: AgentNFAAbi,
+      functionName: "accountOf",
+      args: [tokenId]
+    });
+  }
+  /**
+   * Get the operator address configured for this client.
+   */
+  getOperatorAddress() {
+    return this._operatorAddress;
+  }
+  requireWallet() {
+    if (!this._walletClient) {
+      throw new Error(
+        "PolicyClient: operatorPrivateKey is required for write operations (execute, setOperator)"
+      );
+    }
+  }
+};
+
+export {
+  PolicyClient
+};