From 3efada94cf28abe036ec2319f346cdd13de64bc9 Mon Sep 17 00:00:00 2001 From: Mike Date: Tue, 25 Aug 2026 10:27:57 +0300 Subject: [PATCH] feat: publish the specification as a site TORPC is meant to be implemented by anyone, but the only readable version of it today is either a repository of markdown files or a page inside one vendor's product documentation. Both are the wrong shape for a specification another provider is supposed to adopt. This renders the repository with Jekyll and serves it from GitHub Pages, so the canonical home is a neutral URL. The specification itself does not move: index.md is a front door that links to the documents, and jekyll-relative-links keeps the in-repo markdown links working on the site. The landing page states plainly that the conformance suite holds one case and that no implementation, ours included, may call itself conformant yet. The quickstart on it was executed against production while writing: the keyless Monad endpoint answers with token-tier: 2 and a decimal, renamed body. Enabling Pages on this repository is a settings change that needs admin. Co-Authored-By: Claude Opus 5 (1M context) --- .github/workflows/pages.yml | 37 +++++++++++++++++++++ _config.yml | 15 +++++++++ index.md | 64 +++++++++++++++++++++++++++++++++++++ 3 files changed, 116 insertions(+) create mode 100644 .github/workflows/pages.yml create mode 100644 _config.yml create mode 100644 index.md diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..376995f --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,37 @@ +name: Spec site + +# The specification is the markdown in this repository. This renders it, so the +# canonical home of TORPC is a site anyone can read without cloning a repo, and +# without landing inside a vendor's product documentation. +on: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/configure-pages@v5 + - uses: actions/jekyll-build-pages@v1 + - uses: actions/upload-pages-artifact@v4 + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v4 diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..cdd48fb --- /dev/null +++ b/_config.yml @@ -0,0 +1,15 @@ +title: TORPC +description: Token Optimized RPC: an opt-in compression layer for blockchain JSON-RPC +theme: jekyll-theme-primer +# Rewrites links between .md files to their built .html counterparts, so the +# markdown in specs/ stays readable in the repo and works on the site. +plugins: + - jekyll-relative-links +relative_links: + enabled: true + collections: true +exclude: + - conformance/ + - CONTRIBUTING.md + - SECURITY.md + - TRADEMARKS.md diff --git a/index.md b/index.md new file mode 100644 index 0000000..252a630 --- /dev/null +++ b/index.md @@ -0,0 +1,64 @@ +--- +title: TORPC +--- + +# TORPC + +**TORPC (Token Optimized RPC) is an opt-in compression layer for blockchain JSON-RPC.** A client +asks for a compression tier with one request header, and the server states the tier it actually +applied with one response header. No new methods, no envelope, no new error codes, and no change to +JSON-RPC 2.0 itself. + +JSON-RPC was designed for clients that render into an interface. A fast growing class of consumer is +an LLM-driven agent that pays per token and has a finite context window. For that consumer most of a +raw response is waste: hex padding, service fields it never reads, and undecoded calldata it cannot +interpret. TORPC does that work once, on the way out. + +The specification is published under **CC0 1.0**, so anyone may implement it, and implementing it +requires no permission from and no relationship with any provider. + +## Try it in one command + +Any endpoint that implements TORPC answers an ordinary JSON-RPC request. This one is public and +needs no key: + +```bash +curl -sS -i -X POST "https://rpc.ankr.com/monad_mainnet" \ + -H 'Content-Type: application/json' \ + -H 'Accept-Token-Tier: 2' \ + -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["latest",false]}' +``` + +The response carries `token-tier: 2`, and the body comes back renamed and in decimal: + +```json +{"id":1,"jsonrpc":"2.0","result":{"base_fee_per_gas":"100000000000","block":"90785283", +"gas_limit":"150000000","gas_used":"22917133","size":"800","timestamp":"1785159403"}} +``` + +## The documents + +| Document | What it is | Status | +| --- | --- | --- | +| [EVM RPC Compression v1](specs/evm-v1.md) | The normative specification | Draft. Tiers 1 and 2 normative, tiers 3 and above reserved | +| [Per-method mappings](specs/methods/) | What each method's response becomes at each tier | 23 methods carry a v1 mapping, described by 8 documents | +| [Conformance suite](https://github.com/w3tech/torpc/tree/main/conformance) | Golden cases an implementation must reproduce | Scaffold v0.0.1, one case. Not a coverage claim | +| [Whitepaper](https://github.com/w3tech/torpc/tree/main/whitepaper) | Design rationale and measurements | Draft | +| [Governance](GOVERNANCE.md) | How the specification changes | Current | +| [Decisions](DECISIONS.md) | Why the design is what it is | Current | + +## Nobody is conformant yet + +The conformance suite holds exactly one golden case. Until it covers the specification, **no +implementation, including Ankr's, may describe itself as TORPC conformant.** The word is reserved +for something the suite can demonstrate. + +## Implementations + +- [w3tech/torpc-js](https://github.com/w3tech/torpc-js) is the reference decoder, the typed ruleset + and the benchmark harness, under Apache-2.0. +- Ankr RPC applies tiers 1 and 2 on its endpoints. It is one implementation of this specification, + not the specification itself. + +Building another one? Open an issue in [w3tech/torpc](https://github.com/w3tech/torpc). Interop +reports are the most useful thing the project can receive right now.