Post Actions

This guide will explain 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 an 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 any ERC20 token. Work is underway to add support for native GHO tipping (GRASS on the Lens Testnet).

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.

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 98.5 GHO:

import { blockchainData, evmAddress, uri } from "@lens-protocol/client";
const result = await post(sessionClient, {  contentUri: uri("lens://4f91ca…"),  actions: [    {      unknown: {        address: evmAddress("0x1234…"),        params: [          {            raw: {              // 32 bytes key (e.g., keccak(name))              key: blockchainData("0xac5f04…"),              // an ABI encoded value              value: blockchainData("0x00"),            },          },        ],      },    },  ],});

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",    "amount": {      "__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 { handleOperationWith } from "@lens-protocol/client/viem";
// …
const result = await executePostAction(sessionClient, {  post: postId("42"),  action: {    // …  },}).andThen(handleOperationWith(walletClient));

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;

To enable/disable a Post Action, follow these steps.

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 BasePostAction contract, which acts as template for your custom Post Action, applying the restrictions needed, 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.

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.

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 { BasePostAction } from "contracts/actions/post/base/BasePostAction.sol";
contract SimplePollVoteAction is BasePostAction {    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;

// ... 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]);    }}