Merge pull request #312 from lukecd/main

Adding: Irys Query Package, Irys Provenance Toolkit
twilson63 · Dec 11, 2023 · 3de6265 · 3de6265
2 parents b5d41a3 + 10fde9b
commit 3de6265
Show file tree

Hide file tree

Showing 11 changed files with 676 additions and 61 deletions.
diff --git a/docs/.prettierignore b/docs/.prettierignore
@@ -2,4 +2,6 @@
 .temp
 dist
 
-package.json
+package.json
+/src/guides/irysQueryPackage.md
+/src/references/irysQueryPackage.md
diff --git a/docs/package.json b/docs/package.json
@@ -1,38 +1,38 @@
 {
-  "name": "cookbook",
-  "version": "0.0.1",
-  "description": "A collection of little developer guides to build on the permaweb",
-  "main": "index.js",
-  "authors": {
-    "name": "Permaweb Builders",
-    "email": "[email protected]"
-  },
-  "repository": "twilson63/permaweb-cookbook/cookbook",
-  "scripts": {
-    "dev": "vuepress dev src",
-    "build": "vuepress build src",
-    "deploy": "npm run build && node deploy.mjs",
-    "fmt": "prettier --single-quote --trailing-comma none --write src/.vuepress",
-    "lint": "prettier --single-quote --trailing-comma none --check src/.vuepress"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@bundlr-network/client": "^0.9.11",
-    "arweave": "^1.11.8",
-    "prettier": "^2.8.4",
-    "vuepress": "2.0.0-beta.61",
-    "@vuepress/plugin-container": "2.0.0-beta.61",
-    "@vuepress/plugin-medium-zoom": "2.0.0-beta.61",
-    "@vuepress/plugin-search": "2.0.0-beta.61",
-    "warp-contracts": "^1.2.37"
-  },
-  "dependencies": {
-    "@octokit/core": "^4.2.1",
-    "@vuepress/plugin-container": "2.0.0-beta.61",
-    "@vuepress/plugin-medium-zoom": "2.0.0-beta.61",
-    "add-to-calendar-button": "^2.2.5",
-    "bootstrap": "5.2.3",
-    "dotenv": "^16.1.4",
-    "openai": "^3.2.1"
-  }
-}
+	"name": "cookbook",
+	"version": "0.0.1",
+	"description": "A collection of little developer guides to build on the permaweb",
+	"main": "index.js",
+	"authors": {
+		"name": "Permaweb Builders",
+		"email": "[email protected]"
+	},
+	"repository": "twilson63/permaweb-cookbook/cookbook",
+	"scripts": {
+		"dev": "vuepress dev src",
+		"build": "vuepress build src",
+		"deploy": "npm run build && node deploy.mjs",
+		"fmt": "prettier --single-quote --trailing-comma none --write src/.vuepress",
+		"lint": "prettier --single-quote --trailing-comma none --check src/.vuepress"
+	},
+	"license": "MIT",
+	"devDependencies": {
+		"@bundlr-network/client": "^0.9.11",
+		"arweave": "^1.11.8",
+		"prettier": "^2.8.4",
+		"vuepress": "2.0.0-beta.61",
+		"@vuepress/plugin-container": "2.0.0-beta.61",
+		"@vuepress/plugin-medium-zoom": "2.0.0-beta.61",
+		"@vuepress/plugin-search": "2.0.0-beta.61",
+		"warp-contracts": "^1.2.37"
+	},
+	"dependencies": {
+		"@octokit/core": "^4.2.1",
+		"@vuepress/plugin-container": "2.0.0-beta.61",
+		"@vuepress/plugin-medium-zoom": "2.0.0-beta.61",
+		"add-to-calendar-button": "^2.2.5",
+		"bootstrap": "5.2.3",
+		"dotenv": "^16.1.4",
+		"openai": "^3.2.1"
+	}
+}
diff --git a/docs/src/.vuepress/sidebar.js b/docs/src/.vuepress/sidebar.js
@@ -139,30 +139,30 @@ const getI18NSidebar = (langCode) => [
 				children: [
 					{
 						text: "ArFS",
-						link: get_i18n_link(langCode, "/concepts/arfs/arfs")
+						link: get_i18n_link(langCode, "/concepts/arfs/arfs"),
 					},
 					{
 						text: "Data Model",
-						link: get_i18n_link(langCode, "/concepts/arfs/data-model")
+						link: get_i18n_link(langCode, "/concepts/arfs/data-model"),
 					},
 					{
 						text: "Entity Types",
-						link: get_i18n_link(langCode, "/concepts/arfs/entity-types")
+						link: get_i18n_link(langCode, "/concepts/arfs/entity-types"),
 					},
 					{
 						text: "Content Types",
-						link: get_i18n_link(langCode, "/concepts/arfs/content-types")
+						link: get_i18n_link(langCode, "/concepts/arfs/content-types"),
 					},
 					{
 						text: "Privacy",
-						link: get_i18n_link(langCode, "/concepts/arfs/privacy")
+						link: get_i18n_link(langCode, "/concepts/arfs/privacy"),
 					},
 					{
 						text: "Schema Diagrams",
-						link: get_i18n_link(langCode, "/concepts/arfs/schema-diagrams")
-					}
-				]
-			}
+						link: get_i18n_link(langCode, "/concepts/arfs/schema-diagrams"),
+					},
+				],
+			},
 		],
 	},
 	{
@@ -289,13 +289,18 @@ const getI18NSidebar = (langCode) => [
 					},
 				],
 			},
