Since Curate was first conceptualized, demand for ethereum block space has skyrocketed. This put a high price floor on the usecases that Curate can be with. Furthermore, we learned that there are is a lot more demand for user facing data than for contract to contract queries.
Light Curate is a new version of the contract that significantly decreases costs of deployment and operation of Curate lists by leveraging new technologies and changing the strategy for data storage.
1- Light Curate does not use contract storage to store item data. Instead, we only store the item's IPFS multihash in the contract. This means other contracts can't query the TCR with field values, but storage costs are roughly O(1) vs Classic Curate's O(n). 2- The Graph ipfs api means we can also store the item fields in the subgraph. This comes with several benefits, among them: - No need to use @kleros/gtcr-encoder to encode and decode items. Just query the subgraph and you have the item. - Faster, scalable search: Classic Curate needs to sync with the client by downloading every single item and decoding it. With subgraphs we do not need to do this and can query the fields directly. - New need for complex solidity code searching fields on-chain. 3- EIP-1167: Light Curate uses the minimal proxy for new deployments. This means the cost of deploying a new TCR dropped from roughly 7 million gas to 700k. Ten times cheaper!
This section will be divided into 3 sections:
1- Fetching Parameters: Your UI needs to display some important information to the users such as, what is the bounty for successfuly challenges and how long do items stay in the challenge period. 1- Item Submission: Here you will learn how to build a button to submit an item to the UI. 2- Fetching Items: How to view items and item details. 3- Item Interaction: This includes challenging, submitting evidence and crowdfunding appeals.
We use a view contract to fetch all the relevant information at once. Deployments:
- Gnosis:
0x08e58Bc26CFB0d346bABD253A1799866F269805a(source)
Note: If you are using react, you can take the hook we built here or use it as an example.
With light Curate, item submission consists of first uploading the item to IPFS and then submitting a transaction with the required deposit.
Since we use @graphprotocol/graph-ts we must submit items to its ipfs endpoint until they allow custom endpoints. In addition, we also upload to kleros ipfs node.
In addition to Kleros' and The Graph's, we strongly advise pin the data to ipfs nodes you control as well. Update the provided below for this.
Full example here
REACT_APP_IPFS_GATEWAY=https://cdn.kleros.link
REACT_APP_HOSTED_GRAPH_IPFS_ENDPOINT=https://api.thegraph.com/ipfsconst pinFiles = async (
data: FormData,
pinToGraph: boolean
): Promise<
[Array<string>, Array<{ filebaseCid: string; graphCid: string }>]
> => {
const cids = new Array<string>();
// keep track in case some cids are inconsistent
const inconsistentCids = new Array<{
filebaseCid: string;
graphCid: string;
}>();
for (const [_, dataElement] of Object.entries(data)) {
if (dataElement.isFile) {
const { filename, mimeType, content } = dataElement;
const path = `${filename}`;
const cid = await filebase.storeDirectory([
new File([content], path, { type: mimeType }),
]);
if (pinToGraph) {
const graphResult = await publishToGraph(filename, content);
if (!areCidsConsistent(cid, graphResult)) {
console.warn("Inconsistent cids from Filebase and Graph Node :", {
filebaseCid: cid,
graphCid: graphResult[1].hash,
});
inconsistentCids.push({
filebaseCid: cid,
graphCid: graphResult[1].hash,
});
}
}
cids.push(`/ipfs/${cid}/${path}`);
}
}
return [cids, inconsistentCids];
};
/**
* Send file to IPFS network via The Graph hosted IPFS node
* @param data - The raw data from the file to upload.
* @returns ipfs response. Should include the hash and path of the stored item.
*/
export const publishToGraph = async (fileName, data) => {
const url = `${process.env.GRAPH_IPFS_ENDPOINT}/api/v0/add?wrap-with-directory=true`;
const payload = new FormData();
payload.append("file", new Blob([data]), fileName);
const response = await fetch(url, {
method: "POST",
body: payload,
});
if (!response.ok) {
throw new Error(
`HTTP error! status: ${response.status}, Failed to pin to graph`
);
}
const result = parseNewlineSeparatedJSON(await response.text());
return result.map(({ Name, Hash }) => ({
hash: Hash,
path: `/${Name}`,
}));
};
/**
* @description parses json from stringified json's separated by new line
*/
const parseNewlineSeparatedJSON = (text) => {
const lines = text.trim().split("\n");
return lines.map((line) => JSON.parse(line));
};
export const areCidsConsistent = (filebaseCid, graphResult) => {
const graphCid = graphResult[1].hash;
return graphCid === filebaseCid;
};The JSON file for the object is composed of its metadata and fields.
- Metadata (columns): An array describing each of the items columns (what's its type, name, description, etc.)
- Values (values): An object mapping the column name to the value.
The metadata is available inside the meta evidence file, which is returned by the useTCRView hook. The values are input by the user.
Example of columns used by the TCR at
[
{
"label": "Logo",
"description": "The token's logo.",
"type": "image",
"isIdentifier": false
},
{
"label": "Name",
"description": "The token name.",
"type": "text",
"isIdentifier": true
},
{
"label": "Ticker",
"description": "The token ticker.",
"type": "text",
"isIdentifier": true
},
{
"label": "Address",
"description": "The token address.",
"type": "address",
"isIdentifier": true
},
{
"label": "Chain ID",
"description": "The ID of the chain the token contract was deployed",
"type": "number"
},
{
"label": "Decimals",
"description": "The number of decimal places.",
"type": "number"
}
]And an example of values. Note that it is required for the keys to match the column names in the columns object.
{
"Logo": "/ipfs/QmT4vij3PrGZEQ1zarTrPmkqQWggRQN6VEpewSHJXbkeXh/pnk-logo.png",
"Name": "Pinakion",
"Ticker": "PNK",
"Address": "0x93ED3FBe21207Ec2E8f2d3c3de6e058Cb73Bc04d",
"Chain ID": "1",
"Decimals": "18"
}With this in hand we can submit the item.
const gtcr = new ethers.Contract(tcrAddress, _gtcr, signer)
const enc = new TextEncoder()
const fileData = enc.encode(JSON.stringify({ columns, values }))
const ipfsEvidencePath = await ipfsPublish('item.json', fileData)
// Request signature and submit.
const tx = await gtcr.addItem(ipfsEvidencePath, {
value: submissionDeposit
})We break down this section into two as list views and details view have different requirements.
Fetching items is best done via the subgraph we provide. If you deployed a list using the factory, it already has a subgraph deployed and available here.
Whenever we want to fetch items, or a specific item, we must pass the TCR address to the subgraph.
See this react example for more details.
A standard query for the first page of a given list, ordered by the most recent requests, looks like this.
const ITEMS_PER_PAGE = 40
const orderDirection = 'asc'
const page = 1
const itemsWhere = `{ registry: "${tcrAddress.toLowerCase()}" }`
const GTCR_SUBGRAPH_URL=`https://gateway-arbitrum.network.thegraph.com/api/${YOUR_API_KEY}/subgraphs/id/9hHo5MpjpC1JqfD3BsgFnojGurXRHTrHWcUcZPPCo6m8` // You need to replace with your API key
const query = {
query: `
{
items(
skip: ${(Number(page) - 1) * ITEMS_PER_PAGE}
first: ${ITEMS_PER_PAGE}
orderDirection: ${orderDirection}
orderBy: latestRequestSubmissionTime
where: ${itemsWhere}
) {
itemID
status
data
metadata{
props {
value
}
}
requests(first: 1, orderBy: submissionTime, orderDirection: desc) {
disputed
disputeID
submissionTime
resolved
requester
challenger
resolutionTime
rounds(first: 1, orderBy: creationTime, orderDirection: desc) {
appealPeriodStart
appealPeriodEnd
ruling
hasPaidRequester
hasPaidChallenger
amountPaidRequester
amountPaidChallenger
}
}
}
}
`
}
const { data, errors } = await (
await fetch(GTCR_SUBGRAPH_URL, {
method: 'POST',
headers: {
'Content-Type': "application/json",
},
body: JSON.stringify(query)
})
).json()If you want, you can also use apollo to cache queries and make the app load faster.
const ITEM_DETAILS_QUERY = gql`
query itemDetailsQuery($id: String!) {
item(id: $id) {
data
requests(orderBy: submissionTime, orderDirection: desc) {
requestType
disputed
disputeID
submissionTime
resolved
requester
arbitrator
challenger
evidenceGroupID
creationTx
resolutionTx
rounds(orderBy: creationTime, orderDirection: desc) {
appealPeriodStart
appealPeriodEnd
ruling
hasPaidRequester
hasPaidChallenger
amountPaidRequester
amountPaidChallenger
}
}
}
}
`
// subgraph item entities have id "<itemID>@<listaddress>"
const compoundId = `${itemID}@${tcrAddress.toLowerCase()}`
const detailsViewQuery = useQuery(ITEM_DETAILS_QUERY, {
variables: { id: compoundId }
})This is the easiest part of the application. All items are referenced by their ID which is the keccak256 hash of the IPFS URI.
With it you can:
- Execute requests: This is for when a request passed the challenge period without any challenges.
- Challenge requests (registration or removal) via the contract's
challengeRequestfunction - Submit evidence:
submitEvidenceby passing the evidence json file following (ERC-1497)[https://kleros.gitbook.io/docs/developer/erc-1497-evidence-standard] standard. - Fund appeals:
fundAppeal