Post Actions

This guide explains how to use Post Actions and how to implement custom ones.

Post Actions are contracts that extend the Lens Protocol functionality by allowing Accounts to execute actions on Posts.

Lens provides two built-in Post Actions:

It is also possible to create custom Post Actions to extend the functionality of the Lens Protocol.

You can configure one or more Post Actions when creating a Post.

The SimpleCollectAction allows a user to collect an ERC-721 NFT from a given post.

The Post author can configure the following parameters:

import { dateTime, evmAddress, uri } from "@lens-protocol/client";
const result = await post(sessionClient, {  contentUri: uri("lens://4f91ca…"),  actions: [    {      simpleCollect: {        collectLimit: 100,        endsAt: dateTime("2032-12-22T00:00:00Z"),      },    },  ],});

Lens includes a built-in TippingPostAction, which is enabled by default and allows an Account to tip the author of a Post using native GHO (GRASS on the Lens Testnet) or ERC20 token.

The TippingPostAction supports a referral scheme that lets you reward accounts or apps that helped surface the tipped Post.

A maximum of 20% of the tipped amount can be allocated to referrals, but only if they're explicitly included when the tip is sent.

Post Actions can use funds from either the Signer or the Lens Account to pay for tips or collects.

Let’s say a user tips the author of a Post with 100 GHO using the TippingPostAction.

Here's how the amount is split:

The user includes two referral recipients, fully allocating the maximum 20% referral fee between them:

From the remaining 98.5 GHO:

You can create Posts with custom Post Actions by specifying the action's contract address and encoded parameters. The Lens SDK provides the encodeKeyValuePairs utility to help encode parameters based on the action's metadata.

Consider a post action with the following metadata:

{  "__typename": "UnknownPostAction",  "address": "0x1234…",  "metadata": {    "authors": ["[email protected]", "[email protected]"],    "configureParams": [      {        "__typename": "KeyValuePair",        "key": "0x6bbaf20e3c4b9cd2bcb0a17bbe156c6fdaaeda4a64626e09a17f2283321a6f72",        "name": "lens.param.foo",        "type": "string"      }    ],    "description": "This is a sample action.",    "executeParams": [],    "id": "123e4567-e89b...",    "name": "SampleAction",    "setDisabledParams": [],    "source": "https://github.com/example/repo"  }}

To create a post with this post action, follow these steps:

import { evmAddress, uri } from "@lens-protocol/client";import { encodeKeyValuePairs } from "@lens-protocol/client/viem";
const encodedParams = encodeKeyValuePairs(  { "lens.param.foo": "bar" },  actionMetadata.configureParams,);

import { evmAddress, uri } from "@lens-protocol/client";
const result = await post(sessionClient, {  contentUri: uri("lens://4f91ca…"),  actions: [    {      unknown: {        address: evmAddress("0x1234…"),        params: encodedParams,      },    },  ],});

To execute a Post Action, follow these steps.

