Sherry SDK

A powerful TypeScript SDK for building interactive Web3 mini-apps that can be embedded within social media posts and platforms. Transform any post into an interactive dApp that allows users to swap tokens, vote on proposals, mint NFTs, and more - all without leaving their social media feed.

Features

• Multi-chain Support: Ethereum, Avalanche, Celo, Base, and more
• Action Types:
  • Transfer actions for token transfers
  • Blockchain actions for smart contract interactions
  • Dynamic actions for server-side logic
  • Nested action flows for multi-step processes
• Built-in Validation: Comprehensive type checking and security validation
• TypeScript First: Full type safety with comprehensive definitions
• Cross-chain Support: Enable transactions across multiple blockchains
• Rich Parameters: Select dropdowns, radio buttons, text inputs, and file uploads
• Developer Tools: Built-in debugging and validation utilities

Installation

npm install @sherrylinks/sdk viem
# or
yarn add @sherrylinks/sdk viem

Note: viem is a peer dependency and must be installed separately.

Quick Start

Basic Transfer Action

import { createMetadata, Metadata } from '@sherrylinks/sdk';

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

const validatedMetadata = createMetadata(metadata);

Blockchain Action

import { createMetadata, Metadata } from '@sherrylinks/sdk';

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

const validatedMetadata = createMetadata(metadata);

Action Types

Transfer Actions

Send native tokens with customizable parameters:

• Fixed or user-configurable amounts
• Support for all major chains
• Built-in validation

Blockchain Actions

Direct smart contract interactions:

• Call any contract function
• Rich parameter configuration
• Support for all Solidity types
• Automatic ABI validation

HTTP Actions

Server-side processing with REST endpoints:

• Custom business logic
• Form submissions
• External API integrations
• Rich parameter types (select, radio, textarea, file upload)

Dynamic Actions

Advanced server-side processing:

• Complex calculations
• Real-time data processing
• External service integrations

Action Flows

Multi-step interactive experiences:

• Conditional branching
• Decision points
• Progress tracking
• Completion states

Supported Chains

• Ethereum Mainnet
• Ethereum Sepolia (testnet)
• Avalanche C-Chain
• Avalanche Fuji (testnet)
• Celo Mainnet
• Celo Alfajores (testnet)
• Base Mainnet
• Base Sepolia (testnet)
• Mantle Mainnet
• Mantle Sepolia (testnet)

Validation

The SDK provides comprehensive validation:

import { validateMetadata } from '@sherrylinks/sdk';

const result = validateMetadata(metadata);

if (result.isValid) {
  console.log('Metadata is valid:', result.type);
} else {
  console.error('Validation errors:', result.errors);
}

Template Helpers

The SDK provides template helpers for common parameter types:

import { createParameter, PARAM_TEMPLATES } from '@sherrylinks/sdk';

const emailParam = createParameter(PARAM_TEMPLATES.EMAIL, {
  name: 'email',
  label: 'Your Email',
  required: true,
});

const tokenParam = createParameter(PARAM_TEMPLATES.TOKEN_SELECT, {
  name: 'token',
  label: 'Select Token',
  options: [
    { label: 'USDC', value: 'usdc' },
    { label: 'DAI', value: 'dai' },
  ],
});

API Reference

Core Functions

• createMetadata(metadata) - Validates and processes metadata
• validateMetadata(input) - Validates metadata and returns detailed results

Type Guards

• isBlockchainActionMetadata(action) - Type guard for blockchain actions
• isTransferAction(action) - Type guard for transfer actions
• isHttpAction(action) - Type guard for HTTP actions
• isActionFlow(obj) - Type guard for nested action flows

Parameter Helpers

• createParameter(template, customizations) - Helper for parameter creation
• PARAM_TEMPLATES - Library of predefined parameter templates

Development

# Install dependencies
yarn install

# Run tests
yarn test

# Build the package
yarn build

# Lint code
yarn lint

Examples

The SDK includes comprehensive examples in the src/examples directory:

• Basic transfer actions
• Smart contract interactions
• HTTP actions with forms
• Multi-step action flows

Resources

• Documentation - Complete guides and API reference
• Debugger Tool - Interactive testing environment
• Discord - Community support
• GitHub Issues - Bug reports and feature requests

Contributing

Contributions are welcome! Please submit a Pull Request.

1. Fork the repository
2. Create a feature branch from develop
3. Make your changes
4. Add tests if applicable
5. Open a Pull Request to the develop branch

License

MIT License - see the LICENSE file for details.

Links

• Sherry Platform - Live platform and mini-app gallery
• Documentation - Complete developer documentation
• npm Package - Package registry