Managing Sponsorships
This guide covers how to manage your Lens Sponsorship contract.
Rate Limiting
Lens Sponsorships allow you to scale your app while protecting it from abuse. Sponsorships can be configured with app-wide as well as per-user rate limits with configurable reset windows. This gives the developer full visibility and control over the usage of their app.
Configure Limits
You can provide rate limits when deploying the Sponsorship contract as well as update them later.
First, create the transaction request to update the rate limits of a Sponsorship.
You MUST be authenticated as Builder and be either the owner or an admin of the Sponsorship you intend to configure.
- TypeScript
- GraphQL
Use the updateSponsorshipLimits action to update the rate limits of the Lens Sponsorship smart contract.
- TypeScript
- GraphQL
Then, handle the result using the adapter for the library of your choice:
See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.
Exclusion List
To enable certain use-cases such as trusted VIP/users, the rate-limiting feature can be optionally bypassed for given addresses by adding them to an exclusion list.
Update Exclusion List
First, create the transaction request to update the exclusion list of a Sponsorship.
You MUST be authenticated as Builder and be either the owner or an admin of the Sponsorship you intend to configure.
- TypeScript
- GraphQL
Use the updateSponsorshipExclusionList action to update the exclusions list of the Lens Sponsorship smart contract.
You can add and remove entries as part of the same transaction.
Update Exclusion List
import { evmAddress, SponsorshipRateLimitWindow } from "@lens-protocol/client";import { updateSponsorshipExclusionList } from "@lens-protocol/client/actions";
// …
const result = await updateSponsorshipExclusionList(sessionClient, { sponsorship: evmAddress("0xe2f2a5C287993345a840db3B0845fbc70f5935a5"), toAdd: [ { address: evmAddress("0x1234…"), label: "Bob The Builder", }, ], toRemove: [evmAddress("0x5678…")],});- TypeScript
- GraphQL
Then, handle the result using the adapter for the library of your choice:
See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.
Fetch Exclusion List
- TypeScript
- GraphQL
Use the paginated fetchSponsorshipLimitExclusions action to fetch a list of addresses that are excluded from the rate limits.
Example
import { evmAddress } from "@lens-protocol/client";import { fetchSponsorshipLimitExclusions } from "@lens-protocol/client/actions";
import { client } from "./client";
const posts = await fetchSponsorshipLimitExclusions(client, { filter: { sponsorship evmAddress("0x1234…"), },});
if (result.isErr()) { return console.error(result.error);}
// items: Array<{ sponsorship: EvmAddress, label: string, address: EvmAddress, createdAt: DateTimeTime }>const { items, pageInfo } = result.value;See the Pagination guide for more information on how to handle paginated results.
Signers
To ensure that sponsored transactions are only used by the intended users, the Sponsorship contract uses a list of authorized signers. These signers are one or more addresses that need to supply their signature to every transaction sent to the Sponsorship contract, indicating that the transaction originates from their app.
This is the mechanism behind the allowLensAccess flag you encountered when deploying the Sponsorship contract—it allows the Lens API to sponsor transactions for users while they are logged into your app.
Update Signers
You can provide a list of signers when deploying the Sponsorship contract as well as update them later.
First, create the transaction request to update the signers of a Sponsorship.
You MUST be authenticated as Builder and be either the owner or an admin of the Sponsorship you intend to configure.
- TypeScript
- GraphQL
Use the updateSponsorshipSigners action to update the signers of the Lens Sponsorship smart contract.
Fetch Signers
- TypeScript
- GraphQL
Use the paginated fetchSponsorshipSigners action to list the signers of a Sponsorship.
Example
import { evmAddress } from "@lens-protocol/client";import { fetchSponsorshipSigners } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchSponsorshipSigners(client, { filter: { sponsorship: evmAddress("0x1234…"), },});
if (result.isErr()) { return console.error(result.error);}
// items: Array<SponsorshipSigner>// const { items, pageInfo } = result.value;See the Pagination guide for more information on how to handle paginated results.
Pausing Sponsorships
By default, Sponsorships are active when deployed and ready to use. You can pause a Sponsorship to stop it from being used to sponsor transactions.
First, create the transaction request to pause or unpause a Sponsorship.
You MUST be authenticated as Builder and be either the owner or an admin of the Sponsorship you intend to configure.
- TypeScript
- GraphQL
Use the pauseSponsorship or unpauseSponsorship action to pause or unpause a Sponsorship.
Access Control
The Sponsorship contract supports two roles: Owner and Administrators.
Administrators can:
Add and remove authorized signers
Add and remove addresses to the rate limit exclusion list
Update the rate limits
Pause and unpause the Sponsorship
The Owner can do everything the administrators can do, plus:
Transfer ownership
Update the list of administrators
Withdraw the funds from the Sponsorship
See the Team Management guide for more information on how to manage these roles.