Skip to main content

Action Parameters

Action parameters define the inputs users provide when executing actions. They control UI generation and data validation. All parameter objects share a common set of base properties and can include additional properties specific to their type.

Base Parameter Properties​

All parameter types extend from a base structure and include the following properties:

interface BaseParameter {
  name: string; // Unique identifier for the parameter.
  label: string; // User-friendly label displayed in the UI.
  type: string; // Specifies the input type (e.g., 'text', 'number', 'select').
  required?: boolean; // Whether the parameter is mandatory (default: false).
  description?: string; // Additional help text or guidance for the user.
  fixed?: boolean; // If true, the parameter's value is pre-set and not editable by the user.
  value?: any; // Default or fixed value for the parameter.
}
PropertyTypeRequiredDescription
namestring✅Unique parameter name/identifier.
labelstring✅User-friendly label for the UI.
typestring✅The specific type of the parameter.
requiredboolean❌Whether the field is mandatory.
descriptionstring❌Additional help text displayed to the user.
fixedboolean❌If true, the value is pre-defined and not user-editable.
valueany❌Default value or the fixed value if fixed is true.

Parameter Types​

Below are the specific parameter types available, each extending the BaseParameter properties with its own unique characteristics and additional fields.

Text-Based Parameters​

For inputs that expect textual data. This includes plain text, emails, URLs, and longer messages.

Interface:

interface TextBasedParameter extends BaseParameter {
  type:
    | 'text'
    | 'email'
    | 'url'
    | 'textarea'
    | 'string' // Generic string, often used with ABI types
    | 'bytes' // For byte strings, typically hex-encoded
    | Extract<AbiType, 'string' | 'bytes' | `bytes${number}`>;
  minLength?: number;
  maxLength?: number;
  pattern?: string; // Regular expression for validation.
}

Properties:

PropertyTypeDescription
minLengthnumberMinimum character length.
maxLengthnumberMaximum character length.
patternstringA regex pattern for input validation.

Examples:

  • Simple Text Input:

    {
      "name": "username",
      "label": "Username",
      "type": "text",
      "required": true,
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "Must be 3-20 alphanumeric characters or underscores."
    }

  • Email Input:

    {
      "name": "userEmail",
      "label": "Email Address",
      "type": "email",
      "required": true,
      "pattern": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$", // Example, often handled by UI
      "description": "Please enter a valid email address."
    }

  • Textarea for Longer Messages:

    {
      "name": "feedback",
      "label": "Your Feedback",
      "type": "textarea",
      "required": false,
      "maxLength": 500,
      "description": "Provide your comments (max 500 characters)."
    }

Number-Based Parameters​

For inputs that expect numerical data, including integers, decimals, and dates/times represented as timestamps.

Interface:

interface NumberBasedParameter extends BaseParameter {
  type: 'number' | 'datetime' | Extract<AbiType, `uint${string}` | `int${string}`>;
  min?: number; // Minimum allowed value.
  max?: number; // Maximum allowed value.
  pattern?: string; // Regular expression (less common for numbers but available).
}

Properties:

PropertyTypeDescription
minnumberMinimum numerical value (inclusive).
maxnumberMaximum numerical value (inclusive).
patternstringA regex pattern for validating the number format.

Examples:

  • Decimal Number Input:

    {
      "name": "amount",
      "label": "Amount",
      "type": "number",
      "required": true,
      "min": 0.01,
      "max": 1000,
      "description": "Enter an amount between 0.01 and 1000."
    }

  • Integer (ABI uint256) Input:

    {
      "name": "tokenId",
      "label": "Token ID",
      "type": "uint256", // Or 'number' if not strictly for ABI
      "required": true,
      "min": 0,
      "pattern": "^[0-9]+$",
      "description": "Enter the NFT Token ID (non-negative integer)."
    }

  • Datetime Input (Unix Timestamp):

    {
      "name": "expirationDate",
      "label": "Expiration Date",
      "type": "datetime",
      "required": true,
      "description": "Select the expiration date and time."
    }

Address Parameters​

For inputs that expect blockchain addresses (e.g., Ethereum addresses).

Interface:

interface AddressParameter extends BaseParameter {
  type: 'address' | Extract<AbiType, 'address'>;
  pattern?: string; // Regular expression for custom address validation.
}

Properties:

PropertyTypeDescription
patternstringA regex pattern for validating the address format. Defaults to Ethereum address format if not provided.

Example:

{
  "name": "recipientAddress",
  "label": "Recipient Address",
  "type": "address",
  "required": true,
  "pattern": "^0x[a-fA-F0-9]{40}$", // Standard Ethereum address pattern
  "description": "Enter a valid Ethereum wallet address."
}

