Skip to main content

PolicyKit Client

The PolicyKit class is the high-level orchestrator that ties together IPFS pinning, on-chain deployment, Lit Protocol integration, and policy simulation.

Constructor

import { PolicyKit } from "@policykit/sdk";

const pk = new PolicyKit({
  publicClient,
  walletClient,
  engineAddress: "0xPolicyEngineAddress",
  ipfsBackends: [
    { type: "pinata", jwt: process.env.PINATA_JWT },
  ],
  litConfig: {
    network: "naga",
    litActionCID: "QmLitActionCID",
  },
});

Options

OptionTypeRequiredDescription
publicClientPublicClientYesviem public client for reading chain state
walletClientWalletClientYesviem wallet client for sending transactions
engineAddressAddressYesDeployed PolicyEngine contract address
ipfsBackendsIPFSBackend[]YesArray of IPFS backend configurations
litConfigLitConfigNoLit Protocol configuration (required for Tier 3 rules)

IPFSBackend

interface IPFSBackend {
  type: "pinata" | "custom";
  jwt?: string;           // For Pinata
  endpoint?: string;      // For custom backends
  headers?: Record<string, string>;
}

LitConfig

interface LitConfig {
  network: "naga";          // Lit Protocol network
  litActionCID: string;      // CID of the deployed Lit Action
  pkpPublicKey?: string;     // PKP public key (if pre-provisioned)
}

Methods

deployPolicy(policy)

Deploy a policy to IPFS and register it on-chain.
const result = await pk.deployPolicy(policy);

console.log(result.cid);     // IPFS CID of the policy
console.log(result.txHash);  // On-chain registration tx hash
ParameterTypeDescription
policyPolicyThe policy to deploy
Returns: Promise<DeployResult>
interface DeployResult {
  cid: string;         // IPFS content identifier
  txHash: Hex;         // Transaction hash
  blockNumber: bigint; // Block number of registration
}

updatePolicy(policy)

Update an existing policy. Pins the new version to IPFS and updates the on-chain reference.
const result = await pk.updatePolicy(updatedPolicy);
ParameterTypeDescription
policyPolicyThe updated policy
Returns: Promise<DeployResult>

removePolicy()

Remove the active policy from the caller’s account.
const txHash = await pk.removePolicy();
Returns: Promise<Hex> — The transaction hash

getPolicy(account)

Retrieve the active policy for an account.
const policyData = await pk.getPolicy("0xAccountAddress");
ParameterTypeDescription
accountAddressThe smart account address
Returns: Promise<PolicyData | null>
interface PolicyData {
  cid: string;
  pkpAddress: Address;
  failMode: FailMode;
  encodedRules: Hex;
  requiresAttestation: boolean;
}

simulate(policy, txParams)

Simulate a transaction against a policy locally.
const report = await pk.simulate(policy, {
  target: "0xUniswapRouter",
  value: parseEther("1"),
  data: "0x38ed1739...",
});

if (report.allowed) {
  console.log("Transaction would be allowed");
} else {
  console.log("Blocked by:", report.failedRules);
}
ParameterTypeDescription
policyPolicyThe policy to evaluate against
txParamsTxParamsTransaction parameters
Returns: Promise<EvaluationReport>

requestAttestation(policy, txParams)

Request a Lit Protocol attestation for a transaction.
const attestation = await pk.requestAttestation(policy, {
  target: "0xUniswapRouter",
  value: parseEther("1"),
  data: "0x38ed1739...",
});

console.log(attestation.signature); // EIP-712 signature
console.log(attestation.deadline);  // Expiration timestamp
ParameterTypeDescription
policyPolicyThe policy with off-chain rules
txParamsTxParamsTransaction parameters
Returns: Promise<Attestation>
interface Attestation {
  signature: Hex;
  deadline: number;
  nonce: bigint;
}

Types

TxParams

interface TxParams {
  target: Address;    // Destination address
  value: bigint;      // ETH value in wei
  data: Hex;          // Calldata
}

EvaluationReport

interface EvaluationReport {
  allowed: boolean;
  results: RuleResult[];
  failedRules: RuleResult[];
}

interface RuleResult {
  rule: RuleType;
  tier: 1 | 2 | 3;
  passed: boolean;
  reason?: string;
}