# PACT Rule CLI - API Reference This document provides comprehensive API reference for PACT Rule CLI commands, including detailed parameter specifications, response formats, and integration examples for regulatory compliance rule management. ## Table of Contents - [Command Interface](#command-interface) - [Global Options](#global-options) - [Commands](#commands) - [compile](#compile) - [test](#test) - [deploy](#deploy) - [validate](#validate) - [list](#list) - [status](#status) - [expand](#expand) - [diff](#diff) - [nl2rule](#nl2rule) - [Data Models](#data-models) - [Response Formats](#response-formats) - [Error Handling](#error-handling) - [Integration Examples](#integration-examples) ## Command Interface All PACT Rule CLI commands follow a consistent interface pattern: ```bash pact-rule [arguments] [options] [--global-options] ``` ### Exit Codes - `0`: Success - `1`: General error - `2`: Validation error - `3`: Compilation error - `4`: Deployment error - `5`: Test failure - `6`: AI service error ## Global Options These options are available for all commands: | Option | Type | Description | Default | |--------|------|-------------|---------| | `--config ` | string | Path to configuration file | `$PACT_CONFIG_PATH` | | `--verbose` | boolean | Enable verbose output | false | | `--no-banner` | boolean | Disable startup banner | false | | `--json` | boolean | Output results in JSON format | false | | `--proof` | boolean | Generate cryptographic proof | false | | `--debug` | boolean | Enable debug mode | false | | `--help` | boolean | Show command help | false | | `--version` | boolean | Show version information | false | ## Commands ### compile Compile regulation rules from JSON/YAML files into executable format. #### Syntax ```bash pact-rule compile [options] ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | string | Yes | Path to rule file (JSON or YAML) | #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--output ` | string | Output path for compiled rule | `.compiled.json` | | `--validate` | boolean | Validate before compiling | true | | `--optimize` | boolean | Optimize compiled output | false | #### Response Format **Standard Output:** ``` ✓ Rule compiled successfully Name: kyc-threshold Version: 1.0.0 Output: rules/kyc-threshold.compiled.json Hash: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` **JSON Output (`--json`):** ```json { "success": true, "input": "rules/kyc-threshold.yaml", "output": "rules/kyc-threshold.compiled.json", "rule": "kyc-threshold", "version": "1.0.0", "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6", "proof": "pact-proof-q7r8s9t0u1v2w3x4" } ``` #### Compiled Rule Format ```json { "name": "kyc-threshold", "version": "1.0.0", "description": "Enhanced KYC for high-value transactions", "conditions": [ { "field": "transaction.amount", "operator": ">", "value": 10000, "compiled": "(transaction.amount > 10000)" } ], "actions": [ { "type": "block", "params": { "reason": "KYC verification required", "code": "KYC_REQUIRED" }, "compiled": "block({\"reason\":\"KYC verification required\",\"code\":\"KYC_REQUIRED\"})" } ], "metadata": { "compiledAt": "2024-08-01T12:00:00Z", "compiler": "pact-rule@1.0.0" }, "hash": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" } ``` #### Examples ```bash # Basic compilation pact-rule compile rules/kyc-threshold.yaml # With custom output pact-rule compile rules/aml-rule.json --output dist/aml-compiled.json # With optimization and proof pact-rule compile rules/complex-rule.yaml --optimize --proof ``` ### test Test compiled rules against sample data to verify behavior. #### Syntax ```bash pact-rule test [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--rule ` | string | Yes | Rule name or ID to test | - | | `--data ` | string | Yes | Path to test data file | - | | `--report` | boolean | No | Generate detailed test report | false | #### Test Data Format ```json { "entries": [ { "id": "test-001", "transaction": { "amount": 15000, "currency": "USD" }, "user": { "kyc_status": "pending", "country": "US" } } ] } ``` #### Response Format **Standard Output:** ``` Testing rule: kyc-threshold Test data: test-data.json (2 entries) ✓ test-001: Rule triggered - Action: block ✗ test-002: Rule not triggered Results: 1/2 tests passed ``` **JSON Output (`--json`):** ```json { "success": true, "rule": "kyc-threshold", "testFile": "test-data.json", "results": [ { "entryId": "test-001", "triggered": true, "conditions": { "matched": ["transaction.amount > 10000"], "failed": [] }, "actions": ["block"], "details": { "reason": "KYC verification required", "code": "KYC_REQUIRED" } } ], "summary": { "total": 2, "passed": 1, "failed": 1, "successRate": 0.5 } } ``` #### Examples ```bash # Basic testing pact-rule test --rule kyc-threshold --data test-transactions.json # With detailed report pact-rule test --rule aml-screening --data suspicious-activity.json --report # JSON output for CI/CD pact-rule test --rule sanctions-check --data test-data.json --json ``` ### deploy Deploy compiled rules to blockchain or server infrastructure. #### Syntax ```bash pact-rule deploy [options] ``` #### Options | Option | Type | Required | Description | Default | |--------|------|----------|-------------|---------| | `--rule ` | string | Yes | Rule name or ID to deploy | - | | `--network ` | string | No | Target network | testnet | | `--gas-limit ` | number | No | Gas limit for blockchain | 300000 | | `--dry-run` | boolean | No | Simulate without executing | false | #### Network Options | Network | Description | Endpoint | |---------|-------------|----------| | `mainnet` | Production blockchain | Configured in .pactrc | | `testnet` | Test blockchain | Configured in .pactrc | | `local` | Local development | http://localhost:8545 | | `api` | Centralized API | Configured endpoint | #### Response Format **Standard Output:** ``` Deploying rule: kyc-threshold Network: testnet Gas Limit: 300000 ✓ Deployment successful Transaction: 0xabc123...def456 Block: 12345678 Gas Used: 250000 Status: Confirmed ``` **JSON Output (`--json`):** ```json { "success": true, "rule": "kyc-threshold", "network": "testnet", "deployment": { "transactionHash": "0xabc123...def456", "blockNumber": 12345678, "gasUsed": 250000, "contractAddress": "0x789...012", "status": "confirmed", "timestamp": "2024-08-01T12:00:00Z" }, "proof": "pact-proof-y7z8a9b0c1d2e3f4" } ``` #### Examples ```bash # Deploy to testnet pact-rule deploy --rule kyc-threshold --network testnet # Dry run with gas estimation pact-rule deploy --rule complex-rule --network mainnet --dry-run # Deploy with custom gas limit pact-rule deploy --rule aml-monitoring --network mainnet --gas-limit 500000 ``` ### validate Validate rule syntax and logic against JSON Schema. #### Syntax ```bash pact-rule validate [file] [options] ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | string | No* | Path to rule file | *Required unless `--all` is specified #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--strict` | boolean | Enable strict validation mode | false | | `--all` | boolean | Validate all rule files recursively | false | | `--verbose` | boolean | Show detailed validation information | false | #### Response Format **Standard Output:** ``` Validating: rules/kyc-threshold.yaml ✓ Syntax: Valid ✓ Schema: Compliant ✓ Logic: No conflicts detected Rule is valid and ready for compilation. ``` **Validation Errors:** ``` Validating: rules/invalid-rule.yaml ✗ Schema validation failed: - /conditions/0: missing required property 'field' - /actions/0/params: missing required property 'reason' - /version: must match pattern "^\d+\.\d+\.\d+$" 3 errors found. ``` **JSON Output (`--json`):** ```json { "success": false, "file": "rules/invalid-rule.yaml", "validation": { "syntax": true, "schema": false, "logic": true }, "errors": [ { "path": "/conditions/0", "message": "missing required property 'field'", "type": "schema" } ], "warnings": [] } ``` #### Examples ```bash # Validate single file pact-rule validate rules/kyc-threshold.yaml # Validate all rules with verbose output pact-rule validate --all --verbose # Strict validation pact-rule validate rules/complex-rule.json --strict ``` ### list List all deployed rules with filtering options. #### Syntax ```bash pact-rule list [options] ``` #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--active` | boolean | Show only active rules | false | | `--network ` | string | Filter by network | all | | `--limit ` | number | Limit number of results | 50 | #### Response Format **Standard Output:** ``` Deployed Rules (Network: testnet) ┌─────────────────┬─────────┬────────┬────────────┬─────────────────────┐ │ Rule ID │ Version │ Status │ Network │ Deployed │ ├─────────────────┼─────────┼────────┼────────────┼─────────────────────┤ │ kyc-threshold │ 1.0.0 │ Active │ testnet │ 2024-08-01 10:00:00 │ │ aml-screening │ 2.1.0 │ Active │ testnet │ 2024-07-15 14:30:00 │ │ sanctions-check │ 1.5.0 │ Paused │ testnet │ 2024-07-01 09:00:00 │ └─────────────────┴─────────┴────────┴────────────┴─────────────────────┘ Total: 3 rules ``` **JSON Output (`--json`):** ```json { "success": true, "rules": [ { "ruleId": "kyc-threshold", "version": "1.0.0", "status": "active", "network": "testnet", "deployedAt": "2024-08-01T10:00:00Z", "contractAddress": "0xabc...123", "lastUpdated": "2024-08-01T10:00:00Z" } ], "pagination": { "total": 3, "limit": 50, "offset": 0 } } ``` #### Examples ```bash # List all rules pact-rule list # Active rules on mainnet pact-rule list --active --network mainnet # Limited results pact-rule list --limit 10 --json ``` ### status Show deployment status and statistics for rules. #### Syntax ```bash pact-rule status [options] ``` #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--rule ` | string | Show status for specific rule | - | | `--detailed` | boolean | Show detailed statistics | false | #### Response Format **Standard Output (Overview):** ``` PACT Rule System Status Active Rules: 15 Total Deployments: 23 Networks: mainnet (10), testnet (13) Recent Activity: - kyc-threshold v1.0.0 deployed to testnet (2 hours ago) - aml-screening v2.1.0 updated on mainnet (1 day ago) - sanctions-check v1.5.0 paused on testnet (3 days ago) System Health: ✅ Operational ``` **Specific Rule Status:** ``` Rule: kyc-threshold Version: 1.0.0 Status: Active Deployments: - testnet: 0xabc...123 (Active since 2024-08-01) - mainnet: 0xdef...456 (Pending deployment) Statistics: - Total Evaluations: 1,234,567 - Triggers: 45,678 (3.7%) - Average Gas Cost: 125,000 - Last Triggered: 5 minutes ago ``` **JSON Output (`--json`):** ```json { "success": true, "system": { "activeRules": 15, "totalDeployments": 23, "networks": { "mainnet": 10, "testnet": 13 }, "health": "operational" }, "rule": { "id": "kyc-threshold", "version": "1.0.0", "status": "active", "deployments": [ { "network": "testnet", "address": "0xabc...123", "status": "active", "deployedAt": "2024-08-01T10:00:00Z" } ], "statistics": { "evaluations": 1234567, "triggers": 45678, "triggerRate": 0.037, "averageGasCost": 125000, "lastTriggered": "2024-08-01T11:55:00Z" } } } ``` #### Examples ```bash # System overview pact-rule status # Specific rule status pact-rule status --rule kyc-threshold # Detailed statistics pact-rule status --detailed --json ``` ### expand Generate AI-powered expansion and analysis of compliance rules. #### Syntax ```bash pact-rule expand [options] ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `file` | string | Yes | Path to rule file | #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--model ` | string | AI model to use | gpt-4 | | `--quiet` | boolean | Suppress summary output | false | #### Response Format **Standard Output:** ``` Expanding rule: kyc-threshold.yaml 📊 Rule Analysis ════════════════ Overview: This rule implements enhanced KYC requirements for high-value transactions, aligning with FATF Recommendation 10 and EU 5AMLD requirements. Compliance Implications: • Regulatory Alignment: FATF, EU 5AMLD, US BSA • Risk Coverage: Money laundering, terrorist financing • Customer Impact: 3-5% of transactions affected Edge Cases Identified: 1. Split transactions to avoid threshold → Recommendation: Implement velocity checks 2. Multiple currency conversions → Recommendation: Normalize to base currency 3. Account age considerations → Recommendation: Add time-based conditions Implementation Recommendations: • Add transaction velocity monitoring • Implement graduated thresholds by account age • Consider jurisdiction-specific variations • Add exemptions for verified institutional accounts Risk Assessment: • False Positive Rate: ~2-3% • Coverage: High-value transaction monitoring • Regulatory Compliance: Strong ``` **JSON Output (`--json`):** ```json { "success": true, "rule": "kyc-threshold", "analysis": { "overview": "Enhanced KYC requirements for high-value transactions", "compliance": { "frameworks": ["FATF", "EU-5AMLD", "US-BSA"], "riskCoverage": ["money-laundering", "terrorist-financing"], "customerImpact": 0.035 }, "edgeCases": [ { "scenario": "Split transactions", "risk": "high", "recommendation": "Implement velocity checks" } ], "recommendations": [ "Add transaction velocity monitoring", "Implement graduated thresholds" ], "riskAssessment": { "falsePositiveRate": 0.025, "coverage": "high", "compliance": "strong" } } } ``` #### Examples ```bash # Basic expansion pact-rule expand rules/kyc-threshold.yaml # With specific model pact-rule expand rules/complex-aml.json --model gpt-3.5-turbo # JSON output for processing pact-rule expand rules/sanctions.yaml --json --quiet ``` ### diff Compare two regulatory rule files and show differences. #### Syntax ```bash pact-rule diff [options] ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `fileA` | string | Yes | First rule file to compare | | `fileB` | string | Yes | Second rule file to compare | #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--explain` | boolean | Show detailed explanation | false | | `--json` | boolean | Output in JSON format | false | | `--export ` | string | Export report to file | - | #### Response Format **Standard Output:** ``` Comparing: kyc-threshold v1.0.0 → v1.1.0 Changes Detected: Conditions: ~ transaction.amount: 10000 → 5000 (threshold decreased) + user.account_age_days < 30 (new condition added) Actions: ~ block.reason: "KYC required" → "Enhanced KYC required" + notify.channel: "compliance-urgent" (new action added) Metadata: ~ version: 1.0.0 → 1.1.0 ~ updated: 2024-07-01 → 2024-08-01 ``` **With Explanation (`--explain`):** ``` Regulatory Impact Analysis: ⚠️ CRITICAL CHANGES: • Threshold decreased from $10,000 to $5,000 → Will affect 15% more transactions → Aligns with new EU guidelines • New account age requirement added → Targets new account fraud risk → May impact customer onboarding 📊 Compliance Implications: • Increased monitoring scope • Higher operational overhead • Better risk coverage for new accounts ``` **JSON Output (`--json`):** ```json { "success": true, "comparison": { "fileA": "rules/kyc-threshold-v1.0.yaml", "fileB": "rules/kyc-threshold-v1.1.yaml", "changes": { "conditions": { "modified": [ { "field": "transaction.amount", "oldValue": 10000, "newValue": 5000, "change": "decreased" } ], "added": [ { "field": "user.account_age_days", "operator": "<", "value": 30 } ], "removed": [] }, "actions": { "modified": [ { "type": "block", "field": "params.reason", "oldValue": "KYC required", "newValue": "Enhanced KYC required" } ], "added": [ { "type": "notify", "params": { "channel": "compliance-urgent" } } ] } }, "impact": { "severity": "high", "estimatedAffectedTransactions": 0.15, "complianceAlignment": "improved" } } } ``` #### Examples ```bash # Basic comparison pact-rule diff rules/old-kyc.yaml rules/new-kyc.yaml # With detailed explanation pact-rule diff kyc-v1.0.yaml kyc-v1.1.yaml --explain # Export to markdown pact-rule diff prod/aml.yaml dev/aml.yaml --explain --export changes.md # Version comparison pact-rule diff rule.001@v1.0 rule.001@v1.1 --json ``` ### nl2rule Convert natural language description into executable rule files. #### Syntax ```bash pact-rule nl2rule [options] ``` #### Parameters | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `prompt` | string | Yes | Natural language rule description | #### Options | Option | Type | Description | Default | |--------|------|-------------|---------| | `--format ` | string | Output format (yaml/json) | yaml | | `--out ` | string | Output filename | auto-generated | | `--model ` | string | AI model to use | gpt-4 | | `--fix` | boolean | Auto-fix validation errors | false | | `--simulate` | boolean | Run simulation test | false | | `--test-file ` | string | Test file for simulation | auto-selected | | `--quiet` | boolean | Suppress summary output | false | #### Response Format **Standard Output:** ``` ✅ Rule created: rules/_generated/transaction-limit-rule-001_2024-08-01.yaml 🧠 Title: High-Value Transaction Limit 🔍 Action: block | Risk Score: 80 ✓ Validation: Rule is valid and ready to use 📋 Conditions: transaction.amount>10000, user.kyc_status!=verified 🧪 Next steps: • Run pact-rule test rules/_generated/transaction-limit-rule-001_2024-08-01.yaml for detailed testing • Run pact-rule deploy rules/_generated/transaction-limit-rule-001_2024-08-01.yaml when ready ``` **Generated Rule Example:** ```yaml rule_id: rule.001 title: High-Value Transaction Limit description: Block transactions over $10000 without enhanced KYC category: transaction-monitoring severity: high version: 1.0.0 created: 2024-08-01 if: transaction.amount: ">10000" user.kyc_status: "!=verified" then: action: block risk_score: 80 reason: Enhanced KYC verification required for high-value transactions notification: channel: compliance-team priority: high metadata: generated_by: PACT Protocol NL2Rule AI generation_timestamp: 2024-08-01T12:00:00Z original_prompt: "Block transactions over $10000 without enhanced KYC" ``` **JSON Output (`--json`):** ```json { "success": true, "rule_id": "rule.001", "filename": "rules/_generated/transaction-limit-rule-001_2024-08-01.yaml", "format": "yaml", "prompt": "Block transactions over $10000 without enhanced KYC", "validation": { "valid": true, "errors": [], "warnings": [] } } ``` #### Examples ```bash # Basic generation pact-rule nl2rule "Block transactions over $10000 without enhanced KYC" # Generate JSON format with custom output pact-rule nl2rule "Flag high-velocity transactions" --format json --out velocity-check.json # With auto-fix and simulation pact-rule nl2rule "Monitor cross-border wire transfers" --fix --simulate # Using different AI model pact-rule nl2rule "Require MFA for account changes" --model gpt-3.5-turbo ``` ## Data Models ### Rule Definition Model ```typescript interface RuleDefinition { name: string; // Unique rule identifier version: string; // Semantic version (X.Y.Z) description?: string; // Human-readable description category?: string; // Rule category severity?: 'low' | 'medium' | 'high'; conditions: Condition[]; // Array of conditions (AND logic) actions: Action[]; // Array of actions to execute metadata?: Record; // Additional metadata } interface Condition { field: string; // Data field path (e.g., "transaction.amount") operator: string; // Comparison operator value: any; // Comparison value type?: string; // Value type hint } interface Action { type: string; // Action type (block, flag, notify, etc.) params: Record; // Action parameters priority?: number; // Execution priority } ``` ### Compiled Rule Model ```typescript interface CompiledRule extends RuleDefinition { hash: string; // SHA-256 hash of compiled rule conditions: CompiledCondition[]; // Conditions with compiled expressions actions: CompiledAction[]; // Actions with compiled functions metadata: { compiledAt: string; // ISO timestamp compiler: string; // Compiler version [key: string]: any; }; } interface CompiledCondition extends Condition { compiled: string; // Compiled expression } interface CompiledAction extends Action { compiled: string; // Compiled function call } ``` ### Test Data Model ```typescript interface TestData { entries: TestEntry[]; // Array of test entries } interface TestEntry { id: string; // Unique test identifier transaction?: TransactionData; // Transaction information user?: UserData; // User information metadata?: Record; // Additional test data } interface TransactionData { amount: number; currency: string; type: string; timestamp: string; [key: string]: any; } interface UserData { id: string; kyc_status: string; country: string; account_age_days: number; [key: string]: any; } ``` ### Deployment Model ```typescript interface Deployment { ruleId: string; version: string; network: string; status: 'pending' | 'active' | 'paused' | 'retired'; contractAddress?: string; transactionHash?: string; blockNumber?: number; gasUsed?: number; deployedAt: string; updatedAt: string; } ``` ## Response Formats ### Success Response ```json { "success": true, "data": { // Command-specific data }, "proof": "pact-proof-abc123def456", // If --proof option used "timestamp": "2024-08-01T12:00:00Z" } ``` ### Error Response ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Rule validation failed", "details": { "field": "/conditions/0/value", "error": "must be a number", "received": "string" } }, "timestamp": "2024-08-01T12:00:00Z" } ``` ## Error Handling ### Error Codes | Code | Description | HTTP Equivalent | |------|-------------|-----------------| | `VALIDATION_ERROR` | Rule validation failed | 400 | | `COMPILATION_ERROR` | Rule compilation failed | 400 | | `DEPLOYMENT_ERROR` | Deployment failed | 500 | | `TEST_FAILURE` | Test execution failed | 422 | | `FILE_NOT_FOUND` | Input file not found | 404 | | `NETWORK_ERROR` | Network connectivity issue | 503 | | `AUTH_ERROR` | Authentication failed | 401 | | `AI_SERVICE_ERROR` | AI service unavailable | 503 | ### Error Handling Examples **Validation Error Handling:** ```bash #!/bin/bash if ! pact-rule validate rules/new-rule.yaml; then echo "Validation failed, attempting to fix..." pact-rule nl2rule "$(cat rules/new-rule.yaml)" --fix --out rules/new-rule-fixed.yaml fi ``` **Deployment Error Recovery:** ```bash #!/bin/bash MAX_RETRIES=3 RETRY_COUNT=0 while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do if pact-rule deploy --rule kyc-threshold --network testnet; then echo "Deployment successful" break else RETRY_COUNT=$((RETRY_COUNT + 1)) echo "Deployment failed, retry $RETRY_COUNT of $MAX_RETRIES" sleep 10 fi done ``` ## Integration Examples ### Node.js Integration ```javascript const { exec } = require('child_process'); const { promisify } = require('util'); const execAsync = promisify(exec); class PactRuleClient { async compileRule(filePath) { try { const { stdout } = await execAsync( `pact-rule compile ${filePath} --json` ); return JSON.parse(stdout); } catch (error) { throw new Error(`Compilation failed: ${error.message}`); } } async testRule(ruleName, testData) { try { const { stdout } = await execAsync( `pact-rule test --rule ${ruleName} --data ${testData} --json` ); const result = JSON.parse(stdout); if (result.summary.successRate < 1.0) { throw new Error(`Tests failed: ${result.summary.failed} failures`); } return result; } catch (error) { throw new Error(`Testing failed: ${error.message}`); } } async deployRule(ruleName, network = 'testnet') { try { const { stdout } = await execAsync( `pact-rule deploy --rule ${ruleName} --network ${network} --json` ); return JSON.parse(stdout); } catch (error) { throw new Error(`Deployment failed: ${error.message}`); } } } // Usage const client = new PactRuleClient(); async function deployNewRule() { try { // Compile const compiled = await client.compileRule('rules/new-kyc.yaml'); console.log(`Rule compiled: ${compiled.hash}`); // Test const testResult = await client.testRule('new-kyc', 'test-data.json'); console.log(`Tests passed: ${testResult.summary.passed}/${testResult.summary.total}`); // Deploy const deployment = await client.deployRule('new-kyc', 'testnet'); console.log(`Deployed to: ${deployment.deployment.contractAddress}`); } catch (error) { console.error('Error:', error.message); } } ``` ### Python Integration ```python import subprocess import json from typing import Dict, Any class PactRuleClient: def compile_rule(self, file_path: str) -> Dict[str, Any]: """Compile a rule file""" try: result = subprocess.run( ['pact-rule', 'compile', file_path, '--json'], capture_output=True, text=True, check=True ) return json.loads(result.stdout) except subprocess.CalledProcessError as e: raise Exception(f"Compilation failed: {e.stderr}") def validate_rule(self, file_path: str) -> Dict[str, Any]: """Validate a rule file""" try: result = subprocess.run( ['pact-rule', 'validate', file_path, '--json'], capture_output=True, text=True, check=True ) return json.loads(result.stdout) except subprocess.CalledProcessError as e: return json.loads(e.stdout) if e.stdout else {"success": False} def generate_rule(self, prompt: str, format: str = 'yaml') -> Dict[str, Any]: """Generate rule from natural language""" try: result = subprocess.run( ['pact-rule', 'nl2rule', prompt, '--format', format, '--json'], capture_output=True, text=True, check=True ) return json.loads(result.stdout) except subprocess.CalledProcessError as e: raise Exception(f"Generation failed: {e.stderr}") # Usage client = PactRuleClient() # Generate a new rule prompt = "Block transactions from sanctioned countries" generated = client.generate_rule(prompt) print(f"Generated rule: {generated['filename']}") # Validate the generated rule validation = client.validate_rule(generated['filename']) if validation['success']: print("Rule is valid!") else: print(f"Validation errors: {validation['errors']}") # Compile if valid if validation['success']: compiled = client.compile_rule(generated['filename']) print(f"Compiled successfully: {compiled['hash']}") ``` ### CI/CD Integration ```yaml # .github/workflows/rule-deployment.yml name: Rule Deployment Pipeline on: push: paths: - 'rules/**/*.yaml' - 'rules/**/*.json' jobs: validate-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Install PACT Rule CLI run: npm install -g pact-rule - name: Validate Rules run: | pact-rule validate --all --json > validation-report.json if [ $(jq '.success' validation-report.json) != "true" ]; then echo "Validation failed" cat validation-report.json exit 1 fi - name: Run Tests run: | for rule in rules/*.yaml; do rule_name=$(basename "$rule" .yaml) if [ -f "tests/${rule_name}-test.json" ]; then pact-rule test --rule "$rule_name" --data "tests/${rule_name}-test.json" --json fi done - name: Deploy to Testnet if: github.ref == 'refs/heads/develop' run: | for rule in rules/*.yaml; do rule_name=$(basename "$rule" .yaml) pact-rule deploy --rule "$rule_name" --network testnet --json done - name: Deploy to Mainnet if: github.ref == 'refs/heads/main' run: | for rule in rules/*.yaml; do rule_name=$(basename "$rule" .yaml) pact-rule deploy --rule "$rule_name" --network mainnet --dry-run --json # Remove --dry-run when ready for production done ``` ### Webhook Integration Configure webhooks for rule events: ```javascript // webhook-handler.js const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhook/rule-deployed', (req, res) => { const { rule, network, deployment } = req.body; console.log(`Rule ${rule} deployed to ${network}`); console.log(`Contract: ${deployment.contractAddress}`); console.log(`Transaction: ${deployment.transactionHash}`); // Update internal systems updateRuleRegistry(rule, deployment); // Send notifications notifyComplianceTeam(rule, network); res.json({ received: true }); }); app.post('/webhook/rule-triggered', (req, res) => { const { rule, transaction, action } = req.body; console.log(`Rule ${rule} triggered: ${action.type}`); // Log for audit logRuleTrigger(rule, transaction, action); // Take action based on rule if (action.type === 'block') { blockTransaction(transaction.id); } else if (action.type === 'flag') { flagForReview(transaction.id, action.params); } res.json({ processed: true }); }); app.listen(3000, () => { console.log('Webhook handler listening on port 3000'); }); ``` --- This API reference provides comprehensive documentation for integrating PACT Rule CLI into compliance systems and automated workflows. For additional support, consult the main [README](README.md) or contact the development team.