Boolean Parameters​

For inputs that represent a true/false or yes/no choice, typically rendered as a checkbox.

Interface:

interface BooleanParameter extends BaseParameter {
  type: 'boolean' | Extract<AbiType, 'bool'>;
}

Properties: This parameter type uses only the BaseParameter properties.

Example:

{
  "name": "agreeToTerms",
  "label": "I agree to the terms and conditions",
  "type": "boolean",
  "required": true,
  "value": false // Default to unchecked
}

Select Parameters​

For inputs where the user chooses one option from a dropdown list.

Interface:

interface SelectOption {
  label: string; // Text displayed for the option.
  value: string | number | boolean; // Actual value of the option.
  description?: string; // Optional additional description for the option.
}

interface SelectParameter extends BaseParameter {
  type: 'select';
  options: SelectOption[];
}

Properties:

PropertyTypeDescription
optionsSelectOption[]An array of SelectOption objects to populate the dropdown.

Example:

{
  "name": "tokenChoice",
  "label": "Select Token",
  "type": "select",
  "required": true,
  "options": [
    { "label": "Ether (ETH)", "value": "0xETHAddress", "description": "Native currency" },
    { "label": "USD Coin (USDC)", "value": "0xUSDCAddress", "description": "Stablecoin" }
  ],
  "description": "Choose a token for the transaction."
}

Radio Parameters​

For inputs where the user chooses one option from a set of radio buttons.

Interface:

// Uses the same SelectOption interface as SelectParameter

interface RadioParameter extends BaseParameter {
  type: 'radio';
  options: SelectOption[];
}

Properties:

PropertyTypeDescription
optionsSelectOption[]An array of SelectOption objects to create radio buttons.

Example:

{
  "name": "priorityLevel",
  "label": "Priority Level",
  "type": "radio",
  "required": true,
  "value": "medium", // Default selected radio option
  "options": [
    { "label": "Low", "value": "low", "description": "Standard processing time" },
    { "label": "Medium", "value": "medium", "description": "Faster processing" },
    { "label": "High", "value": "high", "description": "Immediate processing" }
  ]
}

File Parameters​

For inputs that allow users to upload files.

Interface:

interface FileParameter extends BaseParameter {
  type: 'file';
  accept?: string; // Comma-separated string of accepted file types (e.g., "application/pdf,image/jpeg").
  maxSize?: number; // Maximum file size in bytes.
  multiple?: boolean; // If true, allows multiple file selection.
}

Properties:

PropertyTypeDescription
acceptstringMIME types or extensions (e.g., image/png, .pdf).
maxSizenumberMaximum file size in bytes.
multiplebooleanAllows selection of multiple files if true.

Example:

{
  "name": "documentUpload",
  "label": "Upload Document",
  "type": "file",
  "required": true,
  "accept": "application/pdf,.docx",
  "maxSize": 5242880, // 5MB
  "multiple": false,
  "description": "Upload your document in PDF or DOCX format (max 5MB)."
}

Image Parameters​

A specialized file input for uploading images, with additional properties for image-specific validation.

Interface:

interface ImageParameter extends BaseParameter {
  type: 'image';
  accept?: string; // Accepted image types (e.g., "image/jpeg,image/png").
  maxSize?: number; // Maximum file size in bytes.
  multiple?: boolean; // If true, allows multiple image selection.
  maxWidth?: number; // Maximum image width in pixels.
  maxHeight?: number; // Maximum image height in pixels.
  aspectRatio?: string; // Desired aspect ratio (e.g., "16:9", "1:1").
}

Properties:

PropertyTypeDescription
acceptstringMIME types for images (e.g., image/jpeg, image/png).
maxSizenumberMaximum image file size in bytes.
multiplebooleanAllows selection of multiple images if true.
maxWidthnumberMaximum allowed width of the image in pixels.
maxHeightnumberMaximum allowed height of the image in pixels.
aspectRatiostringEnforces a specific aspect ratio (e.g., "16:9", "4:3", "1:1").

Example:

{
  "name": "profilePicture",
  "label": "Profile Picture",
  "type": "image",
  "required": false,
  "accept": "image/jpeg,image/png",
  "maxSize": 2097152, // 2MB
  "maxWidth": 800,
  "maxHeight": 800,
  "aspectRatio": "1:1",
  "description": "Upload a square profile picture (JPG or PNG, max 2MB, 800x800px)."
}

Validation Properties​

