# zkLink Nova Actions & Intent URL SDK
## Overview
**Action:** An Action is a standardized API that accepts parameters and returns signable transaction or message, enabling specific on-chain or off-chain activities. Actions allow developers to abstract their services to meet user potential intents, while maximizing flexibility by allowing anyone to set parameters when creating an Intent URL.

**Intent URL**: An Intent URL is a shareable link that serves as the interface of an Action. It can be generated by anyone who wants to promote specific blockchain activities. Based on the Action, it enables blockchain interaction from any web interface capable of displaying a URL, significantly lowering the barrier to blockchain interaction.

## Role
**Developer:** Responsible for developing Actions. Developers implement the Action specifications and submit the code to the repository. zkLink official team will review and register the Actions.

**Intent Creator:** Responsible for creating Intent URLs. Creator select a registered Action, configure it in easy to use dashboard, generate and share it to let user engage with it.

**User:** The person using the Intent URL.

# Getting Started

## Develop an Action

We provide a toolkit for creating actions that fulfill users' intents across Nova and Nova's connected chains. An action could consist of multiple transactions on multiple chains, interacting with multiple DApps. We abstracts the complexity of multi-chain transactions away, allowing you to focus solely on the service you would like to provide.

Our framework includes a registration process. Once you develop an action and register it in our repository, our server automatically routes requests to your action.

Here is the workflow.


### 0. Prepare

The toolkit is based on Node.js and NestJS framework, so make sure you have already installed Node.js before developing an action.

You must develop your action under our repository. To get started, clone the repository:

git clone [e-mail]:zkLinkProtocol/zklink-intent-url.git

Then install the dependencies:

npm install

Build the project at first to make sure everything is OK:

npm run build

From now you can start to develop your action.

### 1. Initialize

All Action implementations must be in the `libs` directory as a nest sub-project. So you must initiate your action project here. Run the following command:

cd lib
npx nest g library my-action

You will see a new directory named `my-action` in the `libs` directory. This directory contains the basic structure of a nest project.

### 2. Implement

We provide an abstract class that you must extend to implement your action.

The action is described by the `Action` class defined in [`action.dto.ts`](../src/common/dto/action.dto.ts). The abstract class is structured as follows:

type ActionTransactionParams = { [key: string]: string };

abstract class Action {
  abstract getMetadata(): Promise<ActionMetadata>;

  abstract generateTransaction(
    params: ActionTransactionParams,
  ): Promise<GeneratedTransaction>;
}

The `getMetadata` method returns metadata (`ActionMetadata`) that describes the action for display on the frontend. The `generateTransaction` method is responsible for constructing transactions. When a user confirms the action in intent url page, this method executes in the background to construct and return the transaction, which will subsequently be sent to the blockchain.

To implement this functionality, you must extend the `Action` abstract class based on your specific business logic.

class MyAction extends Action {
  async getMetadata(): Promise<ActionMetadata> {
    return {
      title: 'An Action Example',
      description: 'This is a simple action',

      description: 'Support the works you love',
      logo: '',
      networks: [
        {
          name: 'zkLink Nova',
          chainId: '810180',,
          contractAddress: '0x',
        },
      ],
      dApp: { name: 'An Action Example' },
      intent: {
        components: [
          {
            name: 'value',
            label: 'Amount',
            desc: 'The amount to sponsor',
            type: 'input',
            regex: '^[0-9]+$',
            regexDesc: 'Must be a number',
          },
         {
            name: 'recipient',
            label: 'Recipient',
            desc: 'The address that is sponsored',
            type: 'input',
            regex: '^0x[a-fA-F0-9]{40}$',
            regexDesc: 'Address',
          },
        ]
      },
    };
  }

  async generateTransaction(
    params: ActionTransactionParams,
  ): Promise<GeneratedTransaction> {
    return {
      tx: {
        value: BigInt(params.value),
        to: params.recipient,
      },
      // tell the render whether to send the transaction
      shouldSend: true,
    };
  }
}

It must be noticeable that the `intent` field describes the parameters that the intent creator or user can set in Intent URL, which will be displayed on the frontend.

### 3. Register

The last step for implementation is to register your action into our framework. You need to put your action instance into the registered action list in [`registeredActions`](../src/modules/action/registeredActions.ts).

import * as myAction from '@action/my-action';

export const registeredActions = [
  { key: 'novaswap', module: novaSwapAction.default },
  { key: 'buyMeACoffee', module: buyMeACoffeeAction.default },
  { key: 'myAction', module: myAction.default },
];

Our framework will register your Action implementation into the routing system. When a request arrives, it will locate your Action implementation based on your ID, pass in the parameters, and execute your business logic, ultimately generating a transaction for the user to sign and send.

### 4. Submit

After implementing your action, you need to submit a PR to the repository. We will review your code and consider whether to accept it.

## Example

The [buy-me-a-coffee](../libs/buy-me-a-coffee/) and [`novaswap`](../libs/novaswap/) Actions are built-in by zkLink official, which are good examples for you to learn how to implement an action.

## Tips and Tricks

### Keep it Simple

Our Action interface offers flexibility, allowing you to implement TypeScript business logic according to your needs. However, please ensure that your logic implementation remains as straightforward as possible.

### Use Industry-Standard Libraries

While you may introduce new dependencies, please ensure that you use industry-standard libraries.

### Minimize External Dependencies

You are permitted to reference external API services with caution. During the code review process, we will consider the impact on our business operations. The preferred approach is to avoid relying on external API services and, if necessary, to only obtain essential data from the zkLink Nova blockchain.

### Prioritize Security

Security is our top priority. Minimizing dependencies and external services enhances the robustness of our service. This will be a key criterion in our evaluation of your Action implementation.

### Verify your Action with Swagger

After completing an Action, you should test it to ensure it works properly. Our code acts as SWAGGER, allowing you to test whether your Action functions correctly within our API on this page. The process is as follows:

Start the project using the following command:

npm run start

At this point, you can access SWAGGER through `localhost:4101`. You should ensure the proper functioning of three APIs:

- `/api/actions`: This should include the description of your Action.
- `/api/actions/{id}`: Upon entering the corresponding ID, it should return the description of your Action.
- `/api/actions/{id}/transaction`: Upon entering the corresponding ID and the required parameters of the Action, it should generate the desired transaction.

When you encounter issues, you can observe the logs in the command line console to pinpoint the problem. This is the most intuitive troubleshooting method.

## FAQs

### 1. How do I update an action?

To update an existing action, follow these steps:

1. Modify Your Code: Make the necessary changes to your action implementation.
Test Thoroughly: Ensure all changes are thoroughly tested, including unit, integration, and manual tests.
2. Submit a Pull Request (PR): Create a PR with a detailed description of the changes and the reasons for the update.
3. Code Review: The zkLink team will review your PR for quality, security, and compliance with standards.
Approval and Registration: Once approved, your updated action will be registered and available for use.

### 2. What if my action requires external data?

Minimize reliance on external APIs. If necessary, use them cautiously and ensure they do not impact business operations.

### 3. What is the submission and review process for new actions?

1. Submit a PR: Follow the repository's guidelines for submitting a pull request.
2. Code Review: Your code will be reviewed for quality, security, and compliance with standards.
3. Approval: Once approved, your action will be registered and available for use.

## Glossary

1. Action: A standardized API implementation for generating transactions.
2. Intent URL: A shareable link for executing actions on the zkLink Nova network.
3. Swagger: A tool for testing and verifying APIs.