# 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:

```tsx
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:

```jsx
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.

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

   ```

   Example:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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.

   ```tsx
   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:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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:

```tsx
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:

```tsx
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:

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

```

1. Number Input:

```jsx
{
    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:

```jsx
{
    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:

```jsx
{
    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:

```jsx
{
    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.

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

   ```

   Example:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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.

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

   ```

   Example:

   ```jsx
   {
       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:

```tsx
interface ActionError {
    message: string;
}

```

Example usage:

```jsx
{
    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:

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

```

Example usage:

```jsx
{
    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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://blinkz.gitbook.io/blinkz/sdk/blinkz-actions-sdk/core-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.