Add app data repo functions

.env.example

@@ -0,0 +1,2 @@
+USER_ADDRESS=
+PRIVATE_KEY=

.github/workflows/ci.yml

@@ -14,7 +14,7 @@ jobs:
     strategy:
       matrix:
         python-version: [
-          "3.8", "3.9", "3.10", "3.11", "3.12",
+          "3.10", "3.11", "3.12",
         ]
     timeout-minutes: 10
     steps:
@@ -32,6 +32,10 @@ jobs:
           cache: poetry
           cache-dependency-path: poetry.lock
 
+      - name: Poetry lock
+        run: |
+          poetry lock
+
       - name: Install dependencies
         run: |
           poetry install

.pre-commit-config.yaml

@@ -1,9 +1,10 @@
 repos:
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  # Ruff version.
-  rev: v0.1.4
-  hooks:
-    # Run the linter.
-    - id: ruff
-    # Run the formatter.
-    - id: ruff-format
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.3.7
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [--fix]
+      # Run the formatter.
+      - id: ruff-format

Makefile

@@ -0,0 +1,27 @@
+.PHONY: codegen web3_codegen orderbook_codegen subgraph_codegen test lint format remove_unused_imports
+
+codegen: web3_codegen orderbook_codegen subgraph_codegen
+
+# web3_codegen:
+# 	poetry run web3_codegen
+
+orderbook_codegen:
+	poetry run datamodel-codegen --url="https://raw.githubusercontent.com/cowprotocol/services/v2.245.1/crates/orderbook/openapi.yml" --output cow_py/order_book/generated/model.py --target-python-version 3.12 --output-model-type pydantic_v2.BaseModel --input-file-type openapi
+
+subgraph_codegen:
+	poetry run ariadne-codegen
+
+test:
+	poetry run pytest -s
+
+lint:
+	poetry run ruff check . --fix
+
+format: remove_unused_imports
+	poetry run ruff format
+
+remove_unused_imports:
+	poetry run pycln --all .
+
+typecheck:
+	poetry run pyright

README.md

@@ -8,7 +8,7 @@ Welcome to the CoW Protocol Python SDK (cow_py), a developer-friendly Python lib
 
 ## 🐄 Features
 
-- Querying CoW Protocol subgraphs.
+- Querying CoW Protocol subgraph.
 - Managing orders on the CoW Protocol.
 - Interacting with CoW Protocol smart contracts.
 - Encoding orders metadata and pinning to CID.
@@ -27,14 +27,14 @@ pip install cow_py
 Here's a simple example to get your hooves dirty:
 
 ```python
-# TODO: this code is aspirational, this API doesn't exist
-from cow_py.order_book import OrderBook
 
-# Initialize the OrderBook
-order_book = OrderBook()
+from cow_py.order_book.api import OrderBookApi, UID
+
+# Initialize the OrderBookApi
+order_book_api = OrderBookApi()
 
 # Fetch and display orders
-orders = order_book.get_orders()
+orders = order_book.get_order_by_uid(UID("0x..."))
 print(orders)
 ```
 
@@ -44,19 +44,47 @@ print(orders)
 - `contracts/`(TODO): A pasture of Smart contract ABIs for interaction.
 - `order_book/`(TODO): Functions to wrangle orders on the CoW Protocol.
 - `order_signing/`(TODO): Tools for signing and validating orders. Anything inside this module should use higher level modules, and the process of actually signing (ie. calling the web3 function to generate the signature, should be handled in contracts, not here).
-- `subgraphs/`(WIP): GraphQL clients for querying CoW Protocol data.
+- `subgraph/`(WIP): GraphQL client for querying CoW Protocol's Subgraph.
 - `web3/`: Web3 providers for blockchain interactions.
 
 ## 🐄 How to Use
 