+			{
+				text: "Irys Query Package",
+				link: get_i18n_link(langCode, "/guides/irysQueryPackage"),
+				collapsible: false,
+			},
 			{
 				text: "SmartWeave",
 				collapsible: true,
 				children: [
 					{
 						text: get_i18n_str(langCode, "guides-atomic-asset"),
-						link: get_i18n_link(langCode, "/guides/smartweave/atomic-assets/index")
+						link: get_i18n_link(langCode, "/guides/smartweave/atomic-assets/index"),
 					},
 					{
 						text: get_i18n_str(langCode, "guides-atomic-token"),
@@ -366,6 +371,11 @@ const getI18NSidebar = (langCode) => [
 				collapsible: false,
 				link: get_i18n_link(langCode, "/references/http-api"),
 			},
+			{
+				text: "Irys Query Package",
+				collapsible: false,
+				link: get_i18n_link(langCode, "/references/irysQueryPackage"),
+			},
 		],
 	},
 	{
@@ -385,6 +395,10 @@ const getI18NSidebar = (langCode) => [
 				text: "Vue",
 				link: get_i18n_link(langCode, "/kits/vue/"),
 			},
+			{
+				text: "Irys Provenance Toolkit",
+				link: get_i18n_link(langCode, "/kits/irysProvenanceToolkit"),
+			},
 		],
 	},
 ];

diff --git a/docs/src/concepts/queryTransactions.md b/docs/src/concepts/queryTransactions.md
@@ -1,7 +1,9 @@
 # Querying Transactions
+
 It isn't enough to store data permanently, for Arweave to be useful the data also needs to be discoverable and retrievable. This guide summarizes the different approaches to querying data on Arweave.
 
 ## GraphQL
+
 Over time, indexing services that implement a GraphQL interface have became the preferred method for querying transaction data on Arweave. An indexing service reads transaction and block headers as they are added to the network (usually from a full Arweave node which the service operates). Once read, the header info is inserted into a database where it can be indexed and efficiently queried. The indexing service uses this database to provide a GraphQL endpoint for clients to query.
 
 GraphQL has a few advantages that make it ideal for retrieving query data sets. It enables indexing services to create a single endpoint that can then be used to query all types data. The service is able to return multiple resources in a single request as opposed to making an HTTP request for each resource (like one would with a REST API). With GraphQL, clients can batch multiple requests in a single round-trip and specify exactly what data is needed which increases performance.
@@ -33,17 +35,56 @@ const results = await arweave.api.post('/graphql', queryObject);
 ```
 
 ### Public Indexing Services
+
 [https://arweave.net/graphql](https://arweave.net/graphql)
 
 [https://arweave-search.goldsky.com/graphql](https://arweave-search.goldsky.com/graphql)
 
-
 [https://knn3-gateway.knn3.xyz/arseeding/graphql](https://knn3-gateway.knn3.xyz/arseeding/graphql)
 
 ## Inspecting the Blocks
+
 Each piece of data uploaded to Arweave has its own unique transaction id and is included in a unique block which is then added to the blockchain. The data associated with each transaction is split up into 256KB chunks and appended sequentially to Arweave's dataset. It is possible to walk back, block by block, from the [current block](https://arweave.net/block/current) and inspect each one for the transaction id in question. Once found, the chunks offsets can be retrieved from the block and used to request chunks directly from an Arweave peer. This is the lowest level way to locate and read data on the network. Thankfully, less labor intensive approaches [like GraphQL](#graphql) are available.
 
+## Irys Query Package
+
+The [Irys query package](/guides/irysQueryPackage.html) is a JavaScript abstraction that sits on top of GraphQL, enabling JavaScript and TypeScript developers to interact with GraphQL without directly engaging in its syntax.
+
+It supports the same query functionality as native GraphQL [allowing you to search by](https://docs.irys.xyz/developer-docs/querying/query-package#query-type) transaction ID, [tags](https://docs.irys.xyz/developer-docs/tags), [payment token](https://docs.irys.xyz/overview/supported-tokens), transaction sender and block information.
+
+You start by instantiating a new Query object and then filter your query by chaining together a series of filters. You can search transactions uploaded via Irys:
+
+```js:no-line-numbers
+const myQuery = new Query();
+const results = await myQuery
+	.search("irys:transactions")
+	.tags([{ name: "Content-Type", values: ["image/png"] }])
+	.token("solana");
+	.sort("ASC")
+	.limit(20);
+```
+
+Transactions on Arweave:
+
+```js:no-line-numbers
+const myQuery = new Query();
+const results = await myQuery
+	.search("arweave:transactions")
+	.tags([{ name: "Content-Type", values: ["image/png", "image/jpg"] }]);
+```
+
+And Arweave block information.
+
+```js:no-line-numbers
+const myQuery = new Query();
+const results = await myQuery
+	.search("arweave:blocks")
+	.minHeight(1188272)
+	.maxHeight(1188279);
+```
+
 ## ARQL
+
 ::: warning
 ARQL is deprecated and replaced by GraphQL queries at a gateway or indexing service. Some peers may still honor ARQL requests but the availability and accuracy of results are not guaranteed.
 :::
@@ -67,14 +108,14 @@ let get_mail_query =
 
 const res = await this.arweave.api.post(`arql`, get_mail_query)
 ```
+
 This approach to querying was sufficient the weave dataset was small and easy to index. As Arweave adoption accelerated, indexing the data set and responding to ARQL queries resulted in increasing computational costs. Over time as mining became more and more competitive, peers became less and less likely to be able to afford to offer the ARQL service. This ultimately became the impetus for indexing services and the [GraphQL querying](#graphql) common on Arweave today.
 
 There is a pathway back to being able to query data directly from peers however. The [Permaweb Payments Protocol (P3)](https://arweave.net/UoDCeYYmamvnc0mrElUxr5rMKUYRaujo9nmci206WjQ) is a specification developed by the community to enable clients to pay for service. Using P3, peers wishing to offer indexing service could afford to operate it profitably it by charging for the service.
 
 ## Resources
-* [Querying Arweave Guide](../guides/querying-arweave/queryingArweave.md)
-* [ArDB package](../guides/querying-arweave/ardb.md)
-* [ar-gql package](../guides/querying-arweave/ar-gql.md)
-* [GraphQL Reference](../references/gql.md)
-
 
+-   [Querying Arweave Guide](../guides/querying-arweave/queryingArweave.md)
+-   [ArDB package](../guides/querying-arweave/ardb.md)
+-   [ar-gql package](../guides/querying-arweave/ar-gql.md)
+-   [GraphQL Reference](../references/gql.md)
diff --git a/docs/src/guides/README.md b/docs/src/guides/README.md
@@ -23,9 +23,10 @@ Snack-sized guides for the building blocks of the Permaweb
     -   [ArDB](querying-arweave/ardb.md)
     -   [ar-gql](querying-arweave/ar-gql.md)
     -   [Search Service](querying-arweave/search-indexing-service.md)
+-   [Irys Query Package](irysQueryPackage.md)
 -   SmartWeave
     -   [Atomic Assets](smartweave/atomic-assets/index.md)
-        - [using ArDrive CLI](smartweave/atomic-assets/ardrive-cli.md)
+        -   [using ArDrive CLI](smartweave/atomic-assets/ardrive-cli.md)
     -   [Atomic Tokens](atomic-tokens/intro.md)
     -   [Vouch](vouch.md)
     -   Warp Contracts