Core Concepts

1.4.1 Action Structure

An Action is the fundamental building block in the Actions specification. It represents a complete, self-contained blockchain interaction that can be embedded in various Web2 contexts. The Action structure is defined by the following TypeScript interface:

interface Action {
    title: string;
    icon: string;
    description: string;
    label: string;
    links?: LinkedAction[];
    error?: ActionError;
}

Let's break down each field:

1. title: A concise, user-friendly title for the action. This should clearly indicate the purpose of the action, e.g., "Send ETH", "Mint NFT", "Stake Tokens".

2. icon: An absolute HTTPS URL pointing to an icon image. This image should be in SVG, PNG, or WebP format. The icon visually represents the action and should be recognizable at various sizes.

3. description: A brief explanation of what the action does. This provides context to the user and should be clear enough for someone unfamiliar with blockchain technology to understand.

4. label: The text that will appear on the action button or UI element. It should be concise and action-oriented, e.g., "Send", "Mint", "Stake".

5. links: An optional array of LinkedAction objects. These represent subsequent actions or steps that can be taken after the main action is completed. This allows for the creation of multi-step or branching interactions.

6. error: An optional ActionError object that defines how errors should be presented to the user if something goes wrong during the action execution.

Example of a basic Action structure:

const simpleAction = {
    title: "Donate to Charity",
    icon: "<https://example.com/charity-icon.svg>",
    description: "Send a donation in ETH to our selected charity",
    label: "Donate Now",
    links: [
        // LinkedActions would go here
    ],
    error: {
        message: "Unable to process donation. Please try again later."
    }
};

1.4.2 Linked Action Types

Linked Actions are a powerful feature of the Actions specification, allowing for the creation of complex, multi-step blockchain interactions. There are several types of Linked Actions, each serving a different purpose:

1. Link Action

   A simple hyperlink to a specified URL. This is useful for directing users to external resources or documentation.

   interface LinkAction extends LinkedActionBase {
       type: 'link';
       href: string;
   }
   

   Example:

   {
       type: 'link',
       label: 'Learn More',
       href: '<https://example.com/about-our-charity>'
   }
   

2. Reference Action

   References another Action by its Content Identifier (CID). This allows for the creation of modular, reusable Actions.

   interface ReferenceAction extends LinkedActionBase {
       type: 'reference-action';
       cid: string;
   }
   

   Example:

   {
       type: 'reference-action',
       label: 'View Transaction History',
       cid: 'QmX...', // IPFS CID of another Action
   }
   

3. Transaction Action (tx)

   Represents a single blockchain transaction. This is used for interacting with smart contracts or sending transactions.

   interface TxAction extends LinkedActionBase {
       type: 'tx';
       chainId: number;
       txData: {
           address: string;
           abi: string;
           parameters: (TypedActionParameter | ReferencedParameter)[];
           value?: string;
       };
       success: ActionSuccessResponse;
       error: ActionError;
   }
   

   Example:

   {
       type: 'tx',
       label: 'Approve Token Spend',
       chainId: 1, // Ethereum Mainnet
       txData: {
           address: '0x...', // Token contract address
           abi: 'function approve(address spender, uint256 amount) returns (bool)',
           parameters: [
               { type: 'constant', id: 'spenderAddress', value: '0x...' },
               { type: 'constant', id: 'approvalAmount', value: '1000000000000000000' }
           ]
       },
       success: {
           message: 'Approval successful'
       },
       error: {
           message: 'Approval failed. Please try again.'
       }
   }
   

