From 373322b98861b5d080b167701a990a3ba108d9c7 Mon Sep 17 00:00:00 2001 From: Jason Dreyzehner Date: Sat, 15 Apr 2023 00:38:13 -0400 Subject: [PATCH] add fungible token registry example --- .cspell.json | 3 ++- bcmr-v2.schema.json | 34 +++++++++++++++++++++-- bcmr-v2.schema.ts | 11 +++++--- examples/fungible-token.json | 52 ++++++++++++++++++++++++++++++++++++ 4 files changed, 94 insertions(+), 6 deletions(-) create mode 100644 examples/fungible-token.json diff --git a/.cspell.json b/.cspell.json index ba5c4d8..a43f652 100644 --- a/.cspell.json +++ b/.cspell.json @@ -8,7 +8,8 @@ "rebranded", "rebranding", "redenominated", - "TXLOCKTIME" + "TXLOCKTIME", + "XAMPL" ], "flagWords": [], "ignorePaths": [], diff --git a/bcmr-v2.schema.json b/bcmr-v2.schema.json index 21f8520..43556f4 100644 --- a/bcmr-v2.schema.json +++ b/bcmr-v2.schema.json @@ -106,7 +106,7 @@ }, "migrated": { "description": "The timestamp at which this identity snapshot is fully in effect. This value should only be provided if the snapshot takes effect over a period of time (e.g. an in-circulation token identity is gradually migrating to a new category). In these cases, clients should gradually migrate to using the new information beginning after the identity snapshot's timestamp and the `migrated` time.\n\nThis timestamp must be provided in simplified extended ISO 8601 format, a 24-character string of format `YYYY-MM-DDTHH:mm:ss.sssZ` where timezone is zero UTC (denoted by `Z`). Note, this is the format returned by ECMAScript `Date.toISOString()`.", - "type": ["number", "string"] + "type": "string" }, "name": { "description": "The name of this identity for use in interfaces.\n\nIn user interfaces with limited space, names should be hidden beyond the first newline character or `20` characters until revealed by the user.\n\nE.g. `ACME Class A Shares`, `ACME Registry`, `Satoshi Nakamoto`, etc.", @@ -282,6 +282,36 @@ "required": ["name"], "type": "object" }, + "OffChainRegistryIdentity": { + "additionalProperties": false, + "properties": { + "description": { + "description": "A string describing this identity for use in user interfaces.\n\nIn user interfaces with limited space, descriptions should be hidden beyond the first newline character or `140` characters until revealed by the user.\n\nE.g.:\n- `The common stock issued by ACME, Inc.`\n- `A metadata registry maintained by Company Name, the embedded registry for Wallet Name.`\n- `Software developer and lead maintainer of Wallet Name.`", + "type": "string" + }, + "extensions": { + "$ref": "#/definitions/Extensions", + "description": "A mapping of `IdentitySnapshot` extension identifiers to extension definitions. {@link Extensions } may be widely standardized or application-specific.\n\nStandardized extensions for `IdentitySnapshot`s include the `authchain` extension. See https://github.com/bitjson/chip-bcmr#authchain-extension for details." + }, + "name": { + "description": "The name of this identity for use in interfaces.\n\nIn user interfaces with limited space, names should be hidden beyond the first newline character or `20` characters until revealed by the user.\n\nE.g. `ACME Class A Shares`, `ACME Registry`, `Satoshi Nakamoto`, etc.", + "type": "string" + }, + "tags": { + "description": "An array of `Tag` identifiers marking the `Tag`s associated with this identity. All specified tag identifiers must be defined in the registry's `tags` mapping.", + "items": { + "type": "string" + }, + "type": "array" + }, + "uris": { + "$ref": "#/definitions/URIs", + "description": "A mapping of identifiers to URIs associated with this identity. URI identifiers may be widely-standardized or registry-specific. Values must be valid URIs, including a protocol prefix (e.g. `https://` or `ipfs://`). Clients are only required to support `https` and `ipfs` URIs, but any scheme may be specified.\n\nThe following identifiers are recommended for all identities:\n- `icon`\n- `web`\n\nThe following optional identifiers are standardized:\n- `blog`\n- `chat`\n- `forum`\n- `icon-intro`\n- `registry`\n- `support`\n\nFor details on these standard identifiers, see: https://github.com/bitjson/chip-bcmr#uri-identifiers\n\nCustom URI identifiers allow for sharing social networking profiles, p2p connection information, and other application-specific URIs. Identifiers must be lowercase, alphanumeric strings, with no whitespace or special characters other than dashes (as a regular expression: `/^[-a-z0-9]+$/`).\n\nFor example, some common identifiers include: `discord`, `docker`, `facebook`, `git`, `github`, `gitter`, `instagram`, `linkedin`, `matrix`, `npm`, `reddit`, `slack`, `substack`, `telegram`, `twitter`, `wechat`, `youtube`." + } + }, + "required": ["name"], + "type": "object" + }, "Registry": { "additionalProperties": false, "description": "A Bitcoin Cash Metadata Registry is an authenticated JSON file containing metadata about tokens, identities, contract applications, and other on-chain artifacts. BCMRs conform to the Bitcoin Cash Metadata Registry JSON Schema, and they can be published and maintained by any entity or individual.", @@ -323,7 +353,7 @@ "registryIdentity": { "anyOf": [ { - "$ref": "#/definitions/IdentitySnapshot" + "$ref": "#/definitions/OffChainRegistryIdentity" }, { "type": "string" diff --git a/bcmr-v2.schema.ts b/bcmr-v2.schema.ts index 6afbc40..9f19246 100644 --- a/bcmr-v2.schema.ts +++ b/bcmr-v2.schema.ts @@ -512,7 +512,7 @@ export type IdentitySnapshot = { * zero UTC (denoted by `Z`). Note, this is the format returned by ECMAScript * `Date.toISOString()`. */ - migrated?: number | string; + migrated?: string; /** * If this identity is a type of token, a data structure indicating how tokens @@ -637,7 +637,7 @@ export type ChainSnapshot = Omit & { * ``` */ export type RegistryTimestampKeyedValues = { - [timestamp: number | string]: T; + [timestamp: string]: T; }; /** @@ -692,6 +692,11 @@ export type ChainHistory = RegistryTimestampKeyedValues; */ export type IdentityHistory = RegistryTimestampKeyedValues; +export type OffChainRegistryIdentity = Pick< + IdentitySnapshot, + 'name' | 'description' | 'uris' | 'tags' | 'extensions' +>; + /** * A Bitcoin Cash Metadata Registry is an authenticated JSON file containing * metadata about tokens, identities, contract applications, and other on-chain @@ -767,7 +772,7 @@ export type Registry = { * support on-chain resolution/authentication, and the contained * `IdentitySnapshot` can only be authenticated via DNS/HTTPS. */ - registryIdentity: IdentitySnapshot | string; + registryIdentity: OffChainRegistryIdentity | string; /** * A mapping of authbases to the `IdentityHistory` for that identity. diff --git a/examples/fungible-token.json b/examples/fungible-token.json new file mode 100644 index 0000000..be8f923 --- /dev/null +++ b/examples/fungible-token.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://cashtokens.org/bcmr-v2.schema.json", + "version": { "major": 1, "minor": 1, "patch": 0 }, + "latestRevision": "2023-04-14T00:00:17.720Z", + "registryIdentity": { + "name": "Example.com Token Registry", + "description": "An example registry demonstrating how the issuer of a single fungible token might publish information about the token.", + "uris": { + "icon": "https://example.com/registry-icon.svg", + "web": "https://example.com/", + "registry": "https://example.com/.well-known/bitcoin-cash-metadata-registry.json" + } + }, + "identities": { + "89cad9e3e34280eb1e8bc420542c00a7fcc01002b663dbf7f38bceddf80e680c": { + "2023-01-13T00:00:00.000Z": { + "name": "Example Asset", + "description": "This is a short description of Example Asset. In most interfaces, it will be hidden beyond 140 characters or the first newline character.\n\nThis sentence should be hidden in user interfaces with limited space.\n\nNote that this snapshot was introduced on 1/13, but the 'migrated' property indicates that the migration took place over the following month. During this month, most clients should have warned users about the upcoming change, referring users to the 'web' URI in the previous snapshot for information about the change. (Some clients may also offer clients the option to dismiss the migration period and immediately use the new metadata.) At 0 UTC on 2/13, all clients should have switched their default display for this token to use the new metadata, i.e. ticker symbol XAMPL, with 6 decimal places. After the migrated timestamp, old metadata should only be displayed when providing historical context.", + "token": { + "category": "89cad9e3e34280eb1e8bc420542c00a7fcc01002b663dbf7f38bceddf80e680c", + "decimals": 6, + "symbol": "XAMPL" + }, + "migrated": "2023-02-13T00:00:00.000Z", + "uris": { + "icon": "https://example.com/xampl-icon.svg", + "web": "https://example.com/about-xampl", + "blog": "https://blog.example.com/", + "chat": "https://chat.example.com/", + "forum": "https://forum.example.com/", + "registry": "https://example.com/.well-known/bitcoin-cash-metadata-registry.json", + "support": "https://support.example.com/", + "custom-uri-identifier": "protocol://connection-info-for-some-protocol" + } + }, + "2023-01-03T00:00:00.000Z": { + "name": "Example Asset", + "description": "This is a record of an older entry for the token identity. The token was rebranded (from EXAMPLE to XAMPL) and redenominated (from 2 to 6 decimals), but the existing token category was not modified: users were not required to trade their original EXAMPLE tokens for the redenominated XAMPL tokens, their wallets simply updated the way they are displayed using the new metadata. Note, this entry has likely been updated by the issuer to provide useful historical information rather than attempting to preserve the precise contents of the old snapshot; the 'web' URI links to a blog post about XAMPL's re-denomination/re-brand, and outdated URI information is excluded. There may have been metadata updates published between this snapshot and the latest snapshot, but they've been excluded because registries should strive to present a useful history of only meaningful changes to identities. This information can be used in user interfaces to improve continuity following metadata updates or to offer historical context.", + "token": { + "category": "89cad9e3e34280eb1e8bc420542c00a7fcc01002b663dbf7f38bceddf80e680c", + "decimals": 2, + "symbol": "EXAMPLE" + }, + "uris": { + "icon": "https://example.com/old-example-asset-icon.png", + "web": "https://blog.example.com/example-asset-is-now-XAMPL" + } + } + } + }, + "license": "CC0-1.0" +}