Validation properties like minLength, maxLength, min, max, pattern, required, accept, maxSize, etc., are defined within each parameter type above. Ensure that user inputs meet these criteria for successful action execution. The UI will typically provide immediate feedback based on these validation rules.

Best Practices​

1. Parameter Order​

For BlockchainAction, parameters must be in the same order as the ABI function inputs:

// ABI function: transfer(address to, uint256 amount)
params: [
  // First parameter: 'to' address
  {
    name: 'to',
    label: 'Recipient',
    type: 'address',
    required: true,
  },
  // Second parameter: 'amount'
  {
    name: 'amount',
    label: 'Amount',
    type: 'uint256',
    required: true,
  },
];

2. User-Friendly Labels​

Use clear, descriptive labels:

// Good
{
  name: 'spender',
  label: 'Contract to Approve',
  description: 'The contract that will spend your tokens'
}

// Avoid
{
  name: 'spender',
  label: 'Spender'  // Too technical
}

3. Provide Helpful Descriptions​

{
  name: 'slippage',
  label: 'Slippage Tolerance',
  type: 'number',
  description: 'Maximum price difference you\'re willing to accept (0.5% recommended)',
  value: 0.5,
  min: 0.1,
  max: 5.0
}

4. Use Templates When Possible​

// Use templates for consistency
createParameter(PARAM_TEMPLATES.ADDRESS, {
  name: 'recipient',
  label: 'Send To'
});

// Instead of manually defining
{
  name: 'recipient',
  label: 'Send To',
  type: 'address',
  required: true,
  pattern: '^0x[a-fA-F0-9]{40}'
}

5. Validate User Input​

{
  name: 'tokenAmount',
  label: 'Token Amount',
  type: 'number',
  required: true,
  min: 0.000001,      // Minimum viable amount
  max: 1000000,       // Reasonable maximum
  description: 'Amount must be between 0.000001 and 1,000,000'
}

For select/radio parameters, organize options logically:

{
  name: 'network',
  label: 'Network',
  type: 'select',
  required: true,
  options: [
    // Mainnets first
    { label: 'Ethereum Mainnet', value: 1 },
    { label: 'Avalanche C-Chain', value: 43114 },
    { label: 'Celo Mainnet', value: 42220 },
    // Then testnets
    { label: 'Avalanche Fuji (Testnet)', value: 43113 },
    { label: 'Celo Alfajores (Testnet)', value: 44787 }
  ]
}

Parameter Examples by Use Case​

Token Transfer​

const transferParams = [
  createParameter(PARAM_TEMPLATES.ADDRESS, {
    name: 'to',
    label: 'Recipient Address',
  }),
  createParameter(PARAM_TEMPLATES.TOKEN_AMOUNT, {
    name: 'amount',
    label: 'Amount to Send',
    min: 0.000001,
  }),
];

NFT Minting​

const mintParams = [
  createParameter(PARAM_TEMPLATES.ADDRESS, {
    name: 'to',
    label: 'Mint To Address',
    value: 'sender', // Default to current user
  }),
  {
    name: 'quantity',
    label: 'Quantity',
    type: 'select',
    required: true,
    options: [
      { label: '1 NFT', value: 1 },
      { label: '3 NFTs', value: 3 },
      { label: '5 NFTs', value: 5 },
    ],
  },
];

DAO Voting​

const voteParams = [
  {
    name: 'proposalId',
    label: 'Proposal ID',
    type: 'uint256', // or 'number'
    required: true,
    description: 'The ID of the proposal to vote on.',
  },
  {
    name: 'support',
    label: 'Your Vote',
    type: 'radio',
    required: true,
    options: [
      { label: 'Yes - Support this proposal', value: true },
      { label: 'No - Oppose this proposal', value: false },
    ],
    description: 'Cast your vote for or against the proposal.',
  },
];

API Form​

const formParams = [
  {
    name: 'email',
    label: 'Email Address',
    type: 'email',
    required: true,
    description: 'Please enter your email.',
  },
  {
    name: 'feedback',
    label: 'Your Feedback',
    type: 'textarea',
    required: true,
    maxLength: 1000,
    description: 'Tell us what you think (max 1000 characters).',
  },
  {
    name: 'rating',
    label: 'Rating',
    type: 'select',
    required: true,
    options: [
      { label: '1 - Poor', value: 1 },
      { label: '2 - Fair', value: 2 },
      { label: '3 - Good', value: 3 },
      { label: '4 - Very Good', value: 4 },
      { label: '5 - Excellent', value: 5 },
    ],
    description: 'Rate your experience.',
  },
];

For more examples and advanced parameter configurations, see the Action Types documentation.