@relayerfi/action-kit

TypeScript SDK for defining on-chain actions as structured metadata. Part of the Relayer infrastructure stack.

Action Kit lets integrators declare what a widget does (transfer tokens, call a contract, run a multi-step flow) without coupling to any rendering layer. The metadata is consumed by @relayerfi/widget-kit-core and @relayerfi/widget-kit-react to produce interactive UI.

Install

pnpm add @relayerfi/action-kit viem

viem is a required peer dependency.

Usage

Transfer Action

import { createMetadata, type Metadata } from '@relayerfi/action-kit';

const metadata: Metadata = {
  url: 'https://myapp.example',
  icon: 'https://example.com/icon.png',
  title: 'Send AVAX',
  description: 'Transfer 0.1 AVAX',
  actions: [
    {
      type: 'transfer',
      label: 'Send 0.1 AVAX',
      to: '0x1234...5678',
      amount: 0.1,
      chains: { source: 43114 },
    },
  ],
};

const validated = createMetadata(metadata);

Blockchain Action (Contract Call)

const metadata: Metadata = {
  url: 'https://myapp.example',
  icon: 'https://example.com/icon.png',
  title: 'Approve USDC',
  description: 'Approve spender',
  actions: [
    {
      type: 'blockchain',
      label: 'Approve',
      address: '0xA0b86a33E6417C8D7648D5b1D6fF0F6dB6c15b2a',
      abi: [/* ERC-20 approve ABI */],
      functionName: 'approve',
      chains: { source: 1 },
      params: [
        { name: 'spender', type: 'address', value: '0x...', fixed: true },
        { name: 'amount', type: 'number', required: true },
      ],
    },
  ],
};

Action Types

| Type | Purpose | |------|---------| | transfer | Native token or ERC-20 transfers | | blockchain | Smart contract read/write calls | | http | Server-side form submissions and API calls | | dynamic | Runtime-generated actions with server logic | | flow | Multi-step nested action workflows |

Validation

import { validateMetadata } from '@relayerfi/action-kit';

const result = validateMetadata(metadata);
if (!result.isValid) {
  console.error(result.errors);
}

Supported Chains

Ethereum, Avalanche, Base, Celo, Mantle (mainnets + testnets). See src/interface/chains.ts for the full list.

API

Core

• createMetadata(metadata) - Validate and process action metadata
• validateMetadata(input) - Validate with detailed error reporting

Type Guards

• isBlockchainActionMetadata(action)
• isTransferAction(action)
• isHttpAction(action)
• isActionFlow(obj)
• isDynamicAction(action)

Executors

• Executor - Base executor for proxy communication
• DynamicActionExecutor - Execute dynamic actions with server-side logic

Related Packages

| Package | Purpose | |---------|---------| | @relayerfi/widget-kit-core | Framework-agnostic runtime (directory, metadata fetching, security) | | @relayerfi/widget-kit-react | React components for rendering widgets |

License

MIT