Help & Support

Custom Graphs

This guide will introduce the concept of Custom Graphs and how to create and manage them.

This guide provides an introduction to the concept of Custom Graphs. More information will be provided in due course.

As outlined in the Graph concept page, there are two classes of Graph instances:

  • The Global Graph: This is the default, familiar graph, encompassing all connections to date.

  • Custom Graphs: These are app-specific graphs, accessible openly or governed by Graph Rules.

Create a Custom Graph

To create a Graph, you need to:

  1. Create a Graph Metadata object

  2. Upload the Graph Metadata object onto a public URI.

  3. Deploy the Lens Graph smart contract.

See the Lens Metadata Standards guide for more information on creating and hosting Metadata objects.

1

Create Graph Metadata

Use the @lens-protocol/metadata package to construct a valid GraphMetadata object:

Example
import { graph } from "@lens-protocol/metadata";
const metadata = graph({  name: "XYZ",  title: "Not Just Another Graph… or is it?",  description: "My custom graph description",});

2

Upload Graph Metadata

Then, upload the Graph Metadata object to a public URI.

import { storageClient } from "./storage-client";
const { uri } = await storageClient.uploadAsJson(metadata);
console.log(uri); // e.g., lens://4f91ca…

This example uses Lens Storage to host the Metadata object. See the Lens Metadata Standards guide for more information on hosting Metadata objects.

3

Deploy Graph Contract

You MUST be authenticated as Builder to make this request.

Use the createGraph action to deploy the Lens Graph smart contract.

import { uri } from "@lens-protocol/client";import { createGraph } from "@lens-protocol/client/action";
const result = await createGraph(sessionClient, {  metadataUri: uri("lens://4f91ca…"),});

4

Handle Result

Finally, handle the result using the adapter for the library of your choice:

import { handleWith } from "@lens-protocol/client/viem";
// …
const result = await createGraph(sessionClient, {  metadataUri: uri("lens://4f91..."), // the URI from the previous step}).andThen(handleWith(walletClient));

See the Transaction Lifecycle guide for more information on how to determine the status of the transaction.

Fetch a Graph

Use the fetchGraph action to fetch a single Graph by address or by transaction hash.

import { evmAddress } from "@lens-protocol/client";import { fetchGraph } from "@lens-protocol/client/actions";import { client } from "./client";
const result = await fetchGraph(client, {  address: evmAddress("0x1234…"),});
if (result.isErr()) {  return console.error(result.error);}
const graph = result.value;

Search Graphs

Use the paginated fetchGraphs action to search for graphs.

import { fetchGraphs } from "@lens-protocol/client/actions";
import { client } from "./client";
const result = await fetchGraphs(client, {  filter: {    searchBy: "graphName",  },});
if (result.isErr()) {  return console.error(result.error);}
// items: Array<Graph>const { items, pageInfo } = result.value;

Continue with the Pagination guide for more information on how to handle paginated results.

Previous
Graph Rules
Next
Usernames