4. Multi-Transaction Action (tx-multi)

   Represents multiple blockchain transactions that are executed in sequence or parallel.

   interface TxMultiAction extends LinkedActionBase {
       type: 'tx-multi';
       chainId: number;
       txData: Array<{
           address: string;
           abi: string;
           parameters: (TypedActionParameter | ReferencedParameter)[];
           value?: string;
       }>;
       success: ActionSuccessResponse;
       error: ActionError;
       displayConfig: {
           displayMode: 'combined' | 'sequential';
           renderedTxIndex?: number;
       };
   }
   

   Example:

   {
       type: 'tx-multi',
       label: 'Stake Tokens',
       chainId: 1,
       txData: [
           {
               address: '0x...', // Token contract
               abi: 'function approve(address spender, uint256 amount) returns (bool)',
               parameters: [/* ... */]
           },
           {
               address: '0x...', // Staking contract
               abi: 'function stake(uint256 amount)',
               parameters: [/* ... */]
           }
       ],
       success: {
           message: 'Tokens staked successfully'
       },
       error: {
           message: 'Staking failed. Please try again.'
       },
       displayConfig: {
           displayMode: 'sequential'
       }
   }
   

5. Transfer Action

   Represents a native currency transfer action, such as sending ETH.

   interface TransferAction extends LinkedActionBase {
       type: 'transfer-action';
       address: TypedActionParameter | ReferencedParameter;
       value: string;
       success: ActionSuccessResponse;
       error: ActionError;
   }
   

   Example:

   {
       type: 'transfer-action',
       label: 'Donate 0.1 ETH',
       address: {
           type: 'constant',
           id: 'charityAddress',
           value: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
       },
       value: '100000000000000000', // 0.1 ETH in wei
       success: {
           message: 'Donation successful. Thank you!'
       },
       error: {
           message: 'Donation failed. Please try again.'
       }
   }
   

These Linked Action types provide flexibility in creating complex blockchain interactions while maintaining a standardized structure.

1.4.3 Action Inputs

Action Inputs are a crucial part of the Actions specification, allowing for dynamic and interactive blockchain interactions. They define how data is collected from users or the environment to be used in the execution of an Action.

The basic structure of an Action Input is defined by the following interface:

interface ActionInput {
    type: ActionInputType;
    id: string;
    scope: InputScope;
    label: string;
    required?: boolean;
    pattern?: string;
}

Let's examine each field in detail:

1. type: Defines the type of input field. It can be one of the following:

   • 'text': For free-form text input

   • 'number': For numerical input

   • 'radio': For selecting one option from a list

   • 'select': For dropdown selection

2. id: A unique identifier for the input. This is used to reference the input value in other parts of the Action.

