Release/1.5.2

.github/workflows/e2e-tests.yml

@@ -0,0 +1,173 @@
+name: E2E Tests
+
+concurrency:
+  group: e2e-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+    branches:
+      - '**'
+    types: [ opened, synchronize, reopened, ready_for_review ]
+
+  workflow_dispatch:
+    inputs:
+      verbose:
+        description: "Output more information when triggered manually"
+        required: false
+        default: ""
+
+env:
+  CARGO_TERM_COLOR: always
+  VERBOSE: ${{ github.event.inputs.verbose }}
+
+# job to run tests in parallel
+jobs:
+  # Looking for e2e tests
+  find-tests:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.pull_request.draft == false }}
+    outputs:
+      test-files: ${{ steps.get-tests.outputs.test-files }}
+    steps:
+      - name: Check-out repository under $GITHUB_WORKSPACE
+        uses: actions/checkout@v4
+
+      - name: Find test files
+        id: get-tests
+        run: |
+          test_files=$(find tests/e2e_tests -name "test*.py" | jq -R -s -c 'split("\n") | map(select(. != ""))')
+          # keep it here for future debug
+          # test_files=$(find tests/e2e_tests -type f -name "test*.py" | grep -E 'test_(hotkeys|staking)\.py$' | jq -R -s -c 'split("\n") | map(select(. != ""))')
+          echo "Found test files: $test_files"
+          echo "test-files=$test_files" >> "$GITHUB_OUTPUT"
+        shell: bash
+
+  # Pull docker image
+  pull-docker-image:
+    runs-on: ubuntu-latest
+    outputs:
+      image-name: ${{ steps.set-image.outputs.image }}
+    steps:
+      - name: Set Docker image tag based on label or branch
+        id: set-image
+        run: |
+          echo "Event: $GITHUB_EVENT_NAME"
+          echo "Branch: $GITHUB_REF_NAME"
+
+          echo "Reading labels ..."
+          if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            labels=$(jq -r '.pull_request.labels[].name' "$GITHUB_EVENT_PATH")
+          else
+            labels=""
+          fi
+
+          image=""
+
+          for label in $labels; do
+            echo "Found label: $label"
+            case "$label" in
+              "subtensor-localnet:main")
+                image="ghcr.io/opentensor/subtensor-localnet:main"
+                break
+                ;;
+              "subtensor-localnet:testnet")
+                image="ghcr.io/opentensor/subtensor-localnet:testnet"
+                break
+                ;;
+              "subtensor-localnet:devnet")
+                image="ghcr.io/opentensor/subtensor-localnet:devnet"
+                break
+                ;;
+            esac
+          done
+
+          if [[ -z "$image" ]]; then
+            # fallback to default based on branch
+            if [[ "${GITHUB_REF_NAME}" == "master" ]]; then
+              image="ghcr.io/opentensor/subtensor-localnet:main"
+            else
+              image="ghcr.io/opentensor/subtensor-localnet:devnet-ready"
+            fi
+          fi
+
+          echo "✅ Final selected image: $image"
+          echo "image=$image" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to GitHub Container Registry
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u $GITHUB_ACTOR --password-stdin
+
+      - name: Pull Docker Image
+        run: docker pull ${{ steps.set-image.outputs.image }}
+
+      - name: Save Docker Image to Cache
+        run: docker save -o subtensor-localnet.tar ${{ steps.set-image.outputs.image }}
+
+      - name: Upload Docker Image as Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: subtensor-localnet
+          path: subtensor-localnet.tar
+
+  # Job to run tests in parallel
+  run-fast-blocks-e2e-test:
+    name: "FB: ${{ matrix.test-file }} / Python ${{ matrix.python-version }}"
+    needs:
+      - find-tests
+      - pull-docker-image
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false  # Allow other matrix jobs to run even if this job fails
+      max-parallel: 32  # Set the maximum number of parallel jobs (same as we have cores in ubuntu-latest runner)
+      matrix:
+        os:
+          - ubuntu-latest
+        test-file: ${{ fromJson(needs.find-tests.outputs.test-files) }}
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - name: Check-out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: install dependencies
+        run: |
+          uv sync --extra dev --dev
+
+      - name: Download Cached Docker Image
+        uses: actions/download-artifact@v4
+        with:
+          name: subtensor-localnet
+
+      - name: Load Docker Image
+        run: docker load -i subtensor-localnet.tar
+
+      - name: Run tests with retry
+        env:
+          LOCALNET_IMAGE_NAME: ${{ needs.pull-docker-image.outputs.image-name }}
+        run: |
+          for i in 1 2 3; do
+            echo "::group::🔁 Test attempt $i"
+            if uv run pytest ${{ matrix.test-file }} -s; then
+              echo "✅ Tests passed on attempt $i"
+              echo "::endgroup::"
+              exit 0
+            else
+              echo "❌ Tests failed on attempt $i"
+              echo "::endgroup::"
+              if [ "$i" -lt 3 ]; then
+                echo "Retrying..."
+                sleep 5
+              fi
+            fi
+          done
+
+          echo "Tests failed after 3 attempts"
+          exit 1

.github/workflows/unit-and-integration-test.yml

@@ -0,0 +1,59 @@
+name: Unit and integration tests checker
+permissions:
+  contents: read
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+
+jobs:
+  unit-and-integration-tests:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      max-parallel: 5
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache venv
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: venv
+          key: v2-${{ runner.os }}-${{ hashFiles('pyproject.toml') }}
+
+      - name: Install deps
+        if: ${{ steps.cache.outputs.cache-hit != 'true' }}
+        run: |
+          python -m venv venv
+          source venv/bin/activate
+          python -m pip install --upgrade pip
+          python -m pip install uv
+          python -m uv sync --extra dev --active
+
+      - name: Unit tests
+        timeout-minutes: 20
+        env:
+          PYTHONUNBUFFERED: "1"
+        run: |
+          source venv/bin/activate
+          python -m uv run pytest -n 2 tests/unit_tests/ --reruns 3
+
+      - name: Integration tests
+        timeout-minutes: 20
+        env:
+          PYTHONUNBUFFERED: "1"
+        run: |
+          source venv/bin/activate
+          python -m uv run pytest -n 2 tests/integration_tests/ --reruns 3

CHANGELOG.md

@@ -1,4 +1,13 @@
 # Changelog
+## 1.5.2 /2025-08-15
+* Improve test workflows by @basfroman in https://github.com/opentensor/async-substrate-interface/pull/173
+* Adds env var support for setting cache size by @thewhaleking in https://github.com/opentensor/async-substrate-interface/pull/174
+* Set env vars as str in unit test by @thewhaleking in https://github.com/opentensor/async-substrate-interface/pull/177
+* DiskCachedAsyncSubstrateInterface: use aiosqlite by @thewhaleking in https://github.com/opentensor/async-substrate-interface/pull/176
+* Additional Debug Logging by @thewhaleking in https://github.com/opentensor/async-substrate-interface/pull/178
+
+
+**Full Changelog**: https://github.com/opentensor/async-substrate-interface/compare/v1.5.1...v1.5.2
 
 ## 1.5.1 /2025-08-05
 * query multiple/decoding fix by @thewhaleking in https://github.com/opentensor/async-substrate-interface/pull/168

README.md

@@ -54,6 +54,49 @@ async def main():
 asyncio.run(main())
 ```
 
+### Caching
+There are a few different cache types used in this library to improve the performance overall. The one with which
+you are probably familiar is the typical `functools.lru_cache` used in `sync_substrate.SubstrateInterface`.
+
+By default, it uses a max cache size of 512 for smaller returns, and 16 for larger ones. These cache sizes are 
+user-configurable using the respective env vars, `SUBSTRATE_CACHE_METHOD_SIZE` and `SUBSTRATE_RUNTIME_CACHE_SIZE`.
+
+They are applied only on methods whose results cannot change — such as the block hash for a given block number 
+(small, 512 default), or the runtime for a given runtime version (large, 16 default).
+
+Additionally, in `AsyncSubstrateInterface`, because of its asynchronous nature, we developed our own asyncio-friendly 
+LRU caches. The primary one is the `CachedFetcher` which wraps the same methods as `functools.lru_cache` does in 
+`SubstrateInterface`, but the key difference here is that each request is assigned a future that is returned when the 
+initial request completes. So, if you were to do:
+
+```python
+bn = 5000
+bh1, bh2 = await asyncio.gather(
+    asi.get_block_hash(bn),
+    asi.get_block_hash(bn)
+)
+```
+it would actually only make one single network call, and return the result to both requests. Like `SubstrateInterface`,
+it also takes the `SUBSTRATE_CACHE_METHOD_SIZE` and `SUBSTRATE_RUNTIME_CACHE_SIZE` vars to set cache size.
+
+The third and final caching mechanism we use is `async_substrate_interface.async_substrate.DiskCachedAsyncSubstrateInterface`,
+which functions the same as the normal `AsyncSubstrateInterface`, but that also saves this cache to the disk, so the cache
+is preserved between runs. This is product for a fairly nice use-case (such as `btcli`). As you may call different networks
+with entirely different results, this cache is keyed by the uri supplied at instantiation of the `DiskCachedAsyncSubstrateInterface`
+object, so `DiskCachedAsyncSubstrateInterface(network_1)` and `DiskCachedAsyncSubstrateInterface(network_2)` will not share
+the same on-disk cache.
+
+As with the other two caches, this also takes `SUBSTRATE_CACHE_METHOD_SIZE` and `SUBSTRATE_RUNTIME_CACHE_SIZE` env vars.
+
+
+### ENV VARS
+The following environment variables are used within async-substrate-interface
+ - NO_CACHE (default 0): if set to 1, when using the DiskCachedAsyncSubstrateInterface class, no persistent on-disk cache will be stored, instead using only in-memory cache.
+ - CACHE_LOCATION (default `~/.cache/async-substrate-interface`): this determines the location for the cache file, if using DiskCachedAsyncSubstrateInterface
+ - SUBSTRATE_CACHE_METHOD_SIZE (default 512): the cache size (either in-memory or on-disk) of the smaller return-size methods (see the Caching section for more info)
+ - SUBSTRATE_RUNTIME_CACHE_SIZE (default 16): the cache size (either in-memory or on-disk) of the larger return-size methods (see the Caching section for more info)
+
+
 ## Contributing
 
 Contributions are welcome! Please open an issue or submit a pull request to the `staging` branch.