diff --git a/README.md b/README.md index 52a2b4bb4..62749307c 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,9 @@ This web application contains all documentation for t1. It was forked from the [ # Project Layout -### t1 documentation currently has one section: +### t1 documentation currently has two sections: - Concepts - General t1 information or concepts useful for using t1 +- API - xChainRead API documentation ### TODO: - Add essential t1 contract docs, including technical method descriptions via `forge doc --serve` @@ -18,7 +19,7 @@ This web application contains all documentation for t1. It was forked from the [ - ~~Deploy these docs to the world wide web~~ - ~~Create a job to automatically re-deploy the docs to the world wide web when merge into `main` branch~~ - ~~Once the link is fixed or the Lorem Ipsum is replaced with real content, remove the `˙` at the end of the title~~ - - Ensure that all linked Github repos are public before sharing link + - ~~Ensure that all linked Github repos are public before sharing link~~ ## Adding Documentation diff --git a/docs/api/subgraph/_category_.json b/docs/api/subgraph/_category_.json deleted file mode 100644 index 1d891d527..000000000 --- a/docs/api/subgraph/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Subgraph", - "position": 2, - "collapsed": false -} diff --git a/docs/api/subgraph/guides/_category_.json b/docs/api/subgraph/guides/_category_.json deleted file mode 100644 index c694eb5b2..000000000 --- a/docs/api/subgraph/guides/_category_.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "label": "Guides", - "position": 2, - "collapsed": false -} diff --git a/docs/api/subgraph/guides/subgraph-example.md b/docs/api/subgraph/guides/subgraph-example.md deleted file mode 100644 index 2b2582892..000000000 --- a/docs/api/subgraph/guides/subgraph-example.md +++ /dev/null @@ -1,307 +0,0 @@ ---- -id: examples -title: Query Examples -sidebar_position: 3 ---- - -# Subgraph Query Examples - -This doc will teach you how to query t1 V3 analytics by writing GraphQL queries on the subgraph. You can fetch data points like : - -- [collected fees for a position](#general-position-data) -- [current liquidity](#pool-data) of a pool -- [volume on a certain day](#historical-global-data) - -and much more. Below are some example queries. To run a query copy and paste it into the [v3 explorer](https://thegraph.com/hosted-service/subgraph/uniswap/uniswap-v3) to get fresh data. - -## Global Data - -Global data refers to data points about the t1 v3 protocol as a whole. Some examples of global data points are total value locked in the protocol, total pools deployed, or total transaction counts. Thus, to query global data you must pass in the t1 V3 Factory address `0x1F98431c8aD98523631AE4a59f267346ea31F984` and select the desired fields. Reference the full [factory schema](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql#L1) to see all possible fields. - -### Current Global Data - -An example querying total pool count, transaction count, and total volume in USD and ETH: - -``` -{ - factory(id: "0x1F98431c8aD98523631AE4a59f267346ea31F984" ) { - poolCount - txCount - totalVolumeUSD - totalVolumeETH - } -} -``` - -### Historical Global Data - -You can also query historical data by specifying a block number. - -``` -{ - factory(id: "0x1F98431c8aD98523631AE4a59f267346ea31F984", block: {number: 13380584}){ - poolCount - txCount - totalVolumeUSD - totalVolumeETH - } -} -``` - -## Pool Data - -To get data about a certain pool, pass in the pool address. Reference the full [pool schema](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql#L75) and adjust the query fields to retrieve the data points you want. - -### General Pool Query - -The query below returns the feeTier, spot price, and liquidity for the ETH-USDC pool. - -``` -{ - pool(id: "0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8") { - tick - token0 { - symbol - id - decimals - } - token1 { - symbol - id - decimals - } - feeTier - sqrtPrice - liquidity - } -} -``` - -### All Possible Pools - -The maximum items you can query at once is 1000. Thus to get all possible pools, you can iterate using the skip variable. To get pools beyond the first 1000 you can also set the skip as shown below. - -### Skipping First 1000 Pools - -This query sets the skip value and returns the first 10 responses after the first 1000. - -``` -{ - pools(first:10, skip:1000){ - id - token0 { - id - symbol - } - token1 { - id - symbol - } - } -} -``` - -### Creating a Skip Variable - -This next query sets a skip variable. In your language and environment of choice you can then iterate through a loop, query to get 1000 pools each time, and continually adjust skip by 1000 until all pool responses are returned. - -Check out [this example](https://github.com/Uniswap/v3-info/blob/770a05dc1a191cf229432ebc43c1f2ceb3666e3b/src/data/pools/chartData.ts#L14) from our interface for poolDayData that does something similar. - -Note: This query will not work in the graph explorer and more resembles the structure of a query you'd pass to some graphql middleware like Apollo. - -``` -query pools( $skip: Int!) { - pools( - first: 1000 - skip: $skip - orderDirection: asc - ) { - id - sqrtPrice - token0 { - id - } - token1 { - id - } - } - } - -``` - -### Most Liquid Pools - -Retrieve the top 1000 most liquid pools. You can use this similar set up to orderBy other variables like number of swaps or volume. - -``` -{ - pools(first: 1000, orderBy: liquidity, orderDirection: desc) { - id - } -} -``` - -### Pool Daily Aggregated - -This query returns daily aggregated data for the first 10 days since the given timestamp for the UNI-ETH pool. - -``` -{ - poolDayDatas(first: 10, orderBy: date, where: { - pool: "0x1d42064fc4beb5f8aaf85f4617ae8b3b5b8bd801", - date_gt: 1633642435 - } ) { - date - liquidity - sqrtPrice - token0Price - token1Price - volumeToken0 - volumeToken1 - } -} -``` - -## Swap Data - -### General Swap Data - -To query data about a particular swap, input the transaction hash + "#" + the index in the swaps the transaction array.R -This is the reference for the full [swap schema](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql#L353). - -This query fetches data about the sender, receiver, amounts, transaction data, and timestamp for a particular swap. - -``` -{ - swap(id: "0x000007e1111cbd97f74cfc6eea2879a5b02020f26960ac06f4af0f9395372b64#66785") { - sender - recipient - amount0 - amount1 - transaction { - id - blockNumber - gasUsed - gasPrice - } - timestamp - token0 { - id - symbol - } - token1 { - id - symbol - } - } - } -``` - -### Recent Swaps Within a Pool - -You can set the `where` field to filter swap data by pool address. This example fetches data about multiple swaps for the USDC-USDT pool, ordered by timestamp. - -``` -{ -swaps(orderBy: timestamp, orderDirection: desc, where: - { pool: "0x7858e59e0c01ea06df3af3d20ac7b0003275d4bf" } -) { - pool { - token0 { - id - symbol - } - token1 { - id - symbol - } - } - sender - recipient - amount0 - amount1 - } -} -``` - -## Token Data - -Input the the token contract address to fetch token data. Any token that exists in at least one t1 V3 pool can be queried. The output will aggregate data across all v3 pools that include the token. - -### General Token Data - -This queries the decimals, symbol, name, pool count, and volume in USD for the UNI token. Reference the full [token schema](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql#L38) for all possible fields you can query. - -``` -{ - token(id:"0x1f9840a85d5af5bf1d1762f925bdaddc4201f984") { - symbol - name - decimals - volumeUSD - poolCount - } -} -``` - -### Token Daily Aggregated - -You can fetch aggregate data about a specific token over a 24-hour period. This query gets 10-days of the 24-hour volume data for the UNI token ordered from oldest to newest. - -``` -{ - tokenDayDatas(first: 10, where: {token: "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"}, orderBy: date, orderDirection: asc) { - date - token { - id - symbol - } - volumeUSD - } -} -``` - -### All Tokens - -Similar to retrieving all pools, you can fetch all tokens by using skip. -Note: This query will not work in the graph sandbox and more resembles the structure of a query you'd pass to some graphql middleware like Apollo. - -``` -query tokens($skip: Int!) { - tokens(first: 1000, skip: $skip) { - id - symbol - name - } -} -``` - -## Position Data - -### General Position Data - -To get data about a specific position, input the NFT tokenId. This queries the collected fees for token0 and token1 and current liquidity for the position with tokenId 3. Reference the full [position schema](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql#L192) to see all fields. - -``` -{ - position(id:3) { - id - collectedFeesToken0 - collectedFeesToken1 - liquidity - token0 { - id - symbol - } - token1 - { - id - symbol - } - } -} -``` - -## Contribute - -There are many more queries you can do with the t1 v3 subgraph including data related to ticks, mints, positions, and burns. Once again you can reference the full schema [here](https://github.com/Uniswap/v3-subgraph/blob/main/schema.graphql). If you'd like to suggest more example queries to showcase, feel free to drop some suggestions in [discord](https://discord.com/invite/uniswap) under #dev-chat or [contribute](../../../../CONTRIBUTING.md) your own queries by submitting a pull request to the docs repo. diff --git a/docs/api/subgraph/overview.md b/docs/api/subgraph/overview.md deleted file mode 100644 index 14ab98e00..000000000 --- a/docs/api/subgraph/overview.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -id: overview -sidebar_position: 1 -title: Overview ---- - -# The t1 Subgraph - -Uniswap uses multiple [subgraphs](https://thegraph.com/docs/about/introduction#what-the-graph-is) for indexing and organizing data from the t1 smart contracts. -These subgraphs are hosted on The Graph hosted service and can be used to query t1 data. - -## Versions and Production Endpoints - -Each version of t1 has its own dedicated subgraph, and governance contracts have a dedicated subgraph as well. - -Each subgraph has a dedicated endpoint for querying data, as well as a page on [The Graph explorer](https://thegraph.com/explorer) that exposes the schema and available fields to query. - -##### V3 (Mainnet) - -- [Subgraph](https://thegraph.com/explorer/subgraphs/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV?view=Query&chain=arbitrum-one) -- Graphql Endpoint: `https://gateway.thegraph.com/api//subgraphs/id/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV` -- Code: https://github.com/Uniswap/v3-subgraph - -##### V2 (Mainnet) - -- [Subgraph](https://thegraph.com/explorer/subgraphs/A3Np3RQbaBA6oKJgiwDJeo5T3zrYfGHPWFYayMwtNDum?view=Query&chain=arbitrum-one) -- Graphql Endpoint: `https://gateway.thegraph.com/api//subgraphs/id/A3Np3RQbaBA6oKJgiwDJeo5T3zrYfGHPWFYayMwtNDum` -- Code: https://github.com/Uniswap/v2-subgraph diff --git a/docs/api/xChainRead/api-reference.md b/docs/api/xChainRead/api-reference.md new file mode 100644 index 000000000..f2f21af53 --- /dev/null +++ b/docs/api/xChainRead/api-reference.md @@ -0,0 +1,123 @@ +--- + +id: api-reference +title: API Reference +sidebar_label: API Reference +sidebar_position: 2 +--- + +# API Reference + +### Get Read Proofs +Retrieve proof data for cross-chain read requests. + +**URL**: https://api.v05.t1protocol.com/api/read-proofs + +**Parameters**: +- `address` (string, required): Your contract address +- `direction` (string, optional): L1_TO_L2 or L2_TO_L1 +- `page` (number, optional): Page number +- `page_size` (number, optional): Results per page + +**Example**: +https://api.v05.t1protocol.com/api/read-proofs?address=0x81B5e00e15fb3ee055aB5e616Ccb52fA935D3534&direction=L1_TO_L2&page=1&page_size=100 + + +**Response Format**: + +```json +{ + "source_tx_hash": "0xc40c2adee606e05a4c40f26f13c6066ddfabcac9467fdbf7450dac7a644f3d9e", + "message_type": 4, // xChainRead + "block_number": 163780939, + "message_hash": "0x94cdea443c0f6034de6bdf781ce159055546c0e42632db5215558c392088ee8f", + "tx_sender": "0x42d389A9007e446b92C0ce7bd8F42Ea10292881B", + "direction": "L1_TO_L2", // Arbitrum Sepolia to Base Sepolia + "claim_info": { + "from": "0x81B5e00e15fb3ee055aB5e616Ccb52fA935D3534", + "to": "0xf96B8CcB029E0932fe36da0CeDd2b035E2c1695d", + "value": "0", + "nonce": "4", + "message": "0xe11680cd0000000000000000000000000000000000000000000000000000000000014a34000000000000000000000000f96b8ccb029e0932fe36da0cedd2b035e2c1695d374f3efe8b19f4937fadee47d33f93d66a6dd62f5141d8efa41bf5de64f6e53a00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000081b5e00e15fb3ee055ab5e616ccb52fa935d35340000000000000000000000000000000000000000000000000000000000000024ebd45ba21b50198add4a3fd45e9b53bf0a37bd0859d912cfdde54efefe31a0a0fc203b1f00000000000000000000000000000000000000000000000000000000", + "x_chain_read_result": "0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000011b50198add4a3fd45e9b53bf0a37bd0859d912cfdde54efefe31a0a0fc203b1f0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000200000000000000000000000004c408e9bed2426840112ed5fc1c438356a1fd162", + "request_id": "0x374f3efe8b19f4937fadee47d33f93d66a6dd62f5141d8efa41bf5de64f6e53a", + "handle_read_result_with_proof_calldata": "0x0000000000000000000000000000000000000000000000000000000000000004374f3efe8b19f4937fadee47d33f93d66a6dd62f5141d8efa41bf5de64f6e53a000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000002200000000000000000000000000000000000000000000000000000000000000160000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000011b50198add4a3fd45e9b53bf0a37bd0859d912cfdde54efefe31a0a0fc203b1f0000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000200000000000000000000000004c408e9bed2426840112ed5fc1c438356a1fd16200000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000ad3228b676f7d3cd4284a5443f17f1962b36e491b30a40b2405849e597ba5fb5ada0adf42ef09dfcc8f39ea7a22fb33de614899ddecc8558ab5ba341febd990b", + "proof": { + "batch_index": "4", + "merkle_proof": "0000000000000000000000000000000000000000000000000000000000000000ad3228b676f7d3cd4284a5443f17f1962b36e491b30a40b2405849e597ba5fb5ada0adf42ef09dfcc8f39ea7a22fb33de614899ddecc8558ab5ba341febd990b" + } + } +} +``` + +### Key Fields + +| Field | Description | +|-------|-------------| +| `source_tx_hash` | Transaction hash that initiated the read request | +| `message_type` | Message type (4 = xChainRead) | +| `block_number` | Block number when request was submitted | +| `request_id` | Unique identifier for the read request | +| `x_chain_read_result` | Raw ABI-encoded result from target function | +| `handle_read_result_with_proof_calldata` | **Ready-to-use calldata for your contract** | +| `proof.batch_index` | Batch containing this read result | +| `proof.merkle_proof` | Cryptographic proof for verification | + +:::tip +The `handle_read_result_with_proof_calldata` field contains pre-encoded calldata that you can directly submit to your contract's `handleReadResultWithProof` function. +::: + +## Smart Contract API + +### `T1XChainReader` Interface + +```solidity +interface T1XChainReader { + struct ReadRequest { + uint32 destinationDomain; + address targetContract; + uint256 gasLimit; + uint64 minBlock; + bytes callData; + address requester; + } + + function requestRead( + ReadRequest calldata request + ) external payable returns (bytes32 requestId); + + function verifyProofOfRead( + bytes calldata encodedProofOfRead + ) external view returns (bytes32 requestId, bytes memory result); +} +``` + +### Events + +```solidity +event ReadRequested( + bytes32 indexed requestId, + uint32 indexed destinationDomain, + address targetContract, + address requester, + uint256 gasLimit, + uint64 minBlock, + bytes callData, + uint256 nonce +); + +event ProofOfReadRootCommitted(uint256 batchIndex); +``` + +### Proof Encoding Format + +Proofs use the following ABI encoding: +```solidity +abi.encode( + uint256 batchIndex, // index of the batch posted by the prover + bytes32 requestId, // requestId of the read request + uint256 position, // position in merkle tree + bytes result, // raw function result, ABI-encoded + bytes proof // merkle proof +) +``` \ No newline at end of file diff --git a/docs/api/xChainRead/overview.md b/docs/api/xChainRead/overview.md new file mode 100644 index 000000000..5df2e9b36 --- /dev/null +++ b/docs/api/xChainRead/overview.md @@ -0,0 +1,98 @@ +--- +id: overview +title: xChainRead Overview +sidebar_label: Overview +sidebar_position: 1 +--- + +# xChainRead + +xChainRead is a cross-chain verification primitive that enables smart contracts to securely call view functions on other t1-supported chains and prove the results back to an origin chain. + +## How It Works + +xChainRead operates through TEE-secured execution: + +1. **Request**: Your contract calls `requestRead()` with target chain and function details +2. **Execution**: t1's TEE infrastructure executes the cross-chain read request on the target chain +3. **Proof**: Results are batched into merkle trees and the root is committed on-chain +4. **Verification**: Fetch the proof from the API and verify it for your contract + +### TEE Security Model + +t1 runs full nodes of partner rollups inside TEEs, ensuring verifiable execution of state reads and cryptographic guarantees of result integrity. + +## Quick Start + +### 1. Deploy Your Contract + +t1 currently supports the following chains: +- Arbitrum Sepolia +- Base Sepolia + +Let's use the following example to demonstrate how to use xChainRead. This example is a simplified version of the [T1ERC7683](https://github.com/t1protocol/t1/blob/canary/contracts/src/7683/T1ERC7683.sol) contract. It allows users to request a cross-chain read of the `getFilledOrderStatus` function of a 7683 contract on the Base Sepolia chain. + +```solidity +import "./T1XChainReader.sol"; + +contract IntentSettler { + T1XChainReader public xChainRead; + mapping(bytes32 => bytes32) public readRequestToOrderId; + + constructor(address _xChainReader) { + xChainRead = T1XChainReader(_xChainReader); + } + + function requestVerification(bytes32 orderId) external payable { + bytes memory callData = abi.encodeWithSignature( + "getFilledOrderStatus(bytes32)", + orderId + ); + + bytes32 requestId = xChainRead.requestRead({ + destinationDomain: 84532, // Base Sepolia + targetContract: 0xf96B8CcB029E0932fe36da0CeDd2b035E2c1695d, + gasLimit: 200000, + minBlock: 0, + callData: callData, + requester: msg.sender + }); + + readRequestToOrderId[requestId] = orderId; + } + + function handleReadResultWithProof(bytes calldata encodedProofOfRead) external { + (bytes32 requestId, bytes memory result) = + xChainRead.verifyProofOfRead(encodedProofOfRead); + + bytes32 orderId = readRequestToOrderId[requestId]; + require(orderId != bytes32(0), "Invalid request"); + + delete readRequestToOrderId[requestId]; + + // Process verified result + bool isSettled = (result.length != 0); + if (isSettled) { + _releaseEscrowToSolver(orderId); + } + } +} +``` + +### 2. Request Cross-Chain Read + +The `requestRead` function is used to request a cross-chain read. It takes a `ReadRequest` struct as input, which contains the following fields: + +- `destinationDomain`: The domain ID of the target chain +- `targetContract`: The address of the target contract +- `gasLimit`: The gas limit for the read operation +- `minBlock`: The minimum block number to read from +- `callData`: The calldata to call the target function with + +### 3. Handle Proof Response + +Once the read request is processed, the result will be posted to the [API](./api-reference). You can fetch the proof from the API and verify it with your contract. The `verifyProofOfRead` function is used to verify the proof. It takes a `bytes` calldata as input, which can be fetched via the `handle_read_result_with_proof_calldata` field from the API. If the proof is valid, the function will return the request ID and the result of the target function. If the proof is invalid, the function will revert. + +## Next Steps + +- [API Reference](./api-reference) - Detailed API documentation \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 97c55f105..3e178d043 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -36,6 +36,12 @@ module.exports = { position: 'left', className: 'V3_active', }, + { + to: '/api/xChainRead/overview', + label: 'API', + position: 'left', + className: 'V3_active', + }, { // TODO(docs): Publish docs repo and make public at this URL href: 'https://github.com/t1protocol/', diff --git a/src/pages/index.tsx b/src/pages/index.tsx index 9744555f7..384b58038 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -28,7 +28,7 @@ export const actions = [ title: '𝚝𝟷 devnet portal', icon: Chain, to: 'https://devnet.t1protocol.com/', - text: `Play with 𝚝𝟷 devnet.`, + text: `Experience real time cross-chain interactions with 𝚝𝟷.`, }, { title: 'The 𝚝𝟷 smart contracts', @@ -52,17 +52,12 @@ export const dAppGuides = [ text: 'Deposit funds to start interacting with apps on 𝚝𝟷 devnet.', to: 'https://devnet.t1protocol.com/bridge/', }, - { - title: 'T-DEX', - text: 'Swap tokens on 𝚝𝟷 without needing to bridge.', - to: 'https://t-dex.devnet.t1protocol.com/', - }, ] export const smartContractGuides = [ { - title: 'Setup your environment', - text: 'Prepare your local environment for interacting with 𝚝𝟷.', - to: 'https://devnet.t1protocol.com/', + title: 'xChainRead', + text: 'Read data from other chains and prove the results back to your contract.', + to: '/api/xChainRead/overview', }, ]