cf-token-metadata-registry 2.0.2
Note
Nothing changes yet for clients of https://tokens.cardano.org: it keeps running 1.7.0 until March 31, 2027.
2.x runs alongside it at https://v2.tokens.cardano.org, so you can test your client against it now and migrate at your own pace. See the migration timeline.
Caution
2.0.2 is a mandatory release for everyone who runs the registry.
- Running 2.0.0 or 2.0.1: upgrade to 2.0.2. No resync is needed.
- Running 1.7.0: there is no 1.7.x patch. Either migrate to 2.0.2, or set the JVM flag yourself until you do; see Running 1.7.0.
- API clients have nothing to do: the API is the same as in 2.0.1.
2.0.2 is a security patch release on top of 2.0.1: its Docker images carry a mitigation for the reported CVE-2026-114938, a JDK issue in the AVX-512 java.util.Base64 decoder. There are no other changes; the API and the database are the same as in 2.0.1.
Upgrading from 1.7.0? Upgrade straight to 2.0.2. The 2.0.1 release notes describe the whole change from 1.7.0, and all of it applies to 2.0.2.
Security: CVE-2026-114938 mitigation
- The issue: a reported vulnerability in the JDK's AVX-512 intrinsic for
java.util.Base64decoding. It is unconfirmed as of 2026-11-18, and no fixed JDK 25 build exists yet. - Where the registry uses it: it decodes base64 when it validates CIP-26 logos, which come from the GitHub registry and are untrusted input, and encodes it when it serves a CIP-26 logo in the V2
metadatablock. - The mitigation: the JVM images set
JDK_JAVA_OPTIONS="-XX:-UseBASE64Intrinsics", sojava.util.Base64runs in plain Java instead of the JIT intrinsic. It is built into the images, so every deployment gets it: the bundled Docker Compose files, Helm charts, Kubernetes manifests anddocker runalike. On startup the JVM logsNOTE: Picked up JDK_JAVA_OPTIONS: -XX:-UseBASE64Intrinsics(#181, #182). - If you set
JDK_JAVA_OPTIONSyourself, your value replaces the image's: keep-XX:-UseBASE64Intrinsicsin it.JAVA_OPTSis not affected. - No behaviour change: CIP-26 logos are validated as before, with the same
invalid_base64andtoo_largeerrors. The plain-Java path costs a little CPU on base64, which the registry only uses for CIP-26 logos. - The native image (experimental, see Known Issues) has no JIT, so it does not use the intrinsic and needs no mitigation.
- The mitigation will be removed once a JDK with the fix is released.
Running 1.7.0
1.7.0 is exposed too, and gets no patch release. Until you migrate to 2.0.2, pass the flag yourself to every JVM container of the registry: the API (api, and api-ro if you run it) and the CIP-26 sync job (cardanofoundation/cf-token-metadata-registry-job). With the bundled Docker Compose file, add it to the API services:
services:
api:
environment:
JDK_JAVA_OPTIONS: "-XX:-UseBASE64Intrinsics"
api-ro:
environment:
JDK_JAVA_OPTIONS: "-XX:-UseBASE64Intrinsics"Elsewhere, use docker run -e JDK_JAVA_OPTIONS=-XX:-UseBASE64Intrinsics ..., or an env entry in Kubernetes. Use JDK_JAVA_OPTIONS, not JAVA_OPTS: the 1.7.0 images start with ENTRYPOINT ["java", "-jar", "app.jar"], which never reads JAVA_OPTS, while the java launcher reads JDK_JAVA_OPTIONS itself. Check that each JVM logs NOTE: Picked up JDK_JAVA_OPTIONS: -XX:-UseBASE64Intrinsics on startup.
Migration timeline
To give ecosystem partners time to adapt, version 1.7.0 of the registry will stay available on https://tokens.cardano.org for a grace period of 4 months (until March 31, 2027), after which tokens.cardano.org will be upgraded to 2.x. The new version is currently accessible at https://v2.tokens.cardano.org. Note that the preprod environment is already running 2.x exclusively and will not run both versions concurrently. Please complete your migration to version 2.0.2 before the grace period ends.
To migrate: the endpoints stay the same (V1 /metadata/..., V2 /api/v2/subjects/...), so point your client at https://v2.tokens.cardano.org and check the two breaking changes from 1.7.0, both in V2 (V1 is unchanged): name and description can be null, and the CIP-26 logo in the V2 metadata block is base64, no longer hex. Everything else is additive. Details: 2.0.1 release notes.
Upgrading
- From 2.0.1: pull the 2.0.2 images. No resync, no configuration change, no API change.
- From 1.7.0: a full resync from an empty database is required; see For operators in the 2.0.1 release notes.
Docker images (pin a version; a release tag moves latest and latest-native on Docker Hub):
- API, JVM:
cardanofoundation/cf-token-metadata-registry-api:2.0.2 - API, GraalVM native, experimental and not supported yet:
cardanofoundation/cf-token-metadata-registry-api:2.0.2-native. It does not start; see Known Issues. Use the JVM image. - CIP-26 sync job:
cardanofoundation/cf-token-metadata-registry-job:2.0.2
Known Issues
The GraalVM native image is experimental and not supported yet. Use the JVM image. Its known problems are unchanged from 2.0.1:
- It does not start: jOOQ's static initializer fails, caused by native-maven-plugin 0.11.5 (#152); with 0.10.5 it starts, but the CIP-26 sync then times out, likely JGit 7.8.1 (#175).
- It needs an x86-64-v3 CPU (AVX2, Haswell or newer), although it is built for any x86-64 CPU (#176).
- It cannot run in read-only mode (#90).
Full changelog: 2.0.1...2.0.2