@taquito/tzip16 25.1.1 → 25.2.0-beta1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,10 +22,11 @@ npm i --save @taquito/taquito
22
22
 
23
23
  ## Usage
24
24
 
25
- **For production applications that retrieve IPFS metadata, configure a reliable gateway.**
26
- The shared public default, `ipfs.filebase.io`, is provided for convenience and may be
27
- rate-limited or unavailable. Use a dedicated or application-controlled gateway that
28
- can retrieve your content and supports CORS for browser applications.
25
+ **For production applications that retrieve IPFS metadata, configure a paid gateway service with an SLA or a self-hosted HTTPS IPFS gateway.**
26
+ The shared public gateways are best-effort and may be rate-limited, slow, or
27
+ unavailable. The default handler tries `ipfs.filebase.io`, then `gateway.pinata.cloud`
28
+ in order. Use a dedicated or self-hosted HTTPS gateway that supports raw block requests
29
+ (`?format=raw`), can retrieve your content, and supports CORS for browser applications.
29
30
 
30
31
  **Create an instance of the `Tzip16Module` and add it as an extension to the `TezosToolkit`**
31
32
 
@@ -61,11 +62,29 @@ Tezos.addExtension(new Tzip16Module(new MetadataProvider(handlers)));
61
62
  ```
62
63
 
63
64
  An override changes retrieval of `ipfs://` metadata. It does not rewrite HTTP URLs
64
- stored in contracts or URLs inside the returned metadata. Taquito does not
65
- automatically switch gateways when a request fails, or retry HTTP 429/5xx responses.
65
+ stored in contracts or URLs inside the returned metadata. An explicit gateway
66
+ override uses that gateway alone. Without an override, HTTP errors, timeouts,
67
+ integrity failures, and invalid JSON cause the next default gateway to be tried.
66
68
  Applications should catch metadata retrieval failures and let users retry or display
67
69
  that metadata is temporarily unavailable.
68
70
 
71
+ Each gateway has a 10-second total deadline (`10000` ms), including block retrieval and body
72
+ reads. The second constructor argument can change it, for example
73
+ `new IpfsHttpHandler('ipfs.example.com', 15000)` for 15 seconds.
74
+
75
+ ### IPFS verification
76
+
77
+ The built-in handler verifies every retrieved block against its CID before UnixFS
78
+ decoding. It supports CIDv0/CIDv1 raw and dag-pb UnixFS data with SHA-256 or SHA-512
79
+ multihashes, including directory paths and multi-block files. Files are reassembled
80
+ before UTF-8 decoding and before an optional outer `sha256://` check. Gateways
81
+ that cannot serve raw blocks fail; there is no fallback to unverified JSON.
82
+
83
+ Retrieval is bounded to 2 MiB per block, 32 MiB of downloaded blocks and reconstructed
84
+ metadata per gateway, and 1,024 block reads. Unsupported codecs, hashes, or metadata
85
+ exceeding these bounds are rejected. Custom protocol handlers are responsible for
86
+ enforcing their own content-addressed integrity checks.
87
+
69
88
  See the [metadata documentation](https://taquito.io/docs/metadata-tzip16/) for more details.
70
89
 
71
90
  ### Get the contract metadata
@@ -76,17 +95,29 @@ const metadata = await contract.tzip16().getMetadata();
76
95
 
77
96
  The `getMetadata` method returns an object which contains the URI, the metadata in JSON format, an optional SHA256 hash of the metadata, and an optional integrity check result.
78
97
 
79
- On failure, catch `HttpResponseError`, `HttpRequestFailed`, or `HttpTimeoutError`
80
- from `@taquito/http-utils`. IPFS failures include gateway context and configuration
81
- guidance in the message; the existing status, URL, timeout, cause, and transport
82
- classification fields remain available on their respective error types.
98
+ The default metadata provider rejects `sha256://` hash mismatches with
99
+ `MetadataHashMismatchError` before returning metadata or creating off-chain views.
100
+ The error includes the URI, expected hash, and actual hash. A successful SHA-256
101
+ check returns `integrityCheckResult: true`; URIs without a SHA-256 wrapper leave
102
+ that field undefined. Hashes must contain 64 hexadecimal digits; uppercase and
103
+ lowercase digits are accepted. This changes the previous behavior, which returned
104
+ metadata even when `integrityCheckResult` was false.
105
+
106
+ With an explicit gateway, HTTP failures retain `HttpResponseError`,
107
+ `HttpRequestFailed`, or `HttpTimeoutError` from `@taquito/http-utils`, including
108
+ their existing diagnostic fields. When all default gateways fail, `IpfsGatewayError`
109
+ from `@taquito/tzip16` contains the individual failures in its `errors` array.
110
+ IPFS failures include gateway context and configuration guidance in the message.
83
111
 
84
112
  If a response cannot be parsed as JSON, `InvalidContractMetadataError` from
85
113
  `@taquito/tzip16` includes the metadata URI in its message and retains the response
86
114
  text in `invalidMetadata`. For IPFS this URI is the original `ipfs://` address.
87
- A gateway may have returned an HTML page instead of metadata. Prefer error types
88
- and diagnostic fields over matching message text. TZIP-12 retains its existing
89
- contract-metadata fallback behavior.
115
+ IPFS responses are verified before JSON parsing, so a substituted HTML page will
116
+ normally fail the CID check first. Calling `IpfsHttpHandler.getMetadata()` directly
117
+ returns verified, JSON-parseable text. Prefer error types and diagnostic fields over
118
+ matching message text. TZIP-12 retains its existing contract-metadata fallback behavior.
119
+
120
+ Custom `IpfsHttpHandler.httpBackend` subclasses must override `createRequestBytes()` to customize binary block requests. An override of `createRequest()` alone no longer intercepts IPFS retrieval.
90
121
 
91
122
  ### Execute off-chain views
92
123