3. scope: Defines where the input originates. It can be either:

   • 'USER': The input should be provided by the user

   • 'GLOBAL': The input is handled globally by the client (e.g., user's wallet address)

4. label: A user-friendly label for the input field.

5. required: An optional boolean indicating whether the input is mandatory.

6. pattern: An optional string representing a regular expression pattern for input validation.

For selectable inputs (radio and select types), an extended interface is used:

interface ActionInputSelectable extends Omit<ActionInput, 'scope'> {
    scope: Extract<InputScope, 'USER'>;
    options: Array<{
        label: string;
        value: string;
        selected?: boolean;
    }>;
}

This adds an options array to define the selectable choices.

Examples of different input types:

1. Text Input:

{
    type: 'text',
    id: 'recipientName',
    scope: 'USER',
    label: 'Recipient Name',
    required: true
}

1. Number Input:

{
    type: 'number',
    id: 'donationAmount',
    scope: 'USER',
    label: 'Donation Amount (ETH)',
    required: true,
    pattern: '^[0-9]*(\\.[0-9]{1,18})?$' // Allow up to 18 decimal places
}

1. Radio Input:

{
    type: 'radio',
    id: 'donationFrequency',
    scope: 'USER',
    label: 'Donation Frequency',
    options: [
        { label: 'One-time', value: 'once', selected: true },
        { label: 'Monthly', value: 'monthly' },
        { label: 'Yearly', value: 'yearly' }
    ]
}

1. Select Input:

{
    type: 'select',
    id: 'tokenType',
    scope: 'USER',
    label: 'Select Token',
    options: [
        { label: 'ETH', value: 'eth', selected: true },
        { label: 'DAI', value: 'dai' },
        { label: 'USDC', value: 'usdc' }
    ]
}

1. Global Input:

{
    type: 'text',
    id: 'userAddress',
    scope: 'GLOBAL',
    label: 'Your Wallet Address'
}

When designing Actions, it's important to consider the user experience and only request necessary information. Use appropriate input types and validation to ensure data integrity and improve user interaction.

1.4.4 Typed Action Parameters

Typed Action Parameters are used to specify the nature and origin of data used in actions. They provide a flexible way to define how values are obtained and used within an Action. There are five types of Action Parameters:

1. Constant Parameter

   Represents fixed values that don't require user input.

   interface ConstantParameter {
       type: 'constant';
       id: string;
       value: string | number | boolean | string[] | number[] | boolean[];
   }
   

   Example:

   {
       type: 'constant',
       id: 'contractAddress',
       value: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e'
   }
   

2. Action Input

   Represents user-provided input, as defined in the previous section.

3. Computed Input

   Derived from other inputs through simple arithmetic operations.

   interface ComputedInput {
       type: 'computed';
       id: string;
       operation: 'add' | 'multiply';
       values: TypedActionParameter[];
   }
   

   Example:

   {
       type: 'computed',
       id: 'totalAmount',
       operation: 'multiply',
       values: [
           { type: 'constant', id: 'baseAmount', value: 100 },
           { type: 'action-input', id: 'userMultiplier' }
       ]
   }
   

4. Contract Read Input

   Used to fetch data from a smart contract.

   interface ContractReadInput {
       type: 'contract-read';
       id: string;
       address: string;
       abi: string;
       parameters: TypedActionParameter[];
       returnValueIndex?: number;
   }
   

   Example:

   {
       type: 'contract-read',
       id: 'userBalance',
       address: '0x742d35Cc6634C0532925a3b844Bc454e4438f44e',
       abi: 'function balanceOf(address account) view returns (uint256)',
       parameters: [
           { type: 'global', id: 'userAddress' }
       ]
   }
   

5. Referenced Parameter

   Allows reuse of parameters across different parts of an action.

   interface ReferencedParameter {
       type: 'referenced';
       refParameterId: string;
   }
   

   Example:

   {
       type: 'referenced',
       refParameterId: 'userBalance'
   }
   

These Typed Action Parameters provide a powerful way to define and manipulate data within Actions, allowing for dynamic and context-aware blockchain interactions.

1.4.5 Error Handling and Success Responses

Proper error handling and success feedback are crucial for providing a good user experience in blockchain interactions. The Actions specification includes standardized ways to handle errors and communicate successful execution.

Error Handling

The ActionError interface is used to define how errors should be presented to the user:

interface ActionError {
    message: string;
}

Example usage:

{
    error: {
        message: "Transaction failed due to insufficient funds. Please check your balance and try again."
    }
}

When implementing Actions, it's important to provide clear and actionable error messages. Consider different scenarios that might cause failures (e.g., network issues, insufficient funds, smart contract errors) and provide appropriate guidance to the user.

Success Responses

The ActionSuccessResponse interface is used to communicate successful execution of an action:

interface ActionSuccessResponse {
    message: string;
    nextActionCid?: string;
}

Example usage:

{
    success: {
        message: "Your donation of 0.1 ETH was successful. Thank you for your generosity!",
        nextActionCid: "QmX..." // Optional: CID of a follow-up action
    }
}

The nextActionCid field allows for chaining of actions, enabling more complex multi-step interactions.

When designing success responses:

• Provide clear confirmation of what was accomplished

• Include relevant details (e.g., transaction amount, recipient)

• If applicable, guide the user on what they can do next

By implementing robust error handling and informative success responses, you can create Actions that are more user-friendly and provide a smoother interaction with blockchain functionality.