for (const action of post.actions) {  switch (action.__typename) {    case "SimpleCollectAction":      // The Post has a Simple Collect Action      break;
    case "UnknownAction":      // The Post has a Custom Post Action      break;  }}

{  "__typename": "SimpleCollectAction",  "payToCollect": {    "__typename": "PayToCollectConfig",    "price": {      "__typename": "Erc20Amount",      "asset": {        "__typename": "Erc20",        "name": "Wrapped GHO",        "symbol": "wGHO",        "contract": {          "__typename": "NetworkAddress",          "address": "0x1234…",          "chainId": 37111        },        "decimals": 18      },      "value": "42.42"    },    "referralShare": 5, // 5%    "recipients": [      {        "__typename": "RecipientPercent",        "address": "0x5678…",        "percent": 30 // 30%      },      {        "__typename": "RecipientPercent",        "address": "0x9abc…",        "percent": 70 // 70%      }    ]  },  "collectLimit": 100,  "endsAt": "2032-12-22T00:00:00Z",  "followerOnGraph": {    "__typename": "FollowerOn",    "globalGraph": true  },  "isImmutable": true}

import { postId } from "@lens-protocol/client";import { executePostAction } from "@lens-protocol/client/actions";
const result = await executePostAction(sessionClient, {  post: postId("42"),  action: {    simpleCollect: {      selected: true,    },  },});
if (result.isErr()) {  return console.error(result.error);}

import { postId, PaymentSource } from "@lens-protocol/client";import { executePostAction } from "@lens-protocol/client/actions";
const result = await executePostAction(sessionClient, {  post: postId("42"),  action: {    simpleCollect: {      selected: true,      paymentSource: PaymentSource.Signer,    },  },});
if (result.isErr()) {  return console.error(result.error);}

import { postId } from "@lens-protocol/client";import { executePostAction } from "@lens-protocol/client/actions";
const result = await executePostAction(sessionClient, {  post: postId("42"),  action: {    simpleCollect: {      selected: true,      referrals: [        {          address: "0x5678…",          percent: 30,        },        {          address: "0x9abc…",          percent: 70,        },      ],    },  },});
if (result.isErr()) {  return console.error(result.error);}

import { evmAddress, postId } from "@lens-protocol/client";import { executePostAction } from "@lens-protocol/client/actions";
const result = await executePostAction(sessionClient, {  post: postId("42"),  action: {    unknown: {      address: evmAddress("0x1234…"),      params: encodedParams,    },  },});
if (result.isErr()) {  return console.error(result.error);}

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const operation = await executePostAction(sessionClient, {  post: postId("42"),  action: {    // …  },});
if (operation.isErr()) {  return console.error(operation.error);}
switch (operation.value.__typename) {  case "InsufficientFunds":    // handle insufficient funds scenario    return console.log("Insufficient funds to perform the action");
  case "SignerErc20ApprovalRequired":    // handle ERC20 approval required scenario leveraging operation.value.amount: Erc20Amount    return console.log("Signer ERC20 approval required to perform the action");}
const result = await operation  .asyncAndThen(handleOperationWith(wallet))  .andThen(sessionClient.waitForTransaction);

The Lens Protocol provides a method to track which accounts have executed specific actions on a Post.

import { postId } from "@lens-protocol/client";import { fetchWhoExecutedActionOnPost } from "@lens-protocol/client/queries";
const result = await fetchWhoExecutedActionOnPost(client, {  post: postId("42"),});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<PostExecutedActions>const { items, pageInfo } = result.value;

You can add a Post Action to a Post at any time. For example, this can be useful to re-enable the Simple Collect Action on posts migrated from Lens Protocol v2 to v3.

import { evmAddress, postId } from "@lens-protocol/client";import { configurePostAction } from "@lens-protocol/client/actions";
const result = await configurePostAction(sessionClient, {  post: postId("42"),  params: {    simpleCollect: {      payToCollect: {        collectLimit: 100,        erc20: {          value: "100",          currency: evmAddress("0x5678…"),        },      },    },  },});

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await configurePostAction(sessionClient, {  post: postId("42"),  params: {    // …  },}).andThen(handleOperationWith(walletClient));

You can enable or disable a Post Action on a Post at any time, provided that the Post Action has already been configured for that Post. Post Actions can be configured either during Post creation or later, as described in the Configure Post Actions section above.

import { postId } from "@lens-protocol/client";import { enablePostAction } from "@lens-protocol/client/actions";
const result = await enablePostAction(sessionClient, {  post: postId("1234…"),  action: { simpleCollect: true },});

import { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await enablePostAction(sessionClient, {  post: postId("1234…"),  action: { simpleCollect: true },}).andThen(handleOperationWith(walletClient));

The Post Actions are defined by the IPostAction interface, which basically requires three functions, one to configure the action, one to execute it, and another to disable it.

interface IPostAction {    function configure(address originalMsgSender, address feed, uint256 postId, KeyValue[] calldata params)        external        returns (bytes memory);
    function execute(address originalMsgSender, address feed, uint256 postId, KeyValue[] calldata params)        external        returns (bytes memory);
    function setDisabled(        address originalMsgSender,        address feed,        uint256 postId,        bool isDisabled,        KeyValue[] calldata params    ) external returns (bytes memory);}

Before we dive into each of the functions from the IPostAction interface, we need to talk about the ActionHub.

The ActionHub is a special contract that acts as the entry point for every Action in the Lens Protocol.

The purpose of that is to help discovery of Actions, having a single point where all main Action-related events are emitted.

So, each function of the IPostAction interface must be only callable by ActionHub. For this, you can inherit base contracts like BasePostAction or OwnableMetadataBasedPostAction, which act as templates for your custom Post Action, applying the restrictions needed and including metadata and parameter details, so you do not need to worry about it.

With this context, you can now understand why the first param of every IPostAction function is originalMsgSender: this is the address that called the ActionHub originally, either to configure, execute, or disable an Action, given that msg.sender will always have the ActionHub address in the context of your Action contract.

Post Action deployment requires both metadata creation (to describe your action's parameters and behavior) and smart contract deployment. This ensures UIs can discover and properly interact with your action.

import { action } from "@lens-protocol/metadata";
const metadata = action({  name: "SimplePollVoteAction",  description:    "Allows users to cast a boolean vote (Yes/No) on a post with single-vote enforcement. Prevents double voting.",  authors: ["[email protected]"],  source: "https://github.com/lens-protocol/lens-post-action-boilerplate",  executeParams: [    {      key: "0xf1d961d1860db912f7c57ff7ec8e742cb92089b269e42c6fba52c85bcbdf21d8",      name: "lens.param.vote",      type: "bool",    },  ],});

import { storageClient } from "./storage-client";
const { uri } = await storageClient.uploadAsJson(metadata);
console.log(uri); // e.g., lens://4f91ca…

constructor(    address actionHub,    address owner,    string memory metadataUri) OwnableMetadataBasedPostAction(actionHub, owner, metadataUri) {}

The configuration of the Action is done through the configure function, which purpose is to initialize any required state that the Action might require to work properly.

The function receives four parameters:

Return of the configure function is bytes - some Actions might want to return custom information to the caller.

This configure function could be called by anyone (through the ActionHub, as explained above), it will depend on the implementation of the Action and its purpose who is allowed to invoke it (based on originalMsgSender).

For example, there might be Actions that do not require initialization at all, so the configure function implementation will be empty, while other Actions might require the caller to match the author of the given Post.

Every time the configure function is called, the ActionHub will emit a Lens_ActionHub_PostAction_Configured event matching the parameters of the call (or Lens_ActionHub_PostAction_Reconfigured if the configuration was updated).

The execution of the Action is done through the execute function, which purpose is to perform the actual action logic that the Action implements.

The function receives four parameters:

Return of the execute function is bytes - some Actions might want to return custom information to the caller.

This execute function could be called by anyone (through the ActionHub, as explained above), it will depend on the implementation of the Action and its purpose who is allowed to invoke it (based on originalMsgSender).

For example, there might be Actions that do not require any permissions at all, so the execute function implementation will be open, while other Actions might require the caller to match the author of the given Post.

Every time the execute function is called, the ActionHub will emit a Lens_ActionHub_PostAction_Executed event matching the parameters of the call.

The disabling of the Action is done through the setDisabled function, which purpose is to stop an Action to be executable for a given Post. The same function can be used to enable the Action back.

The function receives five parameters:

Return of the setDisabled function is bytes - some Actions might want to return custom information to the caller.

This setDisabled function could be called by anyone (through the ActionHub, as explained above), it will depend on the implementation of the Action and its purpose who is allowed to invoke it (based on originalMsgSender).

Every time the setDisabled function is called, the ActionHub will emit a Lens_ActionHub_PostAction_Disabled event matching the parameters of the call.

For developers starting with custom Post Actions, the Post Action boilerplate provides a complete foundation for building, deploying, and testing custom actions.

Included in the boilerplate are:

Make sure you have the Node.js >= v20.

Enable Corepack, if it isn't already; this will allow you to use the correct Yarn version:

corepack enable

Then, follow these steps to get started:

git clone https://github.com/lens-protocol/lens-post-action-boilerplate.git my-post-actioncd my-post-action

yarn install

cp .env.example .env

PRIVATE_KEY=0x…

The project includes several yarn scripts designed to streamline your workflow:

For detailed instructions on how to utilize these scripts, refer to the project's README.md file.

Let's illustrate the process with an example. We will build a Simple Poll Vote Action so users can vote (e.g., Yes/No) on a Post representing a poll. This action allows any user to vote once per post.

// SPDX-License-Identifier: MITpragma solidity ^0.8.20;
import { IPostAction } from "contracts/interfaces/IPostAction.sol";import { KeyValue } from "contracts/core/types/Types.sol";import { OwnableMetadataBasedPostAction } from "contracts/actions/post/base/OwnableMetadataBasedPostAction.sol";
contract SimplePollVoteAction is OwnableMetadataBasedPostAction {    event PollVoted(address indexed voter, uint256 indexed postId, bool vote);
    mapping(address feed => mapping(uint256 postId => mapping(address voter => bool hasVoted))) private _hasVoted;
    mapping(address feed => mapping(uint256 postId => mapping(bool vote => uint256 count))) private _voteCounts;
    constructor(        address actionHub,        address owner,        string memory metadataURI    ) OwnableMetadataBasedPostAction(actionHub, owner, metadataURI) {}

// ... inside SimplePollVoteAction ...
function _configure(    address originalMsgSender,    address feed,    uint256 postId,    KeyValue[] calldata params) internal override returns (bytes memory) {    require(        originalMsgSender == IFeed(feed).getPostAuthor(postId),        "Only author can configure"    );    // Any extra configuration logic could be added here (e.g. mapping each possible vote type to some string)    // Emitting an event Lens_ActionHub_PostAction_Configured happens automatically via ActionHub    return "";}

// ... inside SimplePollVoteAction ...
function _execute(    address originalMsgSender,    address feed,    uint256 postId,    KeyValue[] calldata params) external override returns (bytes memory) {    require(!_hasVoted[feed][postId][originalMsgSender], "Already voted");
    _hasVoted[feed][postId][originalMsgSender] = true;
    bool voteFound;    bool vote;    for (uint256 i = 0; i < params.length; i++) {      if (params[i].key == keccak256("lens.param.vote")) {          voteFound = true;          vote = abi.decode(params[i].value, (bool));          break;      }    }
    require(voteFound, "Vote not found in params");
    _voteCounts[feed][postId][vote]++;
    return abi.encode(vote);}

We can also add some getters for vote counts and then the SimplePollVoteAction is ready to be deployed and used.

See the full code below:

// SPDX-License-Identifier: MITpragma solidity ^0.8.20;
import { IPostAction } from "contracts/extensions/action/ActionHub.sol";import { KeyValue } from "contracts/core/types/Types.sol";import { BasePostAction } from "contracts/actions/post/base/BasePostAction.sol";import { IFeed } from "contracts/interfaces/IFeed.sol";
/** * @title SimplePollVoteAction * @notice A simple post action allowing users to cast a boolean vote (e.g., Yes/No) on a post. *         Prevents double voting. */contract SimplePollVoteAction is BasePostAction {    event PollVoted(address indexed voter, uint256 indexed postId, bool vote);
    // feed => postId => voter => hasVoted    mapping(address => mapping(uint256 => mapping(address => bool))) private _hasVoted;
    /**      * @notice Configures the SimplePollVote Action for a given post.      * @param originalMsgSender The address initiating the configuration via the ActionHub. Must be post author.      * @param feed The address of the feed contract where the post exists.      * @param postId The ID of the post being configured.      * @param params Not used      * @return bytes Empty bytes.     */    function _configure(        address originalMsgSender,        address feed,        uint256 postId,        KeyValue[] calldata params    ) internal override returns (bytes memory) {        require(            originalMsgSender == IFeed(feed).getPostAuthor(postId),            "Only author can configure"        );        // Any extra configuration logic could be added here (e.g. mapping each possible vote type to some string)        // Emitting an event Lens_ActionHub_PostAction_Configured happens automatically via ActionHub        return "";    }
    /**     * @notice Executes a vote on a given post.     * @param originalMsgSender The address initiating the vote via the ActionHub.     * @param feed The address of the feed contract where the post exists.     * @param postId The ID of the post being voted on.     * @param params Array of key-value pairs. Expected to contain at least one element,     *        where the `value` of the first element is the ABI-encoded boolean vote.     * @return bytes Empty bytes.     * Requirements:     * - The `originalMsgSender` must not have voted on this `postId` before.     * - `params` must not be empty and the first element's value must be abi-decodable as a boolean.     */    function _execute(        address originalMsgSender,        address feed,        uint256 postId,        KeyValue[] calldata params    ) external override returns (bytes memory) {        require(!_hasVoted[feed][postId][originalMsgSender], "Already voted");
        _hasVoted[feed][postId][originalMsgSender] = true;
        bool voteFound;        bool vote;        for (uint256 i = 0; i < params.length; i++) {          if (params[i].key == keccak256("lens.param.vote")) {              voteFound = true;              vote = abi.decode(params[i].value, (bool));              break;          }        }
        require(voteFound, "Vote not found in params");
        _voteCounts[feed][postId][vote]++;
        return abi.encode(vote);    }
    /**     * @notice Gets the vote counts for a specific post.     * @param feed The address of the feed contract where the post exists.     * @param postId The ID of the post to get vote counts for.     * @return (uint256, uint256) A tuple containing the counts for false and true votes respectively.     */    function getVoteCounts(address feed, uint256 postId) external view returns (uint256 ya, uint256 nay) {        return (_voteCounts[feed][postId][false], _voteCounts[feed][postId][true]);    }}