Collect Referrals
Learn how to leverage the Referral System when collecting a publication.
When collecting a publication you have the option to include a list of referrers. These referrers will be rewarded according to the Collect Action Settings.
This mechanics can also apply to other Open Actions that supports referrers.
Referral Rewards
In the Collectable Publications page, we discussed how to identify collectable publications. By examining the collect criteria, you can determine if a publication rewards referrers by checking the referralFee field.
The referralFee field value ranges from 0 to 100. A value of 0 indicates no referral fee, while a value of 100 means 100% of the collectable publication's price is distributed among the referrers. If there are multiple referrers, the fee is equally distributed among them.
Scenarios
There are multiple scenarios where a referral reward is deserved. Here are a few examples:
A Profile that mirrored a collectable publication should be rewarded if the original publication is collected from the Mirror.
A Profile that quoted a collectable publication should be rewarded if the original publication is collected from the Quote.
A Profile that commented on a collectable publication should be rewarded if the original publication is collected after being discovered through the comment.
As an app creator, you can reward yourself (your Profile ID) for all collects originating from your application.
A publication that mirrored or quoted collectable publications should be rewarded if the original publication is collected after being discovered through the Mirror or Quote.
Generally, any situation where a profile action leads to a publication being acted upon (through a Collect Action or any community Open Action) and generates revenue for the publication creator, should be recognized as a referral.
Likewise, any publication that mentions or links to another publication, and subsequently leads to a paid collect, should also be recognized as a referral.
Reward Referrers
To reward referrers when collecting a publication, you need to provide the list of refererrers when executing the collect action. The referrers can be either Profile IDs or Publication IDs.
- React SDK
- JavaScript SDK
- API
To do this, simply provide a referrers array with the Publication IDs and/or Profile IDs of the referrers.
CollectButton.tsx
import { OpenActionKind, useOpenAction, profileId, publicationId } from "@lens-protocol/react-web";
// setup the hookconst { execute, loading } = useOpenAction({ action: { kind: OpenActionKind.COLLECT, referrers: [profileId('0x01'), publicationId('0x01-0x456')], },});
// execute the collect actionconst result = await execute({ publication,});That's it—you've just learned how to provide a list of referrers when collecting a publication.
Full Example
In this example, we will use the Lens JavaScript SDK to demonstrate the full process of collecting a publication with referrers.
In the specific we will find a mirrored post that includes a referral fee. We will then collect it, specifying the ID and author of the mirror as referrers.
This example assumes that you have a client.ts module that exports an authenticated LensClient instance, which is required to collect the publication.
First, we'll fetch mirrors and find one that includes a referral fee.
import { client } from "./client";import { PublicationType, isMirrorPublication, isOpenActionModuleWithReferralFee,} from "@lens-protocol/client";
// fetch mirrorsconst mirrorsResult = await client.publication.fetchAll({ where: { publicationTypes: [PublicationType.Mirror], },});
// type safe as Mirrorconst mirrors = mirrorsResult.items.filter(isMirrorPublication);
// we just need one mirror with referralFeeconst mirror = mirrors.find((m) => m.mirrorOn.openActionModules.find( (o) => "referralFee" in o && o.referralFee > 0 ));const openActionWithReferralFee = mirror.mirrorOn.openActionModules.find( (o) => "referralFee" in o && o.referralFee > 0);
// type safe as OpenActionModuleWithReferralFeeFragmentif ( !openActionWithReferralFee || (openActionWithReferralFee && !isOpenActionModuleWithReferralFee(openActionWithReferralFee))) { throw new Error("No openAction found with referralFee");}
console.log( `We found a mirror with ID ${mirror.id} by profile ${mirror.by.id} of a publication ID ${mirror.mirrorOn.id} with openActionModule ${openActionWithReferralFee.__typename} and referralFee: ${openActionWithReferralFee.referralFee}`);Now that we've located a collectable publication through a mirror, we'll collect it, specifying the mirror's ID and author as referrers. We'll use client.publication.actions.createActOnTypedData method to generate the typed data for the collect action, then sign and broadcast it. This is the only way to execute a paid open action.
Let's create a small helper function to map the OpenActionModule to the appropriate input type for the collect action.
import { OpenActionModuleFragment } from "@lens-protocol/client";
function mapOpenActionModuleToInputType( openActionModule: OpenActionModuleFragment) { switch (openActionModule.__typename) { case "SimpleCollectOpenActionSettings": return { simpleCollectOpenAction: true, }; case "MultirecipientFeeCollectOpenActionSettings": return { multirecipientCollectOpenAction: true, }; default: throw new Error( `Unsupported openActionModule type: ${openActionModule.__typename}` ); }}Now, let's execute the paid collect action, including the referrers.
import { client } from "./client";import { isRelaySuccess } from "@lens-protocol/client";
// map the openActionModule to the correct input typeconst actOnInput = mapOpenActionModuleToInputType(openActionWithReferralFee);
// now collect the publication// notice that paid actions need to be signed and sent through broadcastconst resultTypedData = await client.publication.actions.createActOnTypedData({ actOn: actOnInput, for: mirror.mirrorOn.id, referrers: [{ profileId: mirror.by.id }, { publicationId: mirror.id }],});
const { id, typedData } = resultTypedData.unwrap();
console.log(`Typed data: `, typedData);
// sign with the walletconst signedTypedData = await wallet._signTypedData( typedData.domain, typedData.types, typedData.value);
console.log(`Broadcasting signed typed data...`);
const broadcastResult = await client.transaction.broadcastOnchain({ id, signature: signedTypedData,});
const broadcastValue = broadcastResult.unwrap();
if (!isRelaySuccess(broadcastValue)) { console.log(`Something went wrong`, broadcastValue); return;}
console.log( `Transaction was successfully broadcasted with txId`, broadcastValue.txId);Once the collect action is processed, the referrers will receive their rewards as per the Referral System.
You can access the complete example in the examples repository.