Switch default IPFS gateway off ipfs.io and surface gateway errors

[Wizard1209]

Problem

The default gateway https://ipfs.io/ipfs is being retired as a path gateway: scheduled brownouts (HTTP 429 with a text body) since 1 September and final shutdown on 2026-09-21 (gatewaychanges.ipfs.io). ContractMetadata.from_ipfs / ContractTokenMetadata.from_ipfs called .json() without checking the status, so contract.metadata and token_metadata fail with a bare JSONDecodeError: Expecting value — tests/integration_tests/test_token_metadata.py::test_from_storage is already red. The documented escape hatch did not work either: _spawn_context() and ContractInterface.from_micheline dropped ipfs_gateway, so pytezos.using(ipfs_gateway=…).contract(addr) silently fell back to the default.

flowchart LR
    U["contract.metadata"] --> G{gateway}
    G -->|before: ipfs.io 429/HTML| J["JSONDecodeError<br/>(gateway unnamed)"]
    G -->|after: ipfs.filebase.io| M[metadata]
    G -->|after: any failure| E["RequestException:<br/>gateway, CID,<br/>using(ipfs_gateway=…) hint"]
    O["using(ipfs_gateway=X)"] -.->|before: lost in _spawn_context| G
    O ==>|after: inherited| G

Loading

Change

• DEFAULT_IPFS_GATEWAY = 'https://ipfs.filebase.io/ipfs' (200 in ~0.5 s for the test CID today; gateway.pinata.cloud also works but answers in 6–7 s).
• One fetch_ipfs_json() helper for every IPFS fetch: non-2xx, connection errors and non-JSON bodies raise requests.RequestException naming the gateway and CID and pointing at pytezos.using(ipfs_gateway=...); plain HTTP(S) metadata URLs raise HTTPError on non-2xx.
• ipfs_gateway is inherited by using() and by contracts built from a context; documented in the client/contract using() docstrings, quick start and README.
• DEFAULT_IPFS_GATEWAY keeps its name, ipfs_gateway stays a plain string, exceptions stay in the requests hierarchy — no API surface change.

Verification

• make lint clean; tests/unit_tests 774 passed (9 new: default pinned, inheritance through using()/from_michelson, HTTP error / non-JSON body / connection error paths with real requests.Response objects); tests/integration_tests/test_token_metadata.py + test_metadata.py pass, 3 consecutive runs.
• Live: pytezos.using('mainnet').contract('KT1AFA2mwNUMNd4SsujE1YYp29vd8BZejyKW').metadata.name → 'hDAO' via the new default and via a gateway.pinata.cloud override; a dead gateway (https://nonexistent.invalid/ipfs) → RequestException: IPFS gateway \…` failed to serve `Qm…`: …; set another gateway with `pytezos.using(ipfs_gateway=...)``.
• Known limit: a single public gateway with no fallback chain; the error message and the working override are the mitigation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DhHwjW61YpGsStvxYix1ig

[github-actions]

Test Results

    4 files  ±0      4 suites  ±0   2m 33s ⏱️ -2s
1 163 tests +9  1 150 ✅ +9  13 💤 ±0  0 ❌ ±0 
1 187 runs  +9  1 174 ✅ +9  13 💤 ±0  0 ❌ ±0 

Results for commit 608dc80. ± Comparison against base commit 10c7b49.

♻️ This comment has been updated with latest results.