Open Action | Rentable Billboard

Turn your post into a rentable billboard

Smart Contract Overview

The RentableSpaceAction open action enables profiles to rent their publication space for advertising. Payment is done via ERC20 tokens on polygon such as BONSAI or WMATIC, and space is rented on a per second basis. A creator initializes a post with this action module and sets the token cost per second, the allowed category for ads (optional), and whether open actions can also be promoted. A profile that wants to act on this module must specify how long they wish to rent space for and approve the required payment; if a category was defined on init - provide the merkle proof that their content fits the allowed category. Funds are transferred and the content/open action from the pubId passed in are hot-swapped with this post's contentURI / open action. Clients that integrate this open action must fetch active ad content via the view function #getActiveAd.

 * @notice Get the active ad content and open action module (if any) for a given publication space
 * @param profileId The publication space profile id
 * @param profileId The publication space id
function getActiveAd(
  uint256 profileId, uint256 pubId
) external view returns (string memory contentUri, address openActionModule);

How to initialize

To initialize a publication with this action module, the publication creator must supply in the encoded module init data

  • currency: the ERC20 token to use for payment

  • allowOpenAction: whether to allow open actions to also be promoted

  • expireAt: the expiry timestamp for when this post is accepting ads

  • clientFeePerActBps: the client fee % on any act, to incentivize clients to promote

  • referralFeePerActBps: the referral fee % on any act, to incentivize mirrors

  • interestMerkleRoot: [optional] a merkle tree root for the allowed interest; if set, actors must provide the proof that their profile / content is part of this tree. This will be provided by the MadFi API.

How to process

When a profile wishes to rent the space, they call act() via Lens Protocol, we expect a struct of type RentParams in the encoded action module data:

struct RentParams {
    uint256 adPubId; // [optional] the pub id to pull contentUri and action module for the ad
    uint256 duration; // the amount of time the advertiser wishes to pay for
    uint256 costPerSecond; // the amount the advertisers is willing to pay per second
    uint256 merkleProofIndex; // proof index the space's category merkle
    address clientAddress; // [optional] the whitelisted client address to receive fees
    address openActionModule; // [optional] the linked open action module
    string adContentUri; // [optional] if no pub id passed in, use this lens metadata uri
    bytes32[] merkleProof; // proof for the space's category merkle

By providing an existing pubId, the advertiser is wishing to include their post (and the attached openActionModule) in their ad. Otherwise, they can just provide adContentUri which will be resolve to Lens content metadata.

Advertiser Bidding

To allow for bidding on a rentable space, we allow advertisers to pay the costPerSecond times minBidIncreaseBps which is set to 20%. So advertisers wishing to replace an active ad must bid 20% more than the current active bid.

Replacing an ad refunds the previous advertiser from the contract.

Clients and referrers are paid automatically, and creators must call withdrawFeesEarned to claim their fees. Due to the refund mechanism, the creator of a rentable space can only withdraw fees after the time period for an active ad has passed.

 * @notice Allows a profile or profile manager to withdraw any fees earned, minus the owed amount for a given active ad, if any
 * NOTE: we accrue fees in the contract in order to handle refunds in case of ads being outbidded or canceled
function withdrawFeesEarned(
  address currency, uint256 profileId
) external onlyProfileOwnerOrDelegated(profileId);

A profile owner can always check their total fees earned, and claim that full amount after the ad on their rentable space has ended.

function feesEarned(
  address profileOwner, address currency
) external view returns (uint256);

Canceling an Active Ad

A creator may cancel an active ad on their space after the protocol-defined window of 12 hours; this refunds the advertiser for the amount of time their ad wasn't live.

We also have a flagging and blacklisting feature that allows a creator to cancel an active ad for the reasons defined in enum CancelAdReason:

enum CancelAdReason {
    BAD_ACTOR, // any bad activity
    EXIT, // to allow good faith canceling after `adMinDuration`

This flags the appropriate profile for clients to be aware of during the init / act process. A flagged profile may be blacklisted by the contract owner, which prohibits them from ever calling init / act again.

function cancelActiveAd(
    uint256 profileId,
    uint256 actorProfileId,
    CancelAdReason reason,
    string calldata otherReason,
    bool closeSpace
) external onlyProfileOwnerOrDelegated(profileId);

SDK Overview


Last updated