Usage

What is KRNL SDK?

The KRNL SDK is a developer toolkit for interacting with the KRNL Protocol, enabling seamless workflow execution, delegated account management, and real-time monitoring. With the SDK, you can:

• Execute workflows using a simple DSL (domain-specific language)

• Track step-by-step workflow progress off-chain

• Monitor workflow status and on-chain settlement

• Integrate smart account functionality with delegated authority

The SDK provides React hooks, utilities, and type definitions to simplify development of KRNL-native dApps.

Important: Privy Wallet Requirement

The KRNL SDK requires Privy for wallet integration and must be used with @privy-io/react-auth.

Privy is currently one of the few wallet providers that fully supports EIP-7702 account abstraction, which is essential for KRNL Protocol’s delegated account functionality.

EIP-7702 enables:

• Temporary delegation of account authority

• Smart account capabilities on existing EOAs

• Gasless transactions via delegation

• Enhanced security without deploying separate smart contracts

Without Privy and EIP-7702 support, the SDK cannot enable the smart account features required for KRNL workflow execution.

Configure KRNL Protocol Connection

import { createConfig } from '@krnl/react-sdk';
import { sepolia } from 'viem/chains';

const krnlConfig = createConfig({
  chain: sepolia,
  delegatedContractAddress: '0x...', // KRNL delegated account contract
  privyAppId: 'your-privy-app-id',
  krnlNodeUrl: 'https://v0-1-0.node.lat/', // KRNL Protocol node endpoint
  // rpcUrl is optional – uses KRNL-optimized Privy RPC if not provided
});

---

Setup Providers

import { PrivyProvider } from '@privy-io/react-auth';
import { KRNLProvider } from '@krnl/react-sdk';

function App() {
  return (
    <PrivyProvider appId="your-privy-app-id">
      <KRNLProvider config={krnlConfig}>
        <YourDApp />
      </KRNLProvider>
    </PrivyProvider>
  );
}

---

Authorize KRNL Delegated Account

import { useKRNL } from '@krnl/react-sdk';

const { isAuthorized, enableSmartAccount, embeddedWallet } = useKRNL();

const authorizeAccount = async () => {
  if (!embeddedWallet) return; // Connect wallet via Privy first

  if (!isAuthorized) {
    const success = await enableSmartAccount();
    // Account is now authorized for KRNL workflows
  }
};

Authorization Process:

1. User signs an EIP-7702 authorization message via Privy

2. Delegates specific permissions to the KRNL contract

3. Account gains smart account capabilities without deploying a new contract

4. Delegation is temporary and revocable

---

Execute KRNL Workflows

import { useKRNL, WorkflowStatusCode } from '@krnl/react-sdk';

const {
  executeWorkflow,
  executeWorkflowFromTemplate,
  resetSteps,
  isAuthorized,
  statusCode,
  error,
  steps,
  currentStep
} = useKRNL();

Execute a Basic Workflow

const runWorkflow = async () => {
  if (!isAuthorized) return;

  resetSteps(); // Clear previous workflow state

  const workflowDSL = {
    action: "transfer_tokens",
    params: { from: "0x123...", to: "0x456...", amount: "1000" }
  };

  const result = await executeWorkflow(workflowDSL);

  if (statusCode === WorkflowStatusCode.SUCCESS) {
    // ✅ Workflow completed successfully
  } else if (error) {
    // ❌ Handle errors
  }
};

Execute Workflow From Template

const runTemplateWorkflow = async () => {
  if (!isAuthorized) return;

  const template = {
    action: "transfer_tokens",
    params: {
      from: "{{SENDER_ADDRESS}}",
      to: "{{RECIPIENT_ADDRESS}}",
      amount: "{{AMOUNT}}"
    }
  };

  const params = {
    "{{SENDER_ADDRESS}}": "0x123...",
    "{{RECIPIENT_ADDRESS}}": "0x456...",
    "{{AMOUNT}}": "1000"
  };

  await executeWorkflowFromTemplate(template, params);

  // Monitor progress via steps, currentStep, and statusCode
};

---

Workflow Execution Flow

1. Submit to KRNL: DSL sent to nodes → PENDING

2. Admission Control: Workflow validated & queued → PENDING

3. Processing: Execution off-chain → PROCESSING

4. Completion: Success or failure → SUCCESS / FAILED / ERROR_CODES

5. On-chain Settlement: Results trigger transaction intent on-chain

6. Confirmation: Transaction hash & block number returned

---

Step-by-Step Progress Tracking

Steps Array Structure

interface WorkflowStep {
  id: number;             // Step ID (1, 2, 3)
  title: string;          // Step name
  status: 'pending' | 'running' | 'completed' | 'error';
  error?: string;         // If error occurs
  result?: any;           // Step result
}

Workflow Steps

1. Submit: Send workflow to KRNL node

2. Execute: Off-chain execution (PENDING → PROCESSING → SUCCESS)

3. On-chain Status: Monitor blockchain transaction confirmation

Current Step Values

• 0 = Idle

• 1 = Submitting workflow

• 2 = Executing workflow

• 3 = Monitoring on-chain transaction

---

Workflow Status Codes

Code	Meaning
0	PENDING – Workflow queued
1	PROCESSING – Workflow executing
2	SUCCESS – Workflow completed successfully
3	FAILED – Execution failed
4	INTENT_NOT_FOUND – Intent ID missing
5	WORKFLOW_NOT_FOUND – Workflow definition missing
6	INVALID – Invalid request

---

useKRNL() Hook

const {
  // Status
  isAuthorized,
  isAuthenticated,
  embeddedWallet,

  // Workflow Execution
  executeWorkflow,
  executeWorkflowFromTemplate,

  // Step Management
  resetSteps,
  initializeSteps,
  steps,
  currentStep,

  // Account Management
  enableSmartAccount,

  // State
  statusCode,
  error
} = useKRNL();

---

Template Utilities

import {
  WorkflowObject,
  WorkflowValue,
  processWorkflowTemplate,
  validateTemplateParameters,
  WorkflowStatusCode,
  ERROR_MESSAGES
} from '@krnl/react-sdk';

type WorkflowValue = string | number | boolean | `0x${string}` | WorkflowObject | WorkflowValue[];

Processing Templates

const template: WorkflowObject = { action: "{{ACTION}}", amount: "{{AMOUNT}}" };
const params = { "{{ACTION}}": "transfer", "{{AMOUNT}}": "1000" };
const processed = processWorkflowTemplate(template, params);

Development

# Install dependencies
npm install

# Build SDK
npm run build

# Run tests
npm test

# Type checking
npm run type-check