Open Action | Rentable Billboard
Turn your post into a rentable billboard
ℹ️ This technical guide will go over our open action from a protocol perspective, and then with a full typescript example to initialize and process a post with the RentableSpaceAction
Smart Contract Overview
The verified open action module is here: https://polygonscan.com/address/0x6f7b96f99a3904581470002cee1c5182d8743f34
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
.
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 paymentallowOpenAction
: whether to allow open actions to also be promotedexpireAt
: the expiry timestamp for when this post is accepting adsclientFeePerActBps
: the client fee % on any act, to incentivize clients to promotereferralFeePerActBps
: the referral fee % on any act, to incentivize mirrorsinterestMerkleRoot
: [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:
By providing an existing adPubId
, the advertiser is wishing to include their post (and the attached openActionModule
) in their ad. Otherwise, they can just provide adContentUri
which will be resolved to Lens content metadata.
An advertiser must query for the ad cost (including fees) for a rentable space, which also accounts for the markup when there's an active ad (more info on Advertiser Bidding below). They can query the contract to get the active space's currency.
The return value to use from getAdCost()
that must be approved to pay for ad space is costWithFee
.
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.
A profile owner can always check their total fees earned, and claim that full amount after the ad on their rentable space has ended.
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
:
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.
Client Integration
Here you can find two hardhat tasks (written in typescript) which outline the steps necessary to initialize a publication with the RentableSpaceAction
module, as well as how to process it.
create-post-rentable
to initact-rent-billboard
to process
The scripts make use of the metadata set in the Lens API, and send a raw transaction to the LensHub
contract to post and to act.
The main things to consider are
On init, the post creator must set the open action module as a delegated executor (profile manager). This is to enable an auto-mirror whenever an advertiser acts on the post, for more visibility on the ad.
On act, the actor profile must approve the correct
costWithFee
by querying thegetAdCost()
function on the contract.On act, the advertiser has two options 1) set a
adContentUri
value for the input struct to simply set their own metadata (following the Lens metadata standard) as the ad or 2) set their ownadPubId
andopenActionModule
in order to, for example, promote their own collectable post.
Last updated