LensDocumentation

Referencing Content

Learn how to reference other Lens Publications.

Referencing content allows you to link one Lens Publication to another.

Primary Publications

Primary Publications are the types of publications that can be referenced by other publications. These include Posts, Comments, and Quotes.

The Lens SDKs offer type guards to assist you in determining the specific type of a Lens Publication.

These are:

Available in @lens-protocol/react-web and @lens-protocol/react-native

import {  AnyPublication,  Comment,  isCommentPublication,  isMirrorPublication,  isPostPublication,  isPrimaryPublication,  isQuotePublication,  Mirror,  Post,  PrimaryPublication,  Quote,} from '@lens-protocol/react-web';
const publication: AnyPublication = // ...
if (isPrimaryPublication(publication)) {  // publication is PrimaryPublication}
if (isPostPublication(publication)) {  // publication is Post}
if (isCommentPublication(publication)) {  // publication is Comment}
if (isQuotePublication(publication)) {  // publication is Quote}
if (isMirrorPublication(publication)) {  // publication is Mirror}

Reference Publications

There are three types of reference publications in Lens:

  • Comment - This is a response to a Lens Publication. It can be a reply to a Post, a Quote, or another Comment.

  • Quote - This starts a new conversation thread by referencing another Lens Publication. It can reference a Post, a Comment, or another Quote.

  • Mirror - This amplifies a Lens Publication within your own network. It can reference a Post, a Quote, or a Comment. Note that a Mirror does not have content of its own.

Comment

Creating a Comment follows the same process as creating a Post, with the only difference being that it requires the Publication ID of the Lens Publication to which it is responding.

At present, there's no support for optimistically creating a Comment. If you believe this feature would be valuable, please inform the Lens Protocol team.

Sponsored and Signless

You can use the useCreateComment hook to create a Comment.

Example
const { execute, loading, error } = useCreateComment();
// ...
const result = await execute({  commentOn: publication.id,  metadata: metadataURI,});
// continue as shown in the Post example

The hook choose the Signless Experience when possible; otherwise, it will fall back to a signed experience.

The user experience is also influenced by the Reference policy of the referenced publication. For more details, refer to the section on Unknown Reference Modules.

Self-Funded

You can force the SDK to use the Self-funded flow via the sponsored flag.

Example
const { execute, loading, error } = useCreateComment();
// ...
const result = await execute({  commentOn: publication.id,  metadata: metadataURI,  sponsored: false,});

Quote

Creating a Quote follows the same process as creating a Post, with the only difference being that it requires the Publication ID of the Lens Publication it is referencing.

At present, there's no support for optimistically creating a Quote. If you believe this feature would be valuable, please inform the Lens Protocol team.

Sponsored and Signless

You can use the useCreateQuote hook to create a Quote.

Example
const { execute, loading, error } = useCreateQuote();
// ...
const result = await execute({  quoteOn: publication.id,  metadata: metadataURI,});
// continue as shown in the Post example

The hook choose the Signless Experience when possible; otherwise, it will fall back to a signed experience.

The user experience is also influenced by the Reference policy of the referenced publication. For more details, refer to the section on Unknown Reference Modules.

Self-Funded

You can force the SDK to use the Self-funded flow via the sponsored flag.

Example
const { execute, loading, error } = useCreateQuote();
// ...
const result = await execute({  quoteOn: publication.id,  metadata: metadataURI,  sponsored: false,});

Mirror

Creating a Mirror follows the same process as creating a Post, with the only difference being that it requires the Publication ID of the Lens Publication it is referencing and does not require a Publication Metadata URI.

Since Mirrors do not have content of their own, there is no need to upload Publication Metadata. Therefore, metadataURI will not be present in the following examples.

Sponsored and Signless

You can use the useCreateMirror hook to create a Mirror.

Example
const { execute, loading, error } = useCreateMirror();
// ...
const result = await execute({  mirrorOn: publication.id,});
// continue as shown in the Post example

The hook choose the Signless Experience when possible; otherwise, it will fall back to a signed experience.

The user experience is also influenced by the Reference policy of the referenced publication. For more details, refer to the section on Unknown Reference Modules.

Self-Funded

You can force the SDK to use the Self-funded flow via the sponsored flag.

Example
const { execute, loading, error } = useCreateMirror();
// ...
const result = await execute({  mirrorOn: publication.id,  sponsored: false,});

Reference Policies

By default, any Publication can be referenced by anyone. However, you have the option to restrict who can reference a Primary Publication through a Reference Policy. This policy is a set of rules that determine who can reference a given publication.

You can choose from the following options:

  • Followers Only: Only followers of the author's Profile can reference the publication.

  • Degrees of Separation: Only profiles that the author follows within a specified number of degrees of separation can reference the publication.

  • No Reference: No one can reference the publication.

You can also implement custom Reference policies by using an Unknown Reference Module.

While the examples that follows use the Post publication type, the same principles apply to Comments and Quotes.

Read Reference Policy

The approach outlined here can be used to determine the reference policy of any publication.

Every Primary Publication object includes an operations property, which outlines the operations that the authenticated Profile can perform on the publication.

These operations include:

  • operations.canComment: A TriStateValue indicating whether the authenticated Profile can comment on the publication.

  • operations.canQuote: A TriStateValue indicating whether the authenticated Profile can quote the publication.

  • operations.canMirror: A TriStateValue indicating whether the authenticated Profile can mirror the publication.

These properties can have one of the following tri-state values:

  • TriStateValue.No: The publication cannot be referenced.

  • TriStateValue.Yes: The publication can be referenced.

  • TriStateValue.Unknown: It cannot be determined whether the publication can be referenced. This is usually due to the use of an Unknown Reference Module.

The resolveReferencePolicy helper function can be used to extract a developer-friendly ReferencePolicy object from any Lens Publication.

Available in @lens-protocol/react-web and @lens-protocol/react-native

The following example demonstrates how to use this helper function to display a message based on the reference policy of a publication.

import {  PrimaryPublication,  Profile,  resolveReferencePolicy,  ReferencePolicyType,} from "@lens-protocol/react-web";
import { CommentButton } from "./CommentButton";
export function CommentDisclaimer({  publication,}: {  publication: PrimaryPublication;}) {  const policy = resolveReferencePolicy(publication);
  switch (policy.type) {    case ReferencePolicyType.ANYONE:      return <span>Anybody can reference this publication</span>;
    case ReferencePolicyType.FOLLOWERS_ONLY:      return (        <span>          Only {formatProfile(publication.by)} followers can reference this          publication        </span>      );
    case ReferencePolicyType.DEGREES_OF_SEPARATION:      return (        <span>          Only Profiles within {policy.degreesOfSeparation} degrees of          {formatProfile(publication.by)} can reference this publication.        </span>      );
    case ReferencePolicyType.NO_ONE:      return <span>No one can reference this publication</span>;
    case ReferencePolicyType.UNKNOWN:      return <span>Unknown Reference policy: {policy.contractAddress}</span>;  }}
function formatProfile(profile: Profile) {  return profile.handle?.fullHandle ?? profile.id;}

Pro-tip: For ReferencePolicyType.FOLLOWERS_ONLY, you can use the publication.by.operations.isFollowedByMe.value flag to check if the authenticated Profile is following the author of the publication.

Followers Only

Only followers of the author's Profile can reference the publication.

Example
import { ReferencePolicyType } from '@lens-protocol/react-web';
// ...
const { execute, loading, error } = useCreatePost();
// ...const result = await execute({  metadata: await uploadJson(metadata),  reference: {    type: ReferencePolicyType.FOLLOWERS_ONLY,  },});

The same applies to useCreateComment and useCreateQuote hooks.

Degrees of Separation

The "Degrees of Separation" reference policy provides detailed control over who can reference a Lens Publication within the author's Profile network graph. Here's how it works:

  • A degree of separation of "1" means only Profiles that the author follows can reference the Publication.

  • A degree of separation of "2" extends this privilege to Profiles followed by those the author follows, allowing them to reference the Lens Publication.

  • This pattern continues for further degrees of separation.

Furthermore, it's possible to define the types of references allowed (e.g., comments, mirrors, and quotes) for the Lens Publication.

Example
import { ReferencePolicyType } from '@lens-protocol/react-web';
// ...
const { execute, loading, error } = useCreatePost();
// ...const result = await execute({  metadata: await uploadJson(metadata),  reference: {    type: ReferencePolicyType.DEGREES_OF_SEPARATION;    params: {      /**       * If true, only profile within the specified degrees of separation can comment.       */      commentsRestricted: true,      /**       * If true, only profile within the specified degrees of separation can mirror.       */      mirrorsRestricted: true,      /**       * The number of degrees of separation from the reference profile.       */      degreesOfSeparation: 2,      /**       * If true, only profile within the specified degrees of separation can quote.       */      quotesRestricted: true,      /**       * You can set the degree to follow someone else's graph.       *       * If omitted it uses the authenticated Profile ID.       */      // sourceProfileId: '0x01',    },  },});

The same applies to useCreateComment and useCreateQuote hooks.

No Reference

This setting prevents anyone from referencing the Lens Publication, effectively disabling any Comments, Quotes, or Mirrors.

Example
import { ReferencePolicyType } from '@lens-protocol/react-web';
// ...
const { execute, loading, error } = useCreatePost();
// ...const result = await execute({  metadata: await uploadJson(metadata),  reference: {    type: ReferencePolicyType.NO_ONE,  },});

The same applies to useCreateComment and useCreateQuote hooks.

Previous
Content Licensing
Next
Gated Content