Sponsored Transactions

Learn how to provide a gasless social experience for your users.

The Lens API allows you to offer a gasless experience to your users by sponsoring their transaction costs.

To illustrate these concepts, examples from the process of creating a Post will be used. It would be beneficial to have some familiarity with Content Creation.

Most operations in Lens involve EVM transactions. These are referred to as on-chain transactions to differentiate them from Momoka transactions.

const { execute, loading, error } = useCreatePost();
// ...
// publish postconst result = await execute({  metadata:    "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",  reference: {    type: ReferencePolicyType.FOLLOWERS_ONLY  },});
// detect if an early error occurredif (result.isFailure()) {  console.error(result.error.message);  return;}
// the transaction has been broadcasted and is now being monitored by the SDK

// publish postconst result = await execute({  metadata:    "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",  reference: {    type: ReferencePolicyType.FOLLOWERS_ONLY  },
  // opt out of Sponsored Transactions  sponsored: false,});

Certain operations in Lens can be performed using the Momoka Data Scaling solution. Momoka transactions are less expensive and offer higher throughput compared to traditional on-chain transactions.

Momoka transactions are inherently Sponsored Transactions. Currently, they are used exclusively for creating Momoka Publications. However, the potential for expanding their use in the future remains open.

const { execute, loading, error } = useCreatePost();
// ...
// publish postconst result = await execute({  metadata:    "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"});
// detect if an early error occurredif (result.isFailure()) {  window.alert(result.error.message);  return;}
// optional: wait for the transaction to be mined and indexedconst completion = await result.value.waitForCompletion();
// detect if a minining/indexing error occurredif (completion.isFailure()) {  window.alert(completion.error.message);  return;}
// post was createdconst post = completion.value;

// publish postconst result = await execute({  metadata:    "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  // opt out of Sponsored Transactions  sponsored: false,});

To use Sponsored Transactions through the Lens API, you must meet the following criteria:

The Lens Protocol team has set rate limits on the number of sponsored transactions that will be covered for any given user.

You can verify the current rate limits for a user by using either the SDK or the API.

import { development, LensClient } from '@lens-protocol/client';
const client = new LensClient({  environment: development,});
const result = await client.wallet.rateLimits({  userAddress: '0xa5653e88D9c352387deDdC79bcf99f0ada62e9c6',});

The Lens Protocol team has implemented a series of measures to uphold the quality of the Lens ecosystem. These measures are designed to mitigate the impact of spammy profiles on the overall user experience. They include:

The Lens API imposes further restrictions on the number of sponsored transactions for profiles that fall below a certain signal score threshold, referred to as low-signal profiles. The rate limits for these low-signal profiles are as follows:

Accounts identified as low-signal will need to cover their own gas costs for transactions beyond these limits.

With the introduction of Lens Protocol V2, anyone can now create and use Custom Modules without requiring approval from the Lens Protocol team. This empowers the community to innovate without constraints.

However, Lens API only sponsors transactions involving modules that have undergone a review process. Consequently, operations involving non-reviewed custom modules may not be eligible for sponsored transactions.

In the broadcast on-chain section, we explored the process of creating a sponsored on-chain transaction using EIP-712 Typed Data and signatures. When an operation is broadcast, its signature is directed to a specific Lens Protocol function. Each operation is associated with a unique function that verifies the signature, unpacks the typed data, and carries out the operation on the user's behalf.

To prevent replay attacks on signatures, each operation incorporates a nonce in its EIP-712 Typed Data. This nonce, a sequentially incremented number, tracks the operations performed by a specific signer. It ensures that each signature is unique and can only be processed once. If a nonce is reused or out of sequence, the operation will fail.

When you initiate a sponsored transaction, the Lens API generates the EIP-712 Typed Data based on its current understanding of the blockchain state, which includes the latest known nonce for the signer's address. However, if you initiate another sponsored transaction on the same contract while a previous one is still pending, the nonce in the new transaction's Typed Data will collide with the nonce of the pending transaction. This collision will cause the new transaction to be rejected by the Lens Protocol.

If your dApp allows for concurrent operations, you need to manage signature nonces on the consumer side.

The Lens Protocol has three separate contracts that track nonces independently. These contracts are:

For reliable nonce management, it's crucial to stay updated with the latest nonce for the specific Lens contract you're planning to interact with through sponsored transactions.

You can accomplish this with the JavaScript SDK client.wallet.sigNonces method.

const result = await client.wallet.sigNonces();
if (result.isFailure()) {  console.error(result.error);  process.exit(1);}
console.log(result.value);

Alternatively, you can directly use the Lens API userSigNonces query.

query {  userSigNonces {    lensHubOnchainSigNonce    lensPublicActProxyOnchainSigNonce    lensTokenHandleRegistryOnchainSigNonce  }}

In this context:

The nonce you should consider for an operation depends on the specific operation and whether the user is logged in with a Profile or Wallet-only.

The table below serves as a guide. It illustrates the relationship between the method used to create Typed Data for an operation, the user's authentication status (either Wallet-only or Profile), and the corresponding contract whose nonce should be used as reference for subsequent transactions.

To clarify, let's consider a couple of examples:

Next, every time you create EIP-712 Typed Data for a sponsored transaction, you should specify the nonce explicitly by incrementing the latest reference nonce by 1.

const typedDataResult = await client.publication.createOnchainPostTypedData(  {    contentURI:      "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",  },  {    overrideSigNonce: 42 + 1,  });

You should continue this process, incrementing the nonce by 1 for each new sponsored transaction you create.

The sequence diagram below offers a high-level overview of the process. We've intentionally omitted some details to focus on the aspect of nonce management.

That's it—you now have a solid understanding of how to manage nonces for sponsored transactions.