-### Querying the Subgraph (WIP)
+### Querying the Subgraph
+
+Using the built-in GraphQL client, you can query the CoW Protocol's Subgraph to get real-time data on the CoW Protocol. You can query the Subgraph by using the `SubgraphClient` class and passing in the URL of the Subgraph.
 
 ```python
-from cow_py.subgraphs.queries import TotalsQuery
+from cow_py.subgraph.client import SubgraphClient
 
-totals_query = TotalsQuery()
-totals = await totals_query.execute()
-print(totals)
+url = build_subgraph_url() # Default network is Chain.MAINNET and env SubgraphEnvironment.PRODUCTION
+client = SubgraphClient(url=url)
+
+# Fetch the total supply of the CoW Protocol, defined in a query in cow_py/subgraph/queries
+totals = await client.totals()
+print(totals) # Pydantic model, defined in cow_py/subgraph/graphql_client/{query_name}.py
+```
+
+Or you can leverage `SubgraphClient` to use a custom query and get the results as JSON:
+
+```python
+from pprint import pprint
+from cow_py.subgraph.client import SubgraphClient
+
+url = build_subgraph_url() # Default network is Chain.MAINNET and env SubgraphEnvironment.PRODUCTION
+client = SubgraphClient(url=url)
+
+response = await client.execute(query="""
+            query LastDaysVolume($days: Int!) {
+              dailyTotals(orderBy: timestamp, orderDirection: desc, first: $days) {
+                timestamp
+                volumeUsd
+              }
+            }
+            """, variables=dict(days=2)
+            )
+
+data = client.get_data(response)
+pprint(data)
 ```
 
 ### Signing an Order (TODO)
@@ -75,6 +103,34 @@ signed_order = sign_order(order_details, private_key="your_private_key")
 print(signed_order)
 ```
 
+## 🐄 Development
+
+### 🐄 Tests
+
+Run tests to ensure everything's working:
+
+```bash
+make test # or poetry run pytest
+```
+
+### 🐄 Formatting/Linting
+
+Run the formatter and linter:
+
+```bash
+make format # or ruff check . --fix
+make lint # or ruff format
+```
+
+### 🐄 Codegen
+
+Generate the SDK from the CoW Protocol smart contracts, Subgraph, and Orderbook API:
+
+```bash
+make codegen
+```
+
+
 ## 🐄 Contributing to the Herd
 
 Interested in contributing? Here's how you can help:

cow_py/app_data/app_data_cid.py

@@ -0,0 +1,15 @@
+from typing import Any, Dict
+
+from cow_py.app_data.consts import DEFAULT_IPFS_READ_URI
+from cow_py.app_data.utils import extract_digest, fetch_doc_from_cid
+
+
+class AppDataCid:
+    def __init__(self, app_data_cid: str):
+        self.app_data_cid = app_data_cid
+
+    async def to_doc(self, ipfs_uri: str = DEFAULT_IPFS_READ_URI) -> Dict[str, Any]:
+        return await fetch_doc_from_cid(self.app_data_cid, ipfs_uri)
+
+    def to_hex(self) -> str:
+        return extract_digest(self.app_data_cid)

cow_py/app_data/app_data_doc.py

@@ -0,0 +1,53 @@
+from typing import Dict, Any, TypedDict, Optional
+
+from pinatapy import PinataPy
+
+from cow_py.app_data.consts import DEFAULT_APP_DATA_DOC, LATEST_APP_DATA_VERSION
+from cow_py.app_data.utils import extract_digest, stringify_deterministic
+
+
+class IpfsUploadResult(TypedDict):
+    appData: str
+    cid: str
+
+
+class PinataConfig(TypedDict):
+    pinata_api_key: str
+    pinata_api_secret: str
+
+
+class AppDataDoc:
+    def __init__(self, app_data_doc: Dict[str, Any] = {}):
+        self.app_data_doc = {
+            **DEFAULT_APP_DATA_DOC,
+            **app_data_doc,
+            "version": LATEST_APP_DATA_VERSION,
+        }
+
+    # TODO: make this async
+    def upload_to_ipfs_legacy(
+        self, ipfs_config: PinataConfig
+    ) -> Optional[IpfsUploadResult]:
+        """
+        Uploads a appDocument to IPFS
+
+        @deprecated Pinata IPFS automatically pins the uploaded document using some implicit encoding and hashing algorithm.
+        This method is not used anymore to make it more explicit these parameters and therefore less dependent on the default implementation of Pinata
+
+        @param app_data_doc Document to upload
+        @param ipfs_config keys to access the IPFS API
+
+        @returns the IPFS CID v0 of the content
+        """
+        pinata = PinataPy(
+            ipfs_config.get("pinata_api_key", ""),
+            ipfs_config.get("pinata_api_secret", ""),
+        )
+        pin_response = pinata.pin_json_to_ipfs(
+            stringify_deterministic(self.app_data_doc)
+        )
+        cid = pin_response["IpfsHash"]
+        return {
+            "appData": extract_digest(cid),
+            "cid": cid,
+        }

cow_py/app_data/app_data_hex.py

@@ -0,0 +1,91 @@
+from typing import Dict, Any
+from web3 import Web3
+from multiformats import multibase, CID
+
+from cow_py.app_data.consts import DEFAULT_IPFS_READ_URI, MetaDataError
+from cow_py.app_data.utils import fetch_doc_from_cid
+
+CID_V1_PREFIX = 0x01
+CID_RAW_MULTICODEC = 0x55
+KECCAK_HASHING_ALGORITHM = 0x1B
+KECCAK_HASHING_LENGTH = 32
+CID_DAG_PB_MULTICODEC = 0x70
+SHA2_256_HASHING_ALGORITHM = 0x12
+SHA2_256_HASHING_LENGTH = 32
+
+
+class AppDataHex:
+    def __init__(self, app_data_hex: str):
+        self.app_data_hex = app_data_hex
+
+    def to_cid(self) -> str:
+        cid = self._app_data_hex_to_cid()
+        self._assert_cid(cid)
+        return cid
+
+    def to_cid_legacy(self) -> str:
+        cid = self._app_data_hex_to_cid_legacy()
+        self._assert_cid(cid)
+        return cid
+
+    async def to_doc(self, ipfs_uri: str = DEFAULT_IPFS_READ_URI) -> Dict[str, Any]:
+        try:
+            cid = self.to_cid()
+            return await fetch_doc_from_cid(cid, ipfs_uri)
+        except Exception as e:
+            raise MetaDataError(
+                f"Unexpected error decoding AppData: appDataHex={self.app_data_hex}, message={e}"
+            )
+
+    async def to_doc_legacy(
+        self, ipfs_uri: str = DEFAULT_IPFS_READ_URI
+    ) -> Dict[str, Any]:
+        try:
+            cid = self.to_cid_legacy()
+            return await fetch_doc_from_cid(cid, ipfs_uri)
+        except Exception as e:
+            raise MetaDataError(
+                f"Unexpected error decoding AppData: appDataHex={self.app_data_hex}, message={e}"
+            )
+
+    def _assert_cid(self, cid: str):
+        if not cid:
+            raise MetaDataError(
+                f"Error getting CID from appDataHex: {self.app_data_hex}"
+            )
+
+    def _app_data_hex_to_cid(self) -> str:
+        cid_bytes = self._to_cid_bytes(
+            {
+                "version": CID_V1_PREFIX,
+                "multicodec": CID_RAW_MULTICODEC,
+                "hashing_algorithm": KECCAK_HASHING_ALGORITHM,
+                "hashing_length": KECCAK_HASHING_LENGTH,
+                "multihash_hex": self.app_data_hex,
+            }
+        )
+        return multibase.encode(cid_bytes, "base16")
+
+    def _app_data_hex_to_cid_legacy(self) -> str:
+        cid_bytes = self._to_cid_bytes(
+            {
+                "version": CID_V1_PREFIX,
+                "multicodec": CID_DAG_PB_MULTICODEC,
+                "hashing_algorithm": SHA2_256_HASHING_ALGORITHM,
+                "hashing_length": SHA2_256_HASHING_LENGTH,
+                "multihash_hex": self.app_data_hex,
+            }
+        )
+        return str(CID.decode(cid_bytes).set(version=0))
+
+    def _to_cid_bytes(self, params: Dict[str, Any]) -> bytes:
+        hash_bytes = Web3.to_bytes(hexstr=params["multihash_hex"])
+        cid_prefix = bytes(
+            [
+                params["version"],
+                params["multicodec"],
+                params["hashing_algorithm"],
+                params["hashing_length"],
+            ]
+        )
+        return cid_prefix + hash_bytes

cow_py/app_data/consts.py

@@ -0,0 +1,15 @@
+import os
+
+DEFAULT_IPFS_READ_URI = os.getenv("IPFS_READ_URI", "https://cloudflare-ipfs.com/ipfs")
+
+LATEST_APP_DATA_VERSION = "1.1.0"
+DEFAULT_APP_CODE = "CoW Swap"
+DEFAULT_APP_DATA_DOC = {
+    "appCode": DEFAULT_APP_CODE,
+    "metadata": {},
+    "version": LATEST_APP_DATA_VERSION,
+}
+
+
+class MetaDataError(Exception):
+    pass