Unlock
Search…
Using Subgraphs
In this tutorial, we will see how to use the a subgraph in order to retrieve large amounts of data from the protocol.
RPC endpoints are only able to return a single piece of information at a time, such as the name of a single lock, or the expiration date of a single key... etc.
Retrieving multiple attributes of an object or a list of objects is generally costly and not recommended. For that, subgraphs are a better solution. The way to think about Subgraphs is as "views" of the data stored on chains that is organized and indexed using different dimensions. They use the popular GraphQL API query language to make it trivial to quickly retrieve large amounts of data.
In this tutorial, we will write a function that uses Unlock's subgraphs to retrieve a list of locks managed by a given address. We actually use a similar approach to load a user's lock on our dashboard.

Building the request

The first step is to build the request itself. For this, The Graph offers a convenient Playground tool. Let's look at an example with our xDAI subgraph (all networks share the same schema).
In the left column, you can see a query builder that you can use to customize your queries. The right column provides a convenient way to inspect the schema and auto-complete your queries.
In order to get the locks managed by a given address, we build the following request:
1
{
2
lockManagers(where: { address: "0xDD8e2548da5A992A63aE5520C6bC92c37a2Bcc44" }) {
3
lock(orderBy: creationBlock, orderDirection: desc) {
4
address
5
name
6
price
7
tokenAddress
8
expirationDuration
9
totalSupply
10
maxNumberOfKeys
11
}
12
}
13
}
Copied!
We first get the lockManager whose address matches the one we're looking for, and then, retrieve the locks, sorted by the creation block in a descending order (first in the list is the most recent). For each lock, we get their address, name, price, token (if it is an ERC20 lock), duration, as well as total supply and maximum number of memberships.

Sending the request

There are exists multiple GraphQL libraries in many languages. Here we will focus on the most basic approach: using JavaScript's fetch function that is available in any web browser environment, but also in node.js using node-fetch.
1
// We build the query, with a variable $owner
2
const query = `query Locks($owner: String!) {
3
lockManagers(where: { address: $owner }) {
4
lock(orderBy: creationBlock, orderDirection: desc) {
5
address
6
name
7
price
8
tokenAddress
9
expirationDuration
10
totalSupply
11
maxNumberOfKeys
12
}
13
}
14
}`
15
16
// We set the variable's value to the the user's address
17
const variables = { "owner": userAddress}
18
19
// We send a POST request to the subgraph endpoint of our choice (change if using a different network!)
20
// The body of the request must include a stringified version of and object built with the query and variables
21
const result = await fetch('https://api.thegraph.com/subgraphs/name/unlock-protocol/unlock', {
22
method: 'POST',
23
headers: {
24
'Content-Type': 'application/json',
25
'Accept': 'application/json',
26
},
27
body: JSON.stringify({
28
query,
29
variables
30
})
31
}).then(r => r.json())
Copied!
The result variable will be populated with the result of the query. It will be an array, with all of the information that was retrieved, and matching the query's format. More specifically, here it includes the following: a data object that includes a single property: lockManagers and a list of matching locks!
1
{
2
"data": {
3
"lockManagers": [
4
{
5
"lock": {
6
"address": "0x0dbcdfef8f5b0f8bb3de068cdc56d4c6b6d68914",
7
"expirationDuration": "864000",
8
"maxNumberOfKeys": null,
9
"name": "xDAI Lock",
10
"price": "100000000000000000",
11
"tokenAddress": "0x0000000000000000000000000000000000000000",
12
"totalSupply": "0"
13
}
14
},
15
{
16
"lock": {
17
"address": "0x18c39c5ed5c28681a1b44e31488a5639439419a1",
18
"expirationDuration": "31536000",
19
"maxNumberOfKeys": null,
20
"name": "Ouvre-Boite",
21
"price": "5000000000000000000",
22
"tokenAddress": "0x0000000000000000000000000000000000000000",
23
"totalSupply": "0"
24
}
25
}
26
]
27
}
28
}
Copied!

Next steps

GraphQL lets developers build complex queries to retrieve data from the blockchain that can be used to populate fields in your web3 application!
Last modified 10d ago