diff --git a/warp-academy-docs/docs/sdk/advanced/bundled-interaction.md b/warp-academy-docs/docs/sdk/advanced/bundled-interaction.md deleted file mode 100644 index 0ff4290..0000000 --- a/warp-academy-docs/docs/sdk/advanced/bundled-interaction.md +++ /dev/null @@ -1,202 +0,0 @@ -# Warp Sequencer - -Warp Sequencer is a module that is responsible for submitting users' transactions into Arweave (via [Bundlr Network](https://bundlr.network/)). -During the process, the transactions are indexed in [Warp Gateway](/docs/gateway/overview). -This makes them instantly available for further processing (e.g. state evaluation) - unlike in traditional processing, -where user has to wait several minutes for transaction mining and confirmation. - -Additionally, the Warp Sequencer does not require users to have any cryptocurrencies (AR, ETH, etc.) on their wallets. - -## Introduction - -The idea behind Warp Sequencer is to increase the Developer and User Experience. -Normally, when an interaction with a contract is being sent to Arweave, one has to wait some time: - -1. for the transaction mining (~2 minutes) -2. for the proper transaction confirmation (assuming at least 10 blocks - ~20 minutes). - -This in total gives ~20-25 minutes, which: - -1. Breaks the DX, e.g. in case developer wants to quickly test the contract's functions on mainnet -2. Breaks the UX, e.g. - each user of a given dApp/protocol must wait really long to see the effect - of an interaction with a contract. This makes the applications effectively unusable - especially for users coming - from the web2. - -Additionally, any interaction with contract requires some amount of ARs in the wallet - which might further increase -the entry barrier, both for developers and given protocol/dApp users. - -**NOTE** Waiting for a proper confirmation -is especially important (though often overlooked) in case of a smart contract interactions. -Imagine a cache, that is evaluating the contracts state for all the interactions returned at any given time by the -default Arweave (arweave.net) gateway. -If the cache does not wait for the proper transactions' confirmation, it may happen -that it will store a contract state evaluated from the transactions from a forked blocks (or - even worse - from -transactions that were not included in any block). - -## Advantages of using Warp Sequencer for interactions posting - -1. Interaction is near-instantly available - as soon as proper response from Bundlr network is received. -2. Posting interactions with contract does not require any ARs - the deployment via Bundlr network is either - fully subsidized by the Arweave (for transactions <= 100KiB) or by the Warp (for transactions > 100KiB). - The max transaction size is currently 2MiB. - Most of the contracts' interactions have the "default" 4B size. -3. Even though the Bundlr transactions are created and signed by the Warp's wallet, it is still possible to identify - the original data item owner/signer. - **NOTE** This is especially important in case of smart contracts - as contracts' business - logic very often is dependent on _who_ (i.e. what wallet address) is interacting with the contract. -4. The option to use VRF in contracts that require verifiable randomness. -5. Even if the Warp infra will go down, all the contract interactions can be still retrieved directly from Arweave, - using a simple GQL query. - -## How it works - -Instead of posting the interaction transactions directly to Arweave mainnet, Warp SDK creates a data item with interaction input and tags which is then signed with user's wallet. Data item is then sent to Warp Sequencer (`/gateway/v2/sequencer/register` endpoint) (this is the default behaviour of Warp's SDK `contract.writeInteraction` -function, when `forMainnet` instance is being used). - -The Warp Sequencer then: - -#### 1. Generates a sort key - -A sort key is generated from: - -1. current mainnet network height -2. current sequence value -3. original transaction id -4. current mainnet block hash - -In the original SmartWeave protocol specification, a _sort key_ is defined -as a `[ block_height,sha256(transactionId + blockHash) ]`, where: - -1. `block_height` - current network height, l-padded with `0` to 12 chars, e.g. for block height `1015556`, the - result is `000001015556` -2. `sha256(transactionId + blockHash)` - a `sha256` hash of the concatenated buffers of the transaction id and block - hash, - e.g. for txId `UR_35HORbjjZ_NnUqinkZuWkcNB1-gBST3Rezt5JrDs` and block - hash `ixWCxRN36DjVUxQRa68xIeoZLfvLDTtX78e0ae8RAAJjOPpDBuVKVaEKYOpq7bLS`, - the result is `44edd70f2018924f22a878a558a8f2d5cae8bc1f718d567df43bf52b6384d260`. - -The complete _sort key_ for the above values would -be: `000001015556,44edd70f2018924f22a878a558a8f2d5cae8bc1f718d567df43bf52b6384d260`. - -The generated sort keys are then used by the SmartWeave protocol to lexicographically sort the transactions. - -The Warp Sequencer extends this default mechanism by the current sequence value. -The formula for the _sort key_ is extended to: -`[ block_height,sequence_value,sha256(transactionId + blockHash) ]` - -This sequence value can be obtained from the Sequencer's node timestamp, database or other sources. -In its current implementation - a Sequencer node timestamp value is being used. -This in effect gives a fair transactions ordering - the transactions will have the sequence assigned in order in which -they are processed by the Sequencer. - -Assuming transaction id `La_NpAFAWxGj-VIiLfg7NbBfox0RZ8uuEJSOOZykd48`, block -hash `-o88tFYsMG9RXSGcNXX5sVDuSV5uHy7zuFRj6vYo91e3mXpmng6qw322Ip0-EguA`, -block height `1015560` and current Sequencer value `1663069424541`, the generated _sort key_ would -be `000001015560,1663069424541,a21ac8a60326ba8c2bb8caa05cff3334a22e9960ef55de0b5392caa30b484d0a` - -**NOTE** All the transactions sent to Arweave directly, have the sequence value assigned to `0000000000000000`. -This effectively means that if transactions to a given contract are sent both directly to Arweave mainnet and Warp -Sequencer - -if two transactions happen to be at the same block height, the "direct" Arweave transactions take precedence. -This also means that the sequencing algorithm is fully backwards compatible with the original SmartWeave protocol. - -#### 2. Generates tags for the Bundlr transaction - -| Tag Name | Tag Value | -| ------------------------------------------- | -------------------------------------------------------------------- | -| `Sequencer` | `Warp` | -| `Sequencer-Owner` | The original owner/signar of the contract transaction | -| `Sequencer-Mills` | The sequence value used by the Sequencer for this transaction | -| `Sequencer-Sort-Key` | The generated sort key for this transaction | -| `Sequencer-Last-Sort-Key` | The sort key of the previous transaction | -| `Sequencer-Tx-Id` | The original transaction id | -| `Sequencer-Block-Height` | The block height used for generating the sort key | -| `Sequencer-Block-Id` | The block hash used for generating the sort key | -| `Sequencer-Block-Timestamp` | The timestamp of the block that was used for generating the sort key | -| ...all the tags of the original transaction | | - -:::tip -The `Sequencer-Last-Sort-Key` tells what is the sort key of the 'previous' transaction in the sequencer and -can be used to verify whether all transactions have been properly loaded (i.e. if one -decides to load them directly from L1 nodes) and none is missing. -::: - -Additional set of tags are added in case user requests generating a random value using VRF (Verifiable Random Function): - -| Tag Name | Tag Value | -| ------------ | ----------------------------------------------------------------------- | -| `vrf-index` | The original hash generated by the VRF (using `sort_key` as input data) | -| `vrf-proof` | The original proof generated by the VRF | -| `vrf-bigint` | A BigInt value evaluated from the hash generated by the VRF | -| `vrf-pubkey` | The public key used by the VRF | - -Verifiable randomness can be used by contracts that require using random values - e.g. gaming contracts, nft/loot -generating contracts, etc. -Using the `sort_key`, `vrf-proof` and `vrf-pubkey`, the client can always verify the generated random value. - -#### 3. Wrap original data item in a bundle and uploads the bundle to Bundlr - -Apart from all the tags from point 2, some additional tags are added to the wrapping bundle: - -| Tag Name | Tag Value | -| ---------------- | ----------------- | -| `Bundle-Format` | `binary` | -| `Bundle-Version` | `2.0.0` | -| `App-Name` | `Warp` | -| `Action` | `WarpInteraction` | - -In order to send original data item to Bundlr, we use the concept of nested bundles and set an interaction data item inside a bundle. If you're not faimiliar with this concept, here is a quick summary: - -:::info -Bundling allows to write multiple data items into one top level transaction. A data item differs from a regular transaction by not allowing to transfer AR tokens and passing reward but it has most of the transaction's properties - such as owner, data, tags, owner and id. - -In a nutshell, the nested bundles concept means that a data item of a bundle can also be a bundle containg other data items. According to ANS-104 standard it can lead to theoretically unbounded levels of nesting. - -You can read the specification for nested bundles standard in [ANS-104](https://github.com/ArweaveTeam/arweave-standards/blob/master/ans/ANS-104.md#31-nested-bundle). -::: - -:::info -Obviously the data-item is signed by the Sequencer's wallet - and as such can be easily verified. -The Sequencer wallet address is `jnioZFibZSCcV8o-HkBXYPYEYNib4tqfexP0kCBXX_M`. -::: - -**NOTE** The original data item is not modified in any way - this is to preserve the original -signature! - -After receiving proper response and receipt from Bundlr, the Warp gateway indexes the contract interaction -internally - to make it instantly available. - -#### 4. Finally, the Warp gateway returns the response from the Bundlr to the client. - -## Interaction data item retrieval (generated by the Warp Sequencer) via Arweave gateway - -Use the GQL endpoint, with the original data item id passed in the `Contract` tag. Note that all the -interactions will be part of a bundle (i.e. will have the `edges.node.bundledIn.id` value set). - -```qql -query { - transactions( - ids: ["1UIhK4vL5lc2X4aMsJFmMpJqfdgrjznVzi2F17yLBlc"] - ) { - edges { - node { - id - tags { - name - value - } - block { - height - } - bundledIn { - id - } - } - } - } -} -``` - -## Interaction retrieval via Warp gateway - -The Warp `/gateway/interactions/:id` endpoint allows to retrieve the interaction info based on its original id. diff --git a/warp-academy-docs/docs/sequencer/lifecycle/ordering.md b/warp-academy-docs/docs/sequencer/lifecycle/ordering.md index 2e9a132..5c07a46 100644 --- a/warp-academy-docs/docs/sequencer/lifecycle/ordering.md +++ b/warp-academy-docs/docs/sequencer/lifecycle/ordering.md @@ -47,15 +47,12 @@ This implies, in particular, that when an Arweave block along with its contained ## Previous Sort Key ----- -[DIAGRAM WITH LINKED LIST OF INTERACTIONS] - ----- - All interactions, regardless of how they were sent, are ordered by the sequencer in a linear order. This means that for each interaction, which is not the first interaction of a given contract, we can identify its predecessor within that contract. For this purpose, we use a value we will call the `prev sort key`. +![Linked list of interactions](/img/docs/sequencer/interactions-linked-list.png) + This value is useful prior to the evaluation of the contract state when retrieving the [list of interactions](/docs/gateway/http/get/interactions) for that contract from the gateway, ensuring that no interactions were overlooked. To calculate the prev sort key, each sequencer node maintains a map (refer to: [Data Format](/docs/sequencer/data-format#previous-sort-keys)) in which, for each contract ID, the sort key of the last interaction associated with that contract is stored. @@ -63,10 +60,7 @@ To calculate the prev sort key, each sequencer node maintains a map (refer to: [ ## Block Proposal As sequencer nodes accept interactions and place them in their mempool, these interactions do not yet have assigned `sort key` and `prev sort key` values. These values can only be calculated at the time of creating a proposal for the next sequencer block. ----- -[DIAGRAM FOR PROPOSER] - ----- +![Creating a block proposal](/img/docs/sequencer/block-proposal.png) The process is as follows: diff --git a/warp-academy-docs/docs/sequencer/lifecycle/overview.md b/warp-academy-docs/docs/sequencer/lifecycle/overview.md index 5fdd426..ac5ce12 100644 --- a/warp-academy-docs/docs/sequencer/lifecycle/overview.md +++ b/warp-academy-docs/docs/sequencer/lifecycle/overview.md @@ -3,6 +3,8 @@ Interactions are used to change the state of contracts and invoke computations defined in the contract's source code. However, before any of that can happen, the interaction must go through a lifecycle, which is not such a simple process. +![The lifecycle of an interaction in Warp Sequencer](/img/docs/sequencer/interaction-lifecycle.png) + In brief, the lifecycle of an interaction begins when it is [created](/docs/sequencer/lifecycle/creating) and sent by the [Warp SDK](/docs/sdk/overview). The interaction is then [received](/docs/sequencer/lifecycle/receiving) by the Warp Sequencer, which establishes order relative to other interactions. The process of [ordering](/docs/sequencer/lifecycle/ordering) involves generating keys on which the interactions are sorted, as well as generating random values in case the contract needs them. @@ -18,6 +20,4 @@ For this type of interaction, the sequencer also sends data to Arweave, but only The gateway receives a common list of interactions regardless of whether they were sent to the sequencer or to Arweave. -![Decentralized Warp Sequencer](/img/docs/sequencer/sequencer.png) - The stages of the interaction lifecycle will be described in detail in the following sections. \ No newline at end of file diff --git a/warp-academy-docs/docs/sequencer/lifecycle/receiving.md b/warp-academy-docs/docs/sequencer/lifecycle/receiving.md index 0a50f24..f74bf02 100644 --- a/warp-academy-docs/docs/sequencer/lifecycle/receiving.md +++ b/warp-academy-docs/docs/sequencer/lifecycle/receiving.md @@ -1,5 +1,7 @@ # Receiving and Validating Interactions +![Receiving interaction by the sequencer node](/img/docs/sequencer/receiving-interaction.png) + The sequencer accepts interactions in the form of [DataItem](https://github.com/ArweaveTeam/arweave-standards/blob/master/ans/ANS-104.md) via the endpoint `/api/v1/data-item` (refer to: [API Methods](/docs/sequencer/api-methods#submits-a-new-interaction-to-the-sequencer)). Interactions added to the sequencer's blockchain take the form of messages. The message that encapsulates an interaction in the DataItem format is `MsgDataItem` (see: [Messages format](/docs/sequencer/data-format#interaction-message)). @@ -10,11 +12,6 @@ Finally, a transaction is created whose only message is this interaction. A [transaction](https://docs.cosmos.network/main/learn/advanced/transactions) in the Cosmos SDK represents a set of messages that trigger state transitions within the blockchain. ::: ----- -[DIAGRAM FOR RECEIVING INTERACTIONS] - ----- - ## Validation Subsequently, the transaction undergoes a validation process to ensure its correctness. diff --git a/warp-academy-docs/docusaurus.config.js b/warp-academy-docs/docusaurus.config.js index b306ee7..65f5051 100644 --- a/warp-academy-docs/docusaurus.config.js +++ b/warp-academy-docs/docusaurus.config.js @@ -83,6 +83,17 @@ const config = { }, sidebarPath: require.resolve('./sidebars/standardsSidebar.js'), }, + ], + [ + '@docusaurus/plugin-client-redirects', + { + redirects: [ + { + to: '/docs/sequencer/introduction', + from: '/docs/sdk/advanced/bundled-interaction', + } + ] + } ] ], diff --git a/warp-academy-docs/package.json b/warp-academy-docs/package.json index 952c27d..ad8cd81 100644 --- a/warp-academy-docs/package.json +++ b/warp-academy-docs/package.json @@ -16,6 +16,7 @@ "dependencies": { "@docsearch/react": "3", "@docusaurus/core": "^2.4.0", + "@docusaurus/plugin-client-redirects": "2.4.0", "@docusaurus/preset-classic": "^2.4.0", "@docusaurus/theme-mermaid": "^2.4.0", "@mdx-js/react": "^1.6.22", diff --git a/warp-academy-docs/standards/tradeable-atomic-asset.md b/warp-academy-docs/standards/tradeable-atomic-asset.md index 1533bc1..c8cabeb 100644 --- a/warp-academy-docs/standards/tradeable-atomic-asset.md +++ b/warp-academy-docs/standards/tradeable-atomic-asset.md @@ -16,7 +16,7 @@ To find existing contracts implementing the atomic-asset standard, we can use `t Tags can be specified [during deployment](../docs/sdk/advanced/register-contract) of atomic-asset. - During deployment following tag should be added : `{name: 'Indexed-By', value: 'atomic-asset'}` - - This tag is supported by [warp-aggregate-node](../docs/aggregate-node/overview.md). Thus allow to query assets by its owner - [documentation](../docs/aggregate-node/overview.md#nft-by-owner) + - This tag is supported by [warp-aggregate-node](../docs/aggregate-node/overview). Thus allow to query assets by its owner - [documentation](../docs/aggregate-node/overview#nft-by-owner) ## State diff --git a/warp-academy-docs/static/img/docs/sequencer/block-proposal.png b/warp-academy-docs/static/img/docs/sequencer/block-proposal.png new file mode 100644 index 0000000..15f1584 Binary files /dev/null and b/warp-academy-docs/static/img/docs/sequencer/block-proposal.png differ diff --git a/warp-academy-docs/static/img/docs/sequencer/sequencer.png b/warp-academy-docs/static/img/docs/sequencer/interaction-lifecycle.png similarity index 100% rename from warp-academy-docs/static/img/docs/sequencer/sequencer.png rename to warp-academy-docs/static/img/docs/sequencer/interaction-lifecycle.png diff --git a/warp-academy-docs/static/img/docs/sequencer/interactions-linked-list.png b/warp-academy-docs/static/img/docs/sequencer/interactions-linked-list.png new file mode 100644 index 0000000..4a34f94 Binary files /dev/null and b/warp-academy-docs/static/img/docs/sequencer/interactions-linked-list.png differ diff --git a/warp-academy-docs/static/img/docs/sequencer/receiving-interaction.png b/warp-academy-docs/static/img/docs/sequencer/receiving-interaction.png new file mode 100644 index 0000000..9409dfa Binary files /dev/null and b/warp-academy-docs/static/img/docs/sequencer/receiving-interaction.png differ diff --git a/warp-academy-docs/yarn.lock b/warp-academy-docs/yarn.lock index 41a10b9..7d4ba68 100644 --- a/warp-academy-docs/yarn.lock +++ b/warp-academy-docs/yarn.lock @@ -1680,6 +1680,21 @@ react-helmet-async "*" react-loadable "npm:@docusaurus/react-loadable@5.5.2" +"@docusaurus/plugin-client-redirects@2.4.0": + version "2.4.0" + resolved "https://registry.yarnpkg.com/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-2.4.0.tgz#53117d112ac9cc191deda053af4335e0381b4125" + integrity sha512-HsS+Dc2ZLWhfpjYJ5LIrOB/XfXZcElcC7o1iA4yIVtiFz+LHhwP863fhqbwSJ1c6tNDOYBH3HwbskHrc/PIn7Q== + dependencies: + "@docusaurus/core" "2.4.0" + "@docusaurus/logger" "2.4.0" + "@docusaurus/utils" "2.4.0" + "@docusaurus/utils-common" "2.4.0" + "@docusaurus/utils-validation" "2.4.0" + eta "^2.0.0" + fs-extra "^10.1.0" + lodash "^4.17.21" + tslib "^2.4.0" + "@docusaurus/plugin-content-blog@2.4.0": version "2.4.0" resolved "https://registry.yarnpkg.com/@docusaurus/plugin-content-blog/-/plugin-content-blog-2.4.0.tgz#50dbfbc7b51f152ae660385fd8b34076713374c3" @@ -3187,15 +3202,10 @@ caniuse-api@^3.0.0: lodash.memoize "^4.1.2" lodash.uniq "^4.5.0" -caniuse-lite@^1.0.0, caniuse-lite@^1.0.30001286: - version "1.0.30001312" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001312.tgz#e11eba4b87e24d22697dae05455d5aea28550d5f" - integrity sha512-Wiz1Psk2MEK0pX3rUzWaunLTZzqS2JYZFzNKqAiJGiuxIjRPLgV6+VDPOg6lQOUxmDwhTlh198JsTTi8Hzw6aQ== - -caniuse-lite@^1.0.30001426, caniuse-lite@^1.0.30001449: - version "1.0.30001450" - resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001450.tgz#022225b91200589196b814b51b1bbe45144cf74f" - integrity sha512-qMBmvmQmFXaSxexkjjfMvD5rnDL0+m+dUMZKoDYsGG8iZN29RuYh9eRoMvKsT6uMAWlyUUGDEQGJJYjzCIO9ew== +caniuse-lite@^1.0.0, caniuse-lite@^1.0.30001286, caniuse-lite@^1.0.30001426, caniuse-lite@^1.0.30001449: + version "1.0.30001572" + resolved "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001572.tgz" + integrity sha512-1Pbh5FLmn5y4+QhNyJE9j3/7dK44dGB83/ZMjv/qJk86TvDbjk0LosiZo0i0WB0Vx607qMX9jYrn1VLHCkN4rw== ccount@^1.0.0: version "1.1.0"