@taquito/tzip16 25.0.0 → 25.1.0-beta0

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,6 +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.
29
+
25
30
  **Create an instance of the `Tzip16Module` and add it as an extension to the `TezosToolkit`**
26
31
 
27
32
  The constructor of the `Tzip16Module` takes an optional `MetadataProvider` as a parameter. When none is passed, the default `MetadataProvider` of Taquito is instantiated, and the default handlers (`HttpHandler`, `IpfsHandler`, and `TezosStorageHandler`) are used.
@@ -40,6 +45,29 @@ Tezos.addExtension(new Tzip16Module());
40
45
  const contract = await Tezos.contract.at("contractAddress", tzip16)
41
46
  ```
42
47
 
48
+ ### Configure an IPFS gateway
49
+
50
+ Pass the gateway hostname without `https://` or `/ipfs/`. Copying `DEFAULT_HANDLERS`
51
+ retains the HTTP, HTTPS, and Tezos storage handlers:
52
+
53
+ ```ts
54
+ import { TezosToolkit } from '@taquito/taquito';
55
+ import { DEFAULT_HANDLERS, IpfsHttpHandler, MetadataProvider, Tzip16Module } from '@taquito/tzip16';
56
+
57
+ const Tezos = new TezosToolkit('https://YOUR_PREFERRED_RPC_URL');
58
+ const handlers = new Map(DEFAULT_HANDLERS);
59
+ handlers.set('ipfs', new IpfsHttpHandler('ipfs.example.com')); // Your gateway hostname
60
+ Tezos.addExtension(new Tzip16Module(new MetadataProvider(handlers)));
61
+ ```
62
+
63
+ 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.
66
+ Applications should catch metadata retrieval failures and let users retry or display
67
+ that metadata is temporarily unavailable.
68
+
69
+ See the [metadata documentation](https://taquito.io/docs/metadata-tzip16/) for more details.
70
+
43
71
  ### Get the contract metadata
44
72
 
45
73
  ```ts
@@ -48,6 +76,18 @@ const metadata = await contract.tzip16().getMetadata();
48
76
 
49
77
  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.
50
78
 
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.
83
+
84
+ If a response cannot be parsed as JSON, `InvalidContractMetadataError` from
85
+ `@taquito/tzip16` includes the metadata URI in its message and retains the response
86
+ 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.
90
+
51
91
  ### Execute off-chain views
52
92
 
53
93
  ```ts
@@ -3,19 +3,33 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.IpfsHttpHandler = void 0;
4
4
  const http_utils_1 = require("@taquito/http-utils");
5
5
  class IpfsHttpHandler {
6
- constructor(ipfsGatheway) {
6
+ constructor(ipfsGateway) {
7
7
  this.httpBackend = new http_utils_1.HttpBackend();
8
- this._ipfsGateway = ipfsGatheway ? ipfsGatheway : 'ipfs.io';
8
+ this._ipfsGateway = ipfsGateway ? ipfsGateway : 'ipfs.filebase.io';
9
9
  }
10
10
  async getMetadata(_contractAbstraction, { location }, _context) {
11
- return this.httpBackend.createRequest({
12
- url: `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`,
13
- method: 'GET',
14
- headers: {
15
- 'Content-Type': 'text/plain; charset=utf-8'
16
- },
17
- json: false
18
- });
11
+ const url = `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`;
12
+ try {
13
+ return await this.httpBackend.createRequest({
14
+ url,
15
+ method: 'GET',
16
+ headers: {
17
+ 'Content-Type': 'text/plain; charset=utf-8',
18
+ },
19
+ json: false,
20
+ });
21
+ }
22
+ catch (error) {
23
+ const guidance = `IPFS metadata retrieval failed at ${url}. Check gateway availability and that the content is retrievable. ` +
24
+ `Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').`;
25
+ if (error instanceof http_utils_1.HttpResponseError) {
26
+ throw new http_utils_1.HttpResponseError(`${guidance} ${error.message}`, error.status, error.statusText, error.body, error.url);
27
+ }
28
+ if (error instanceof http_utils_1.HttpRequestFailed || error instanceof http_utils_1.HttpTimeoutError) {
29
+ error.message = `${guidance} ${error.message}`;
30
+ }
31
+ throw error;
32
+ }
19
33
  }
20
34
  }
21
35
  exports.IpfsHttpHandler = IpfsHttpHandler;
@@ -35,7 +35,14 @@ class MetadataProvider {
35
35
  metadataJSON = JSON.parse(metadata);
36
36
  }
37
37
  catch (ex) {
38
- throw new errors_1.InvalidContractMetadataError(metadata);
38
+ const error = new errors_1.InvalidContractMetadataError(metadata);
39
+ error.message = `Unable to parse metadata from ${uri} as JSON.`;
40
+ if (uriInfo.protocol === 'ipfs') {
41
+ error.message +=
42
+ ' The IPFS gateway may have returned an HTML error or service-worker page.' +
43
+ " Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').";
44
+ }
45
+ throw error;
39
46
  }
40
47
  return {
41
48
  uri,
@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.VERSION = void 0;
4
4
  // IMPORTANT: THIS FILE IS AUTO GENERATED! DO NOT MANUALLY EDIT!
5
5
  exports.VERSION = {
6
- "commitHash": "13f62cd47ea018312f100b660d0225604c757afa",
7
- "version": "25.0.0"
6
+ "commitHash": "a1d45363559ba27998bbc263b69c961710e4710a",
7
+ "version": "25.1.0-beta0"
8
8
  };
@@ -1,4 +1,4 @@
1
- import { HttpBackend } from '@taquito/http-utils';
1
+ import { HttpBackend, HttpResponseError, HttpRequestFailed, HttpTimeoutError } from '@taquito/http-utils';
2
2
  import { Schema, ParameterSchema } from '@taquito/michelson-encoder';
3
3
  import { bytesToString } from '@taquito/utils';
4
4
  import { TaquitoError, ParameterValidationError, TezosToolkitConfigError, InvalidViewParameterError } from '@taquito/core';
@@ -196,19 +196,33 @@ class TezosStorageHandler {
196
196
  }
197
197
 
198
198
  class IpfsHttpHandler {
199
- constructor(ipfsGatheway) {
199
+ constructor(ipfsGateway) {
200
200
  this.httpBackend = new HttpBackend();
201
- this._ipfsGateway = ipfsGatheway ? ipfsGatheway : 'ipfs.io';
201
+ this._ipfsGateway = ipfsGateway ? ipfsGateway : 'ipfs.filebase.io';
202
202
  }
203
203
  async getMetadata(_contractAbstraction, { location }, _context) {
204
- return this.httpBackend.createRequest({
205
- url: `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`,
206
- method: 'GET',
207
- headers: {
208
- 'Content-Type': 'text/plain; charset=utf-8'
209
- },
210
- json: false
211
- });
204
+ const url = `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`;
205
+ try {
206
+ return await this.httpBackend.createRequest({
207
+ url,
208
+ method: 'GET',
209
+ headers: {
210
+ 'Content-Type': 'text/plain; charset=utf-8',
211
+ },
212
+ json: false,
213
+ });
214
+ }
215
+ catch (error) {
216
+ const guidance = `IPFS metadata retrieval failed at ${url}. Check gateway availability and that the content is retrievable. ` +
217
+ `Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').`;
218
+ if (error instanceof HttpResponseError) {
219
+ throw new HttpResponseError(`${guidance} ${error.message}`, error.status, error.statusText, error.body, error.url);
220
+ }
221
+ if (error instanceof HttpRequestFailed || error instanceof HttpTimeoutError) {
222
+ error.message = `${guidance} ${error.message}`;
223
+ }
224
+ throw error;
225
+ }
212
226
  }
213
227
  }
214
228
 
@@ -578,7 +592,14 @@ class MetadataProvider {
578
592
  metadataJSON = JSON.parse(metadata);
579
593
  }
580
594
  catch (ex) {
581
- throw new InvalidContractMetadataError(metadata);
595
+ const error = new InvalidContractMetadataError(metadata);
596
+ error.message = `Unable to parse metadata from ${uri} as JSON.`;
597
+ if (uriInfo.protocol === 'ipfs') {
598
+ error.message +=
599
+ ' The IPFS gateway may have returned an HTML error or service-worker page.' +
600
+ " Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').";
601
+ }
602
+ throw error;
582
603
  }
583
604
  return {
584
605
  uri,
@@ -631,8 +652,8 @@ class Tzip16Module {
631
652
 
632
653
  // IMPORTANT: THIS FILE IS AUTO GENERATED! DO NOT MANUALLY EDIT!
633
654
  const VERSION = {
634
- "commitHash": "13f62cd47ea018312f100b660d0225604c757afa",
635
- "version": "25.0.0"
655
+ "commitHash": "a1d45363559ba27998bbc263b69c961710e4710a",
656
+ "version": "25.1.0-beta0"
636
657
  };
637
658
 
638
659
  export { BigMapContractMetadataNotFoundError, ContractMetadataNotFoundError, DEFAULT_HANDLERS, ForbiddenInstructionInViewCodeError, HttpHandler, InvalidContractMetadataError, InvalidContractMetadataTypeError, InvalidUriError, IpfsHttpHandler, MetadataProvider, MichelsonStorageView, NoParameterExpectedError, ProtocolNotSupportedError, TezosStorageHandler, Tzip16ContractAbstraction, Tzip16Module, UnconfiguredContractMetadataProviderError, UriNotFoundError, VERSION, ViewFactory, ViewImplementationType, calculateSHA256Hash, tzip16 };
@@ -1 +1 @@
1
- {"version":3,"file":"taquito-tzip16.es6.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
1
+ {"version":3,"file":"taquito-tzip16.es6.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
@@ -193,19 +193,33 @@
193
193
  }
194
194
 
195
195
  class IpfsHttpHandler {
196
- constructor(ipfsGatheway) {
196
+ constructor(ipfsGateway) {
197
197
  this.httpBackend = new httpUtils.HttpBackend();
198
- this._ipfsGateway = ipfsGatheway ? ipfsGatheway : 'ipfs.io';
198
+ this._ipfsGateway = ipfsGateway ? ipfsGateway : 'ipfs.filebase.io';
199
199
  }
200
200
  async getMetadata(_contractAbstraction, { location }, _context) {
201
- return this.httpBackend.createRequest({
202
- url: `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`,
203
- method: 'GET',
204
- headers: {
205
- 'Content-Type': 'text/plain; charset=utf-8'
206
- },
207
- json: false
208
- });
201
+ const url = `https://${this._ipfsGateway}/ipfs/${location.substring(2)}/`;
202
+ try {
203
+ return await this.httpBackend.createRequest({
204
+ url,
205
+ method: 'GET',
206
+ headers: {
207
+ 'Content-Type': 'text/plain; charset=utf-8',
208
+ },
209
+ json: false,
210
+ });
211
+ }
212
+ catch (error) {
213
+ const guidance = `IPFS metadata retrieval failed at ${url}. Check gateway availability and that the content is retrievable. ` +
214
+ `Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').`;
215
+ if (error instanceof httpUtils.HttpResponseError) {
216
+ throw new httpUtils.HttpResponseError(`${guidance} ${error.message}`, error.status, error.statusText, error.body, error.url);
217
+ }
218
+ if (error instanceof httpUtils.HttpRequestFailed || error instanceof httpUtils.HttpTimeoutError) {
219
+ error.message = `${guidance} ${error.message}`;
220
+ }
221
+ throw error;
222
+ }
209
223
  }
210
224
  }
211
225
 
@@ -575,7 +589,14 @@
575
589
  metadataJSON = JSON.parse(metadata);
576
590
  }
577
591
  catch (ex) {
578
- throw new InvalidContractMetadataError(metadata);
592
+ const error = new InvalidContractMetadataError(metadata);
593
+ error.message = `Unable to parse metadata from ${uri} as JSON.`;
594
+ if (uriInfo.protocol === 'ipfs') {
595
+ error.message +=
596
+ ' The IPFS gateway may have returned an HTML error or service-worker page.' +
597
+ " Configure a reliable gateway with IpfsHttpHandler('your-gateway-hostname').";
598
+ }
599
+ throw error;
579
600
  }
580
601
  return {
581
602
  uri,
@@ -628,8 +649,8 @@
628
649
 
629
650
  // IMPORTANT: THIS FILE IS AUTO GENERATED! DO NOT MANUALLY EDIT!
630
651
  const VERSION = {
631
- "commitHash": "13f62cd47ea018312f100b660d0225604c757afa",
632
- "version": "25.0.0"
652
+ "commitHash": "a1d45363559ba27998bbc263b69c961710e4710a",
653
+ "version": "25.1.0-beta0"
633
654
  };
634
655
 
635
656
  Object.defineProperty(exports, "InvalidViewParameterError", {
@@ -1 +1 @@
1
- {"version":3,"file":"taquito-tzip16.umd.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
1
+ {"version":3,"file":"taquito-tzip16.umd.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
@@ -1,9 +1,9 @@
1
- import { HttpBackend } from "@taquito/http-utils";
2
- import { ContractAbstraction, ContractProvider, Wallet, Context } from "@taquito/taquito";
3
- import { Handler, Tzip16Uri } from "../metadata-provider";
1
+ import { HttpBackend } from '@taquito/http-utils';
2
+ import { ContractAbstraction, ContractProvider, Wallet, Context } from '@taquito/taquito';
3
+ import { Handler, Tzip16Uri } from '../metadata-provider';
4
4
  export declare class IpfsHttpHandler implements Handler {
5
5
  private _ipfsGateway;
6
6
  httpBackend: HttpBackend;
7
- constructor(ipfsGatheway?: string);
7
+ constructor(ipfsGateway?: string);
8
8
  getMetadata(_contractAbstraction: ContractAbstraction<ContractProvider | Wallet>, { location }: Tzip16Uri, _context: Context): Promise<string>;
9
9
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@taquito/tzip16",
3
- "version": "25.0.0",
3
+ "version": "25.1.0-beta0",
4
4
  "description": "TZIP-16 contract metadata support for Taquito.",
5
5
  "keywords": [
6
6
  "taquito",
@@ -51,12 +51,12 @@
51
51
  ]
52
52
  },
53
53
  "dependencies": {
54
- "@taquito/core": "^25.0.0",
55
- "@taquito/http-utils": "^25.0.0",
56
- "@taquito/michelson-encoder": "^25.0.0",
57
- "@taquito/rpc": "^25.0.0",
58
- "@taquito/taquito": "^25.0.0",
59
- "@taquito/utils": "^25.0.0",
54
+ "@taquito/core": "^25.1.0-beta0",
55
+ "@taquito/http-utils": "^25.1.0-beta0",
56
+ "@taquito/michelson-encoder": "^25.1.0-beta0",
57
+ "@taquito/rpc": "^25.1.0-beta0",
58
+ "@taquito/taquito": "^25.1.0-beta0",
59
+ "@taquito/utils": "^25.1.0-beta0",
60
60
  "bignumber.js": "^10.0.2",
61
61
  "crypto-js": "^4.2.0"
62
62
  },