> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/docs/guides/ci-cache-strategy.md).

# CI Cache Strategy

> How Lithosphere CI pipelines use caching to keep PR times under 10-15 minutes.

## Cache Layers

| Layer           | Tool                                    | Key                               | TTL          | Workflow            |
| --------------- | --------------------------------------- | --------------------------------- | ------------ | ------------------- |
| pnpm store      | `actions/cache`                         | `os-pnpm-store-{lockfile hash}`   | 7 days (LRU) | ci.yaml             |
| node\_modules   | `actions/cache`                         | `os-node-modules-{lockfile hash}` | 7 days (LRU) | ci.yaml             |
| Turborepo local | `actions/cache`                         | `os-turbo-{sha}`                  | 7 days (LRU) | ci.yaml             |
| Docker layers   | BuildKit GHA cache                      | `type=gha`                        | repo-scoped  | publish-images.yaml |
| Hardhat cache   | pnpm store (includes hardhat cache dir) | lockfile-based                    | per-install  | ci-contracts.yaml   |
| Foundry cache   | Not cached in CI (fast enough)          | N/A                               | N/A          | ci-contracts.yaml   |

## How It Works

### pnpm Store Cache

The pnpm content-addressable store is cached between runs. On cache hit, `pnpm install --frozen-lockfile` resolves in \~3 seconds instead of 30+.

```yaml
- name: Get pnpm store directory
  run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV

- uses: actions/cache@v4
  with:
    path: ${{ env.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: ${{ runner.os }}-pnpm-store-
```

### Turborepo Cache

Turbo hashes each task's inputs (source files, dependencies, env vars) and skips unchanged packages. The `.turbo` directory is cached between CI runs so even cross-PR builds benefit from prior results.

### Docker Layer Cache

`docker/build-push-action` uses GitHub Actions cache backend (`type=gha`) for BuildKit layer caching. This makes incremental image builds 2-5x faster.

### Hardhat Compilation Cache

Hardhat's `cache/` directory stores compilation results. When source files haven't changed, `hardhat compile` is a no-op. This is included in the pnpm workspace install and cached via node\_modules.

## Cache Invalidation

* **pnpm store**: Invalidated when any `pnpm-lock.yaml` changes (new deps)
* **node\_modules**: Same as pnpm store
* **Turbo**: Keyed by commit SHA; `restore-keys` prefix allows partial hits from prior commits
* **Docker**: Invalidated per-layer when Dockerfile or COPY sources change

## Parallelization Strategy

The CI is split into independent parallel jobs:

```
ci.yaml:         build ─┬─ test
                        ├─ typecheck
                 lint ──┘
                 gitleaks (independent)

ci-contracts:    compile ─┬─ test
                          ├─ gas-report
                          ├─ slither
                          └─ abi-export
                 lint (independent)

ci-sdk:          Node 18 ┐
                 Node 20 ├─ parallel matrix
                 Node 22 ┘
                 size-check (independent)
```

## Flaky Test Quarantine

When a test is identified as flaky:

1. Add `skip` annotation with a tracking issue link
2. Move to a `__flaky__/` directory (excluded from CI by default)
3. Run flaky tests in a separate non-blocking job
4. Fix and re-enable within one sprint

Turbo's `inputs` config means only changed packages re-run tests, which naturally reduces flake exposure.

## Target CI Times

| Pipeline       | Target   | Mechanism                          |
| -------------- | -------- | ---------------------------------- |
| Contracts (PR) | < 10 min | Parallel compile/test/lint/slither |
| Services (PR)  | < 15 min | Turbo cache + parallel jobs        |
| SDK (PR)       | < 5 min  | Fast tsup build, small test suite  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://whitepaper.litho.ai/docs/guides/ci-cache-strategy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.