@bifrostwallet/assets 0.0.0-stage → 0.0.1-beta

package/README.md

@@ -1,3 +1,84 @@
-# Temporary Holding Version
+# @bifrostwallet/assets
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Curated assets for Bifrost Wallet: providers, validators, tokens, dapps, and more as the catalog grows.
+
+Zero runtime dependencies: JSON data plus pure lookup helpers. Logos are **not** bundled; published `logoURL` values are absolute (GitHub raw by default). For production or sensitive apps, mirror logos to your own bucket or CDN.
+
+## Install
+
+```bash
+npm install @bifrostwallet/assets
+```
+
+Or install with Yarn or pnpm using the same package name.
+
+## Quick start
+
+```js
+const {
+  getProvider,
+  getListedProviders,
+  findProviderByValidator,
+  getNativeToken,
+  getToken,
+} = require("@bifrostwallet/assets");
+
+// Chain ids are CAIP-2 (e.g. "eip155:14", "eip155:19")
+const bifrost = getProvider("eip155:14", "0x1650d2760baee638c034200dedcbe17b050d0364");
+const logoURL = bifrost.logoURL; // already absolute
+const byNode = findProviderByValidator(
+  "eip155:14",
+  "NodeID-5oLazJm5PtV8JFb2GpzuCVMZdi1GxkwYP",
+); // → Bifrost Wallet
+const picker = getListedProviders("eip155:14"); // listed: true only
+
+const flr = getNativeToken("eip155:14"); // native gas token (address === null)
+// WNAT / WFLR on Flare (lookup is case-insensitive)
+const wflr = getToken("eip155:14", "0x1D80c49BbBCd1C0911346656B529DF9E5c2F783d");
+```
+
+TypeScript / ESM:
+
+```ts
+import {
+  getProvider,
+  getListedProviders,
+  findProviderByValidator,
+  getNativeToken,
+} from "@bifrostwallet/assets";
+
+const bifrost = getProvider("eip155:14", "0x1650d2760baee638c034200dedcbe17b050d0364");
+const listed = getListedProviders("eip155:14");
+const native = getNativeToken("eip155:14");
+```
+
+## Provider picker vs confirmations
+
+| UI | Rule |
+| --- | --- |
+| Provider **picker** / discovery | Show only `listed: true` (`getListedProviders`) |
+| Already-selected provider (confirmations, details) | Show the entry even if `listed` is false (`getProvider` / `getProviders`) |
+
+## Without NPM
+
+**Not recommended.** Prefer the NPM package. GitHub raw is a fallback only:
+
+```
+https://raw.githubusercontent.com/bifrostwallet/assets/main/data/providers/eip155-14/all.json
+https://raw.githubusercontent.com/bifrostwallet/assets/main/data/tokens/eip155-14/all.json
+```
+
+Relative `logoURL` values resolve against:
+
+```
+https://raw.githubusercontent.com/bifrostwallet/assets/main/data/
+```
+
+For production or sensitive applications, mirror logos to your own bucket or CDN instead of relying on GitHub’s CDN.
+
+## Docs
+
+Full integrator guide (data model, media format, optional CDN manifest):  
+[docs.bifrostwallet.com: Consuming Assets](https://docs.bifrostwallet.com/list/consuming-assets)
+
+Source of truth: [github.com/bifrostwallet/assets](https://github.com/bifrostwallet/assets)

package/index.d.ts

@@ -0,0 +1,142 @@
+// @bifrostwallet/assets — generated file, do not edit.
+
+export interface ProviderInfo {
+  name: string;
+  description: string;
+  websiteURL: string;
+  links: {
+    github?: string;
+    x?: string;
+    discord?: string;
+    telegram?: string;
+    youtube?: string;
+    reddit?: string;
+    linkedin?: string;
+    tiktok?: string;
+  };
+  /**
+   * Absolute logo URL in published lists (GitHub raw by default).
+   * info.json in git keeps a relative path; resolveAssetURL() still works for either form.
+   */
+  logoURL: string;
+  /** SHA-256 of the logo file, covered by provider signatures */
+  logoHash: string;
+  identityAddress: string;
+  delegationAddress: string;
+  signingPolicyAddress: string;
+  submitAddress: string;
+  submitSignaturesAddress: string;
+  publicKey: string;
+  /** Avalanche-style NodeIDs of the provider's validators */
+  validators: string[];
+  /** Curator-granted listing flag for Bifrost Wallet UIs */
+  listed: boolean;
+  /** Flare FTSO Management Group membership (synced on-chain) */
+  managementGroup: boolean;
+  /** Optional domain linkage, refreshed nightly from websiteURL */
+  domainLinked: boolean;
+  /** Same brand present on both Flare and Songbird in this catalog (curator-reviewed) */
+  dualNetwork: boolean;
+  /** Earliest known provider activity on this network (write-once, curator-managed) */
+  firstTransaction?: {
+    hash: string;
+    blockNumber: number;
+    /** ISO 8601 UTC */
+    timestamp: string;
+  };
+}
+
+export interface TokenInfo {
+  name: string;
+  symbol: string;
+  decimals: number;
+  /** Lowercase 0x… for contracts; null for the chain native gas token */
+  address: string | null;
+  /** Always present — string CoinGecko id, or null when unmapped / unpriced */
+  coingeckoId: string | null;
+  logoURL: string;
+  logoHash: string;
+}
+
+export interface TokenBlocklistEntry {
+  chainPath: string;
+  address: string;
+  identifier: string;
+}
+
+export interface ManifestSectionHashes {
+  contentHash: string;
+  chains?: Record<string, string>;
+}
+
+/** CAIP-2 chain id, e.g. "eip155:14" or "eip155:19" */
+export type ChainId = string;
+
+export declare const DEFAULT_ASSET_BASE_URL: string;
+export declare const PROVIDER_CHAIN_IDS: string[];
+export declare const TOKEN_CHAIN_IDS: string[];
+/** Ed25519 SPKI PEM for verifying CDN manifest.json (empty string if key not generated yet) */
+export declare const MANIFEST_PUBLIC_KEY: string;
+
+/** Section content hashes baked into this package release (compare to CDN manifest) */
+export declare function getSectionHashes(): {
+  providers?: ManifestSectionHashes;
+  contracts?: ManifestSectionHashes;
+  dapps?: ManifestSectionHashes;
+  tokens?: ManifestSectionHashes;
+};
+
+export interface AssetsManifestBody {
+  generatedAt: string;
+  sections: {
+    providers?: ManifestSectionHashes;
+    contracts?: ManifestSectionHashes;
+    dapps?: ManifestSectionHashes;
+    tokens?: ManifestSectionHashes;
+  };
+}
+
+export interface AssetsManifest extends AssetsManifestBody {
+  signature: string;
+}
+
+/** Canonical JSON string signed by the Bifrost Ed25519 publish key */
+export declare function canonicalManifestBody(body: AssetsManifestBody): string;
+/**
+ * Verify CDN manifest with node:crypto Ed25519.
+ * Defaults to MANIFEST_PUBLIC_KEY when publicKeyPem is omitted.
+ */
+export declare function verifyManifest(
+  manifest: AssetsManifest,
+  publicKeyPem?: string
+): boolean;
+
+/** All curated providers for a chain (throws on unknown chain) */
+export declare function getProviders(chainId: ChainId): ProviderInfo[];
+/** A single provider by identity address (case-insensitive), or null */
+export declare function getProvider(
+  chainId: ChainId,
+  identityAddress: string
+): ProviderInfo | null;
+/** Providers listed in Bifrost Wallet UIs */
+export declare function getListedProviders(chainId: ChainId): ProviderInfo[];
+/** Providers that are current FTSO Management Group members */
+export declare function getManagementGroupProviders(chainId: ChainId): ProviderInfo[];
+/** The provider operating a validator NodeID, or null */
+export declare function findProviderByValidator(
+  chainId: ChainId,
+  nodeId: string
+): ProviderInfo | null;
+/** All curated tokens for a chain (throws on unknown chain) */
+export declare function getTokens(chainId: ChainId): TokenInfo[];
+/** A single ERC-20 by address (case-insensitive), or null */
+export declare function getToken(chainId: ChainId, address: string): TokenInfo | null;
+/** Native gas token entry for a chain, or null */
+export declare function getNativeToken(chainId: ChainId): TokenInfo | null;
+/** Curated token blocklist entries */
+export declare function getTokenBlocklist(): TokenBlocklistEntry[];
+/**
+ * Joins a relative (or already-absolute) asset path to a base URL.
+ * Defaults to the base baked into this package build (ASSET_BASE_URL / GitHub raw).
+ */
+export declare function resolveAssetURL(relativePath: string, baseURL?: string): string;

package/index.js

@@ -0,0 +1,228 @@
+"use strict";
+// @bifrostwallet/assets — generated file, do not edit.
+
+const providersByChain = {
+  "eip155-14": require("./providers/eip155-14.json"),
+  "eip155-19": require("./providers/eip155-19.json"),
+};
+
+const tokensByChain = {
+  "eip155-1": require("./tokens/eip155-1.json"),
+  "eip155-10": require("./tokens/eip155-10.json"),
+  "eip155-11155111": require("./tokens/eip155-11155111.json"),
+  "eip155-114": require("./tokens/eip155-114.json"),
+  "eip155-137": require("./tokens/eip155-137.json"),
+  "eip155-14": require("./tokens/eip155-14.json"),
+  "eip155-16": require("./tokens/eip155-16.json"),
+  "eip155-19": require("./tokens/eip155-19.json"),
+  "eip155-250": require("./tokens/eip155-250.json"),
+  "eip155-4002": require("./tokens/eip155-4002.json"),
+  "eip155-420": require("./tokens/eip155-420.json"),
+  "eip155-42161": require("./tokens/eip155-42161.json"),
+  "eip155-42163": require("./tokens/eip155-42163.json"),
+  "eip155-5": require("./tokens/eip155-5.json"),
+  "eip155-50": require("./tokens/eip155-50.json"),
+  "eip155-51": require("./tokens/eip155-51.json"),
+  "eip155-56": require("./tokens/eip155-56.json"),
+  "eip155-80001": require("./tokens/eip155-80001.json"),
+  "eip155-8453": require("./tokens/eip155-8453.json"),
+  "eip155-84532": require("./tokens/eip155-84532.json"),
+  "eip155-97": require("./tokens/eip155-97.json"),
+  "eip155-998": require("./tokens/eip155-998.json"),
+  "eip155-999": require("./tokens/eip155-999.json"),
+};
+
+const tokenBlocklist = require("./tokens/blocklist.json");
+
+/** Bundled snapshot of section content hashes (same algorithm as CDN manifest.json). */
+const SECTION_HASHES = {
+  "providers": {
+    "contentHash": "34b17e0206215f8e821e2ee0badb4e5dad9b5aff61e01412703129bdaa4d309d",
+    "chains": {
+      "eip155-14": "92226cb84bebf225fcbcf4af5c16e18c7935e9e0b549992bcea99dc564384ce2",
+      "eip155-19": "8bed4749411b716feedc0861ff2ca6f9d002f257eff05540e49142d4c2b24605"
+    }
+  },
+  "tokens": {
+    "contentHash": "1e6da50ba69c9895e1cb1774908f9c56de41956c39b1a2c1d244cd710dd2212b",
+    "chains": {
+      "eip155-1": "63ff7bf33ea031f7765cf73f981f345e77e5d761824b097fea7971dee7867708",
+      "eip155-10": "9d6d559be18b4b2a2516ca66d975f17dc804a50d5c9a8d6bdc466266ec4c5a33",
+      "eip155-11155111": "a8682c3da1a11942e413ddb5c7736c34a0a3b77aa5df6a6e9b47e56a567999fc",
+      "eip155-114": "5b2e1503b845d5d1a2299f64f72b4786b834b694da36c1c15af5f71371029f43",
+      "eip155-137": "e5e5047ddf758dad58cd4f2cd6599c855f731fa5de8c8f6ac56f2fc54644f0eb",
+      "eip155-14": "5a8212c8263bbb1a787d4463bf097c29b56fa0e14b685053be9805cd90725d4a",
+      "eip155-16": "ee5224b4853d61665fa89cbb9df5feb1d75f15843eaac4dd56254019d9df50a6",
+      "eip155-19": "a42bfa17e774af50d15ffcd08f60531fcdc0fbea9882d98f8f721f177f7daa7b",
+      "eip155-250": "20abc5f8d9de7210a5318edb7fef7a6812450c69f40ce22becc5c193bed640e1",
+      "eip155-4002": "217c1f2f92a1674e802adb1e31e3bee52380da76fe14bafc82397cf08fd5e8c3",
+      "eip155-420": "cec0b2a52bc6daa2188e2c25cadd8226f40013421f820cf455e77e3617d6cf59",
+      "eip155-42161": "29f5eebb42a85b729b974fc5483ccf28967853618422287e6916d993101b9882",
+      "eip155-42163": "c91b6e5ca0c75388ae9326ef26054bb73dd866f6c28379d172a217648a55de1a",
+      "eip155-5": "39fa17702137bb2ed634d21028ae7a68599cd5521932e33b08c55f00c272053f",
+      "eip155-50": "5415b5d5224d73d0bd80f153a8d121e3315de7964140566d0f9a44aac59e749c",
+      "eip155-51": "e6112ca4d68eacc8a7b0f504fe5e8d725f711af320d98f07bdd4d9cb8dc2e06d",
+      "eip155-56": "06da2605033adb91b4cf32959b700934395fc34c11401576fc2a0ba9820b4b09",
+      "eip155-80001": "408050807491893b08eb9f473f2e5867104c1dadff4671323aaa44509bd04f08",
+      "eip155-8453": "390522231623da0edbe330681102656c1bd1bfdf9a58d678c77e7e4c1c22c262",
+      "eip155-84532": "455323b32bfe577783c16fe6868a35238c7c8c72d2d554ce2cacd0818ca7a2a8",
+      "eip155-97": "564bf279fef4fd9b2001b73dff78922dedc57fee0f243db8f437f9915d717347",
+      "eip155-998": "b7c0f4a4ec4fdf4cf98718f7b2f32e1f1955733d9873d20adf231324659ece68",
+      "eip155-999": "ce2252709b4f9d7b7ae42c6c1a58bb1262d18b1254bb5f50ed822df61717a90d",
+      "blocklist": "295c8643e1bd21d0cb8667765cba410e0b0d8ba2445710fadc729d1d321a7dc1"
+    }
+  }
+};
+
+/**
+ * Ed25519 SPKI public key (PEM) used to verify CDN manifest.json signatures.
+ * Verify with node:crypto (Node) or Web Crypto Ed25519 (browsers).
+ */
+const MANIFEST_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAemcuPT4chJxVl3iBJIarkuLlRxSV7pYlxp8W72hXBUE=\n-----END PUBLIC KEY-----";
+
+const DEFAULT_ASSET_BASE_URL = "https://raw.githubusercontent.com/bifrostwallet/assets/main/data/";
+
+const PROVIDER_CHAIN_IDS = Object.keys(providersByChain).map(chainPathToCaip2);
+const TOKEN_CHAIN_IDS = Object.keys(tokensByChain).map(chainPathToCaip2);
+
+function chainPathToCaip2(chainPath) {
+  const i = String(chainPath).indexOf("-");
+  return i === -1 ? String(chainPath) : String(chainPath).slice(0, i) + ":" + String(chainPath).slice(i + 1);
+}
+
+function normalizeChainId(chainId) {
+  // Public API accepts CAIP-2 only (e.g. "eip155:14"). Repo paths use eip155-14.
+  if (typeof chainId !== "string" || !chainId.includes(":")) {
+    throw new Error(
+      'Use a CAIP-2 chain id (e.g. "eip155:14"). Got: ' + JSON.stringify(chainId)
+    );
+  }
+  return chainId.replace(":", "-");
+}
+
+function getProviders(chainId) {
+  const providers = providersByChain[normalizeChainId(chainId)];
+  if (!providers) {
+    throw new Error(
+      "Unknown chain " + chainId + ". Available: " + PROVIDER_CHAIN_IDS.join(", ")
+    );
+  }
+  return providers;
+}
+
+function getProvider(chainId, identityAddress) {
+  const target = String(identityAddress).toLowerCase();
+  return (
+    getProviders(chainId).find(
+      (provider) => provider.identityAddress.toLowerCase() === target
+    ) ?? null
+  );
+}
+
+function getListedProviders(chainId) {
+  return getProviders(chainId).filter((provider) => provider.listed);
+}
+
+function getManagementGroupProviders(chainId) {
+  return getProviders(chainId).filter((provider) => provider.managementGroup);
+}
+
+function findProviderByValidator(chainId, nodeId) {
+  return (
+    getProviders(chainId).find((provider) => provider.validators.includes(nodeId)) ??
+    null
+  );
+}
+
+function getTokens(chainId) {
+  const tokens = tokensByChain[normalizeChainId(chainId)];
+  if (!tokens) {
+    throw new Error(
+      "Unknown token chain " + chainId + ". Available: " + TOKEN_CHAIN_IDS.join(", ")
+    );
+  }
+  return tokens;
+}
+
+function getToken(chainId, address) {
+  const target = String(address).toLowerCase();
+  return (
+    getTokens(chainId).find(
+      (token) => token.address && token.address.toLowerCase() === target
+    ) ?? null
+  );
+}
+
+function getNativeToken(chainId) {
+  return getTokens(chainId).find((token) => token.address === null) ?? null;
+}
+
+function getTokenBlocklist() {
+  return tokenBlocklist.tokens || [];
+}
+
+function resolveAssetURL(relativePath, baseURL) {
+  const base = baseURL || DEFAULT_ASSET_BASE_URL;
+  return base.replace(/\/?$/, "/") + String(relativePath).replace(/^\//, "");
+}
+
+function getSectionHashes() {
+  return SECTION_HASHES;
+}
+
+const SECTION_ORDER = ["providers", "contracts", "dapps", "tokens"];
+
+/** Canonical UTF-8 JSON bytes (as string) that the Ed25519 signature covers. */
+function canonicalManifestBody(body) {
+  const sections = {};
+  for (const name of SECTION_ORDER) {
+    const section = body.sections[name];
+    if (!section) continue;
+    const entry = { contentHash: section.contentHash };
+    if (section.chains) {
+      const chains = {};
+      for (const chain of Object.keys(section.chains).sort()) {
+        chains[chain] = section.chains[chain];
+      }
+      entry.chains = chains;
+    }
+    sections[name] = entry;
+  }
+  return JSON.stringify({ generatedAt: body.generatedAt, sections });
+}
+
+/**
+ * Verify CDN manifest.json with node:crypto Ed25519 (Node / bundlers that polyfill it).
+ * Browsers: Web Crypto Ed25519 over Buffer.from(canonicalManifestBody(body), "utf8").
+ */
+function verifyManifest(manifest, publicKeyPem) {
+  const { createPublicKey, verify } = require("node:crypto");
+  const { signature, ...body } = manifest;
+  const message = Buffer.from(canonicalManifestBody(body), "utf8");
+  return verify(
+    null,
+    message,
+    createPublicKey(publicKeyPem || MANIFEST_PUBLIC_KEY),
+    Buffer.from(signature, "base64url")
+  );
+}
+
+module.exports = {
+  DEFAULT_ASSET_BASE_URL,
+  PROVIDER_CHAIN_IDS,
+  TOKEN_CHAIN_IDS,
+  MANIFEST_PUBLIC_KEY,
+  getSectionHashes,
+  canonicalManifestBody,
+  verifyManifest,
+  getProviders,
+  getProvider,
+  getListedProviders,
+  getManagementGroupProviders,
+  findProviderByValidator,
+  getTokens,
+  getToken,
+  getNativeToken,
+  getTokenBlocklist,
+  resolveAssetURL,
+};

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@bifrostwallet/assets",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1-beta",
+  "description": "Curated assets for Bifrost Wallet.",
+  "repository": "https://github.com/bifrostwallet/assets.git",
+  "author": "Bifrost Software Ltd",
+  "license": "MIT",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "sideEffects": false
 }