BitcoinCash/chip-bcmr
1
Fork 0
Code Issues Pull Requests Releases Activity

init

Browse Source
This commit is contained in:
Jason Dreyzehner
2022-10-31 13:00:15 -04:00
commit 80cb85816f
8 changed files with 1672 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+26
View File
@@ -0,0 +1,26 @@
{
"version": "0.2",
"$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/master/cspell.schema.json",
"language": "en",
"words": [
"authchains",
"BCMR",
"rebranded",
"rebranding",
"redenominated",
"TXLOCKTIME"
],
"flagWords": [],
"ignorePaths": [],
"patterns": [
{
"name": "cash-address-format",
"pattern": "/:[qpzry9x8gf2tvdw0s3jn54khce6mua7l]+/g"
}
],
"ignoreRegExpList": [
"Base64",
"HexValues",
"cash-address-format"
]
}
.gitignore
+2
View File
@@ -0,0 +1,2 @@
node_modules
package-lock.json
bcmr-v1.schema.json
+324
View File
@@ -0,0 +1,324 @@
{
"$ref": "#/definitions/Registry",
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"Extensions": {
"additionalProperties": {},
"description": "A mapping of extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type.",
"type": "object"
},
"IdentityHistory": {
"description": "An array of `IdentitySnapshot`s, ordered from newest to oldest documenting the evolution of a particular identity. Typically, the current identity information is the record at index `0`, but in cases where a planned migration has not yet begun (the snapshot's `time.begin` has not been reached), the record at index `1` is considered the current identity.\n\nThis strategy allows wallets and other user interfaces to offer better experiences when an identity is rebranded, a token redenominated, or other important metadata is modified in a coordinated update. For example, a wallet may warn token holders of a forthcoming rebranding of fungible tokens they hold; after the change, the wallet may continue to offer prominent interface hints that the rebranded tokens was recently updated.\n\nNote, only the `IdentitySnapshot`s at index `0` and `1` can be considered part of an identities \"current\" information (based on their `time` settings in relation to current time). E.g. even if two snapshots have active, overlapping migration periods (i.e. the snapshot at `2` is still relevant for the snapshot at `1`), clients should only attempt to display the migration from the snapshot at index `1` to that at index `0`.",
"items": {
"$ref": "#/definitions/IdentitySnapshot"
},
"type": "array"
},
"IdentitySnapshot": {
"additionalProperties": false,
"description": "A snapshot of the metadata for a particular identity at a specific time.",
"properties": {
"description": {
"description": "A string describing this identity for use in user interfaces. Descriptions longer than `160` characters may be elided in some interfaces.\n\nE.g. `The common stock issued by ACME, Inc.`, `A metadata registry maintained by Company Name, the embedded registry for Wallet Name.`; `Software developer and lead maintainer of Wallet Name.`; etc.",
"type": "string"
},
"extensions": {
"$ref": "#/definitions/Extensions",
"description": "A mapping of `IdentitySnapshot` extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type.\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. Names longer than `20` characters may be elided in some interfaces.\n\nE.g. `ACME Class A Shares`, `ACME Registry`, `Satoshi Nakamoto`, etc.",
"type": "string"
},
"status": {
"description": "The status of this identity, must be `active`, `inactive`, or `burned`. If omitted, defaults to `active`.\n- Identities with an `active` status should be actively tracked by clients.\n- Identities with an `inactive` status may be considered for archival by clients and may be removed in future registry versions.\n- Identities with a `burned` status have been destroyed by setting the latest identity output to a data-carrier output (`OP_RETURN`), permanently terminating the authchain. Clients should archive burned identities and – if the burned identity represented a token type – consider burning any remaining tokens of that category to reclaim funds from those outputs.",
"enum": ["active", "inactive", "burned"],
"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"
},
"time": {
"additionalProperties": false,
"description": "The timing information for the introduction of this identity snapshot. Each timestamps may be provided as either an ISO string (simplified extended ISO 8601 format) or as a locktime value: an integer from `0` to `4294967295` (inclusive) where values less than `500000000` are understood to be a block height (the current block number in the chain, beginning from block `0`), and values greater than or equal to `500000000` are understood to be a Median Time Past (BIP113) UNIX timestamp.\n\nGenerally, timestamps should be provided as an ISO string unless on-chain artifacts require the locktime value (e.g. an on-chain migration that is set to complete at a particular locktime value).",
"properties": {
"begin": {
"description": "The timestamp at which this identity snapshot begins to be active. If `complete` isn't specified, this is a precise time at which this snapshot takes effect and clients should begin using the new information.",
"type": ["string", "number"]
},
"complete": {
"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 `begin` time and completing at the `complete` time.",
"type": ["string", "number"]
}
},
"required": ["begin"],
"type": "object"
},
"token": {
"additionalProperties": false,
"description": "If this identity is a type of token, a data structure indicating how tokens should be displayed in user interfaces. Omitted for non-token identities.",
"properties": {
"category": {
"description": "The current token category used by this identity. Often, this will be equal to the identities authbase, but some token identities must migrate to new categories for technical reasons.",
"type": "string"
},
"decimals": {
"description": "An integer between `0` and `18` (inclusive) indicating the divisibility of the primary unit of this token category.\n\nThis is the number of digits that can appear after the decimal separator in fungible token amounts. For a token category with a `symbol` of `SYMBOL` and a `decimals` of `2`, a fungible token amount of `12345` should be displayed as `123.45 SYMBOL`.\n\nIf omitted, defaults to `0`.",
"type": "number"
},
"nfts": {
"additionalProperties": false,
"description": "Display information for non-fungible tokens (NFTs) of this identity. Omitted for token categories without NFTs.",
"properties": {
"description": {
"description": "A string describing how this identity uses NFTs (for use in user interfaces). Descriptions longer than `160` characters may be elided in some interfaces.\n\nE.g. `ACME DEX NFT order receipts are issued when you place orders on the decentralized exchange. After orders are processed, order receipts can be redeemed for purchased tokens or sales proceeds.`; `ACME Game collectable NFTs unlock unique playable content, user avatars, and item skins in ACME Game Online.`; etc.",
"type": "string"
},
"fields": {
"additionalProperties": {
"additionalProperties": false,
"properties": {
"description": {
"description": "A string describing how this identity uses NFTs (for use in user interfaces). Descriptions longer than `160` characters may be elided in some interfaces.\n\nE.g. `The BCH value pledged at the time this receipt was issued.`; `The number of tokens sold in this order.`; `The seat number associated with this ticket.`; `The IPFS` collectable NFTs unlock unique playable content, user avatars, and item skins in ACME Game Online.`; etc.",
"type": "string"
},
"encoding": {
"anyOf": [
{
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"binary",
"boolean",
"hex",
"https-url",
"ipfs-cid",
"locktime",
"utf8"
],
"type": "string"
}
},
"required": ["type"],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"aggregate": {
"const": "add",
"description": "The `aggregate` property indicates that aggregating this field from multiple NFTs is desirable in user interfaces. For example, for a field named `BCH Pledged` where `aggregate` is `add`, the client can display a `Total BCH Pledged` in any user interface listing more than one NFT.\n\nIf specified, clients should aggregate the field from all NFTs within a view (e.g. NFTs held by a single wallet, NFTs existing in a single transaction's outputs, etc.) using the specified operation. Note, while aggregation could be performed using any commutative operation – multiplication, bitwise AND, bitwise OR, and bitwise XOR, etc. – only `add` is currently supported.",
"type": "string"
},
"decimals": {
"description": "An integer between `0` and `18` (inclusive) indicating the divisibility of the primary unit of this token field.\n\nThis is the number of digits that can appear after the decimal separator in amounts. For a field with a `decimals` of `2`, a value of `123456` should be displayed as `1234.56`.\n\nIf omitted, defaults to `0`.",
"type": "number"
},
"type": {
"const": "number",
"type": "string"
},
"unit": {
"description": "The unit in which this field is denominated, taking the `decimals` value into account. If representing fungible token amount, this will often be the symbol of the represented token category.\n\nE.g. `BCH`, `sats`, `AcmeUSD`, etc.\n\nIf not provided, clients should not represent this field as having a unit beyond the field's `name`.",
"type": "string"
}
},
"required": ["type"],
"type": "object"
}
],
"description": "The expected encoding of this field when read from the parsing altstack (see `token.nft.parse`). All encoding definitions must have a `type`, and some encoding definitions allow for additional hinting about display strategies in clients.\n\nEncoding types may be set to `binary`, `boolean`, `hex`, `number`, or `utf8`:\n\n- `binary` types should be displayed as binary literals (e.g. `0b0101`)\n- `boolean` types should be displayed as `true` if exactly `0x01` or `false` if exactly `0x00`. If a boolean value does not match one of these values, clients should represent the NFT as unable to be parsed (e.g. simply display the full `commitment`).\n- `hex` types should be displayed as hex literals (e.g.`0xabcd`).\n- `https-url` types are percent encoded with the `https://` prefix omitted; they may be displayed as URIs or as activatable links.\n- `ipfs-cid` types are binary-encoded IPFS Content Identifiers; they may be displayed as URIs or as activatable links.\n- `locktime` types are `OP_TXLOCKTIME` results: integers from `0` to `4294967295` (inclusive) where values less than `500000000` are understood to be a block height (the current block number in the chain, beginning from block `0`), and values greater than or equal to `500000000` are understood to be a Median Time Past (BIP113) UNIX timestamp. (Note, sequence age is not currently supported.)\n- `number` types should be displayed according the their configured `decimals` and `unit` values.\n- `utf8` types should be displayed as utf8 strings."
},
"extensions": {
"$ref": "#/definitions/Extensions",
"description": "A mapping of NFT field extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type."
},
"name": {
"description": "The name of this field for use in interfaces. Names longer than `20` characters may be elided in some interfaces.\n\nE.g. `BCH Pledged`, `Tokens Sold`, `Seat Number`, `IPFS Content Identifier`, `HTTPS URL` etc.",
"type": "string"
},
"uris": {
"$ref": "#/definitions/URIs",
"description": "A mapping of identifiers to URIs associated with this NFT field. 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."
}
},
"required": ["encoding"],
"type": "object"
},
"description": "A mapping of field identifier to field definitions for the data fields that can appear in NFT commitments of this category.",
"type": "object"
},
"parse": {
"additionalProperties": false,
"description": "Parsing and interpretation information for all NFTs of this category.\n\nParsing instructions are provided in the `bytecode` property, and the results are interpreted using the `types` property.",
"properties": {
"bytecode": {
"description": "A segment of hex-encoded Bitcoin Cash VM bytecode that parses NFT commitments of this category and returns a list of NFT field values via the altstack. The `bytecode` is taken as locking bytecode evaluated after pushing the full NFT commitment to the stack (as if pushed in a single-operation unlocking bytecode).\n\nIf the resulting stack is not valid (a single \"truthy\" element remaining on the stack) – or if the altstack is empty – parsing has failed and clients should represent the NFT as unable to be parsed (e.g. simply display the full `commitment`).\n\nOn successful parsing evaluations, the bottom item on the altstack indicates the type of the NFT according to the matching definition in `types`. If no match is found, clients should represent the NFT as unable to be parsed.",
"type": "string"
},
"types": {
"additionalProperties": {
"additionalProperties": false,
"description": "A definition for one type of NFT within a token category. NFT types are indexed by the expected hex-encoded value of the bottom altstack item following evaluation of `token.nft.parse.bytecode`. The remaining altstack items are mapped to NFT fields according to the `fields` property of the matching NFT type.",
"properties": {
"description": {
"description": "A string describing this NFT type for use in user interfaces. Descriptions longer than `160` characters may be elided in some interfaces.\n\nE.g. `Receipts issued by the exchange to record details about purchases. After settlement, these receipts are redeemed for the purchased tokens.`; `Receipts issued by the crowdfunding campaign to document the value of funds pledged. If the user decides to cancel their pledge before the campaign completes, these receipts can be redeemed for a full refund.`; `Tickets issued for events at ACME Stadium.`; `Sealed ballots certified by ACME decentralized organization during the voting period. After the voting period ends, these ballots must be revealed to reclaim the tokens used for voting.`; etc.",
"type": "string"
},
"extensions": {
"$ref": "#/definitions/Extensions",
"description": "A mapping of NFT type extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type."
},
"fields": {
"description": "A list of identifiers for fields contained in NFTs of this type. On successful parsing evaluations, the bottom item on the altstack indicates the matched NFT type, and the remaining altstack items represent NFT field contents in the order listed (where `fields[0]` is the second-to-bottom item, and the final item in `fields` is the top of the altstack).\n\nFields should be ordered by recommended importance from most important to least important; in user interfaces, clients should display fields at lower indexes more prominently than those at higher indexes, e.g. if some fields cannot be displayed in minimized interfaces, higher-importance fields can still be represented. (Note, this ordering is controlled by the bytecode specified in `token.nft.parse.bytecode`.)",
"items": {
"type": "string"
},
"type": "array"
},
"name": {
"description": "The name of this NFT type for use in interfaces. Names longer than `20` characters may be elided in some interfaces.\n\nE.g. `Market Order Buys`, `Limit Order Sales`, `Pledge Receipts`, `ACME Stadium Tickets`, `Sealed Votes`, etc.",
"type": "string"
},
"uris": {
"$ref": "#/definitions/URIs",
"description": "A mapping of identifiers to URIs associated with this NFT type. 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."
}
},
"required": ["name", "fields"],
"type": "object"
},
"description": "A mapping of hex-encoded values to definitions of possible NFT types in this category.",
"type": "object"
}
},
"required": ["bytecode", "types"],
"type": "object"
}
},
"required": ["fields", "parse"],
"type": "object"
},
"symbol": {
"description": "An abbreviation used to uniquely identity this token category.",
"type": "string"
}
},
"required": ["category", "symbol"],
"type": "object"
},
"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", "time"],
"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.",
"properties": {
"$schema": {
"description": "The schema used by this registry. Many JSON editors can automatically provide inline documentation and autocomplete support using the `$schema` property, so it is recommended that registries include it. E.g.: `https://raw.githubusercontent.com/bitjson/chip-bcmr/master/registry-v1.schema.json`",
"type": "string"
},
"extensions": {
"$ref": "#/definitions/Extensions",
"description": "A mapping of `Registry` extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type.\n\nStandardized extensions for `Registry`s include the `locale` extension. See https://github.com/bitjson/chip-bcmr#locales-extension for details."
},
"identities": {
"additionalProperties": {
"$ref": "#/definitions/IdentityHistory"
},
"description": "A mapping of authbases to the `IdentityHistory` for that identity.\n\nAn authbase is a 32-byte, hex-encoded transaction hash (A.K.A. TXID) for which the zeroth-descendant transaction chain (ZDTC) authenticates and publishes an identity's claimed metadata.\n\nIdentities may represent metadata registries, specific types of tokens, companies, organizations, individuals, or other on-chain entities.",
"type": "object"
},
"latestRevision": {
"description": "The timestamp of the latest revision made to this registry version. The 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": "string"
},
"license": {
"description": "The license under which this registry is published. This may be specified as either a SPDX short identifier (https://spdx.org/licenses/) or by including the full text of the license.\n\nCommon values include: - `CC0-1.0`: https://creativecommons.org/publicdomain/zero/1.0/ - `MIT`: https://opensource.org/licenses/MIT",
"type": "string"
},
"registryIdentity": {
"anyOf": [
{
"type": "string"
},
{
"$ref": "#/definitions/IdentitySnapshot"
}
],
"description": "The identity information of this particular registry, provided as either an authbase (recommended) or an `IdentitySnapshot`.\n\nAn authbase is a 32-byte, hex-encoded transaction hash (A.K.A. TXID) for which the zeroth-descendant transaction chain (ZDTC) authenticates and publishes all registry updates. If an authbase is provided, the registry's identity information can be found in `identities[authbase]`, and clients should immediately attempt to verify the registry's identity on-chain. (See https://github.com/bitjson/chip-bcmr#chain-resolved-registries)\n\nIf an `IdentitySnapshot` is provided directly, this registry does not support on-chain resolution/authentication, and the contained `IdentitySnapshot` can only be authenticated via DNS/HTTPS."
},
"tags": {
"additionalProperties": {
"$ref": "#/definitions/Tag"
},
"description": "A map of registry-specific `Tag`s used by this registry to convey information about identities it tracks.\n\nTags allow registries to group identities into collections of related identities, marking characteristics or those identities. Tags are standardized within a registry and may represent either labels applied by that registry (e.g. `individual`, `organization`, `token`, `wallet`, `exchange`, `staking`, `utility-token`, `security-token`, `stablecoin`, `wrapped`, `collectable`, `deflationary`, `governance`, `decentralized-exchange`, `liquidity-provider`, `sidechain`, `sidechain-bridge`, etc.) or designations by external authorities (certification, membership, ownership, etc.) that are tracked by that registry.\n\nTags may be used by clients in search, discover, and filtering of identities, and they can also convey information like accreditation from investor protection organizations, public certifications by security or financial auditors, and other designations that signal legitimacy and value to users.",
"type": "object"
},
"version": {
"additionalProperties": false,
"description": "The version of this registry. Versioning adheres to Semantic Versioning (https://semver.org/).",
"properties": {
"major": {
"description": "The major version is incremented when an identity is removed.",
"type": "number"
},
"minor": {
"description": "The minor version is incremented when an identity is added or a new identity snapshot is added.",
"type": "number"
},
"patch": {
"description": "The patch version is incremented when an existing identity or identity snapshot is modified (e.g. to correct an error or add a missing piece of information) or when other registry properties (e.g. registry `name`, `description`, `uris`, etc.) are modified.\n\nGenerally, substantive changes to an existing identity should be made using a new identity snapshot in a minor version upgrade – this allows clients to provide a better user experience by noting the change in relevant user interfaces.\n\nFor example, patch upgrades might include spelling corrections in an existing snapshot or the addition of an `icon-svg` containing a higher-resolution version of an existing `icon` image. On the other hand, a rebranding in which the icon is substantially changed may warrant a new identity snapshot to be added in a minor version upgrade.",
"type": "number"
}
},
"required": ["major", "minor", "patch"],
"type": "object"
}
},
"required": ["version", "latestRevision", "registryIdentity"],
"type": "object"
},
"Tag": {
"additionalProperties": false,
"description": "Tags allow registries to classify and group identities by a variety of characteristics. Tags are standardized within a registry and may represent either labels applied by that registry or designations by external authorities (certification, membership, ownership, etc.) that are tracked by that registry.\n\nExamples of possible tags include: `individual`, `organization`, `token`, `wallet`, `exchange`, `staking`, `utility-token`, `security-token`, `stablecoin`, `wrapped`, `collectable`, `deflationary`, `governance`, `decentralized-exchange`, `liquidity-provider`, `sidechain`, `sidechain-bridge`, `acme-audited`, `acme-endorsed`, etc.\n\nTags may be used by clients in search, discovery, and filtering of identities, and they can also convey information like accreditation from investor protection organizations, public certifications by security or financial auditors, and other designations that signal integrity and value to users.",
"properties": {
"description": {
"description": "A string describing this tag for use in user interfaces. Descriptions longer than `160` characters may be elided in some interfaces.\n\nE.g. `An identity maintained by a single individual.`; `An identity representing a type of token.`; `An on-chain application that has passed security audits by ACME, Inc.`; etc.",
"type": "string"
},
"extensions": {
"$ref": "#/definitions/Extensions",
"description": "A mapping of `Tag` extension identifiers to extension definitions. Extensions may be widely standardized or registry-specific, and extension definitions may be values of any type."
},
"name": {
"description": "The name of this tag for use in interfaces. Names longer than `20` characters may be elided in some interfaces.\n\nE.g. `Individual`, `Token`, `Audited by ACME, Inc.`, etc.",
"type": "string"
},
"uris": {
"$ref": "#/definitions/URIs",
"description": "A mapping of identifiers to URIs associated with this tag. 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 tags:\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"
},
"URIs": {
"additionalProperties": {
"type": "string"
},
"description": "A mapping of identifiers to URIs associated with an entity. 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.",
"type": "object"
}
}
}
bcmr-v1.schema.ts
+639
View File
@@ -0,0 +1,639 @@
/**
* A mapping of identifiers to URIs associated with an entity. 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.
*/
export type URIs = {
[identifier: string]: string;
};
/**
* A mapping of extension identifiers to extension definitions. Extensions may
* be widely standardized or registry-specific, and extension definitions may
* be values of any type.
*/
export type Extensions = {
[identifier: string]: unknown;
};
/**
* Tags allow registries to classify and group identities by a variety of
* characteristics. Tags are standardized within a registry and may represent
* either labels applied by that registry or designations by external
* authorities (certification, membership, ownership, etc.) that are tracked by
* that registry.
*
* Examples of possible tags include: `individual`, `organization`, `token`,
* `wallet`, `exchange`, `staking`, `utility-token`, `security-token`,
* `stablecoin`, `wrapped`, `collectable`, `deflationary`, `governance`,
* `decentralized-exchange`, `liquidity-provider`, `sidechain`,
* `sidechain-bridge`, `acme-audited`, `acme-endorsed`, etc.
*
* Tags may be used by clients in search, discovery, and filtering of
* identities, and they can also convey information like accreditation from
* investor protection organizations, public certifications by security or
* financial auditors, and other designations that signal integrity and value
* to users.
*/
export type Tag = {
/**
* The name of this tag for use in interfaces. Names longer than `20`
* characters may be elided in some interfaces.
*
* E.g. `Individual`, `Token`, `Audited by ACME, Inc.`, etc.
*/
name: string;
/**
* A string describing this tag for use in user interfaces. Descriptions
* longer than `160` characters may be elided in some interfaces.
*
* E.g. `An identity maintained by a single individual.`; `An identity
* representing a type of token.`; `An on-chain application that has passed
* security audits by ACME, Inc.`; etc.
*/
description?: string;
/**
* A mapping of identifiers to URIs associated with this tag. 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.
*
* The following identifiers are recommended for all tags:
* - `icon`
* - `web`
*
* The following optional identifiers are standardized:
* - `blog`
* - `chat`
* - `forum`
* - `icon-intro`
* - `registry`
* - `support`
*
* For details on these standard identifiers, see:
* https://github.com/bitjson/chip-bcmr#uri-identifiers
*
* Custom 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]+$/`).
*
* For example, some common identifiers include: `discord`, `docker`,
* `facebook`, `git`, `github`, `gitter`, `instagram`, `linkedin`, `matrix`,
* `npm`, `reddit`, `slack`, `substack`, `telegram`, `twitter`, `wechat`,
* `youtube`.
*/
uris?: URIs;
/**
* A mapping of `Tag` extension identifiers to extension definitions.
* Extensions may be widely standardized or registry-specific, and extension
* definitions may be values of any type.
*/
extensions?: Extensions;
};
/**
* 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.
*/
export type Registry = {
/**
* The schema used by this registry. Many JSON editors can automatically
* provide inline documentation and autocomplete support using the `$schema`
* property, so it is recommended that registries include it. E.g.:
* `https://raw.githubusercontent.com/bitjson/chip-bcmr/master/registry-v1.schema.json`
*/
$schema?: string;
/**
* The version of this registry. Versioning adheres to Semantic Versioning
* (https://semver.org/).
*/
version: {
/**
* The major version is incremented when an identity is removed.
*/
major: number;
/**
* The minor version is incremented when an identity is added or a new
* identity snapshot is added.
*/
minor: number;
/**
* The patch version is incremented when an existing identity or identity
* snapshot is modified (e.g. to correct an error or add a missing piece of
* information) or when other registry properties (e.g. registry `name`,
* `description`, `uris`, etc.) are modified.
*
* Generally, substantive changes to an existing identity should be made
* using a new identity snapshot in a minor version upgrade – this allows
* clients to provide a better user experience by noting the change in
* relevant user interfaces.
*
* For example, patch upgrades might include spelling corrections in an
* existing snapshot or the addition of an `icon-svg` containing a
* higher-resolution version of an existing `icon` image. On the other hand,
* a rebranding in which the icon is substantially changed may warrant a new
* identity snapshot to be added in a minor version upgrade.
*/
patch: number;
};
/**
* The timestamp of the latest revision made to this registry version. The
* 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()`.
*/
latestRevision: string;
/**
* The identity information of this particular registry, provided as either an
* authbase (recommended) or an `IdentitySnapshot`.
*
* An authbase is a 32-byte, hex-encoded transaction hash (A.K.A. TXID) for
* which the zeroth-descendant transaction chain (ZDTC) authenticates and
* publishes all registry updates. If an authbase is provided, the registry's
* identity information can be found in `identities[authbase]`, and clients
* should immediately attempt to verify the registry's identity on-chain.
* (See https://github.com/bitjson/chip-bcmr#chain-resolved-registries)
*
* If an `IdentitySnapshot` is provided directly, this registry does not
* support on-chain resolution/authentication, and the contained
* `IdentitySnapshot` can only be authenticated via DNS/HTTPS.
*/
registryIdentity: string | IdentitySnapshot;
/**
* A mapping of authbases to the `IdentityHistory` for that identity.
*
* An authbase is a 32-byte, hex-encoded transaction hash (A.K.A. TXID) for
* which the zeroth-descendant transaction chain (ZDTC) authenticates and
* publishes an identity's claimed metadata.
*
* Identities may represent metadata registries, specific types of tokens,
* companies, organizations, individuals, or other on-chain entities.
*/
identities?: {
[authbase: string]: IdentityHistory;
};
/**
* A map of registry-specific `Tag`s used by this registry to convey
* information about identities it tracks.
*
* Tags allow registries to group identities into collections of related
* identities, marking characteristics or those identities. Tags are
* standardized within a registry and may represent either labels applied by
* that registry (e.g. `individual`, `organization`, `token`, `wallet`,
* `exchange`, `staking`, `utility-token`, `security-token`, `stablecoin`,
* `wrapped`, `collectable`, `deflationary`, `governance`,
* `decentralized-exchange`, `liquidity-provider`, `sidechain`,
* `sidechain-bridge`, etc.) or designations by external authorities
* (certification, membership, ownership, etc.) that are tracked by
* that registry.
*
* Tags may be used by clients in search, discover, and filtering of
* identities, and they can also convey information like accreditation from
* investor protection organizations, public certifications by security or
* financial auditors, and other designations that signal legitimacy and value
* to users.
*/
tags?: {
[identifier: string]: Tag;
};
/**
* A mapping of `Registry` extension identifiers to extension definitions.
* Extensions may be widely standardized or registry-specific, and extension
* definitions may be values of any type.
*
* Standardized extensions for `Registry`s include the `locale` extension. See
* https://github.com/bitjson/chip-bcmr#locales-extension for details.
*/
extensions?: Extensions;
/**
* The license under which this registry is published. This may be specified
* as either a SPDX short identifier (https://spdx.org/licenses/) or by
* including the full text of the license.
*
* Common values include:
* - `CC0-1.0`: https://creativecommons.org/publicdomain/zero/1.0/
* - `MIT`: https://opensource.org/licenses/MIT
*/
license?: string;
};
/**
* A snapshot of the metadata for a particular identity at a specific time.
*
*/
export type IdentitySnapshot = {
/**
* The name of this identity for use in interfaces. Names longer than
* `20` characters may be elided in some interfaces.
*
* E.g. `ACME Class A Shares`, `ACME Registry`, `Satoshi Nakamoto`, etc.
*/
name: string;
/**
* A string describing this identity for use in user interfaces.
* Descriptions longer than `160` characters may be elided in some interfaces.
*
* E.g. `The common stock issued by ACME, Inc.`, `A metadata
* registry maintained by Company Name, the embedded registry for Wallet
* Name.`; `Software developer and lead maintainer of Wallet Name.`; etc.
*/
description?: string;
/**
* 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.
*/
tags?: string[];
/**
* The timing information for the introduction of this identity snapshot.
* Each timestamps may be provided as either an ISO string (simplified
* extended ISO 8601 format) or as a locktime value: an integer from `0` to
* `4294967295` (inclusive) where values less than `500000000` are understood
* to be a block height (the current block number in the chain, beginning from
* block `0`), and values greater than or equal to `500000000` are understood
* to be a Median Time Past (BIP113) UNIX timestamp.
*
* Generally, timestamps should be provided as an ISO string unless on-chain
* artifacts require the locktime value (e.g. an on-chain migration that is
* set to complete at a particular locktime value).
*/
time: {
/**
* The timestamp at which this identity snapshot begins to be active. If
* `complete` isn't specified, this is a precise time at which this
* snapshot takes effect and clients should begin using the new information.
*/
begin: string | number;
/**
* 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 `begin` time and completing
* at the `complete` time.
*/
complete?: string | number;
};
/**
* If this identity is a type of token, a data structure indicating how tokens
* should be displayed in user interfaces. Omitted for non-token identities.
*/
token?: {
/**
* The current token category used by this identity. Often, this will be
* equal to the identities authbase, but some token identities must migrate
* to new categories for technical reasons.
*/
category: string;
/**
* An abbreviation used to uniquely identity this token category.
*
* Symbols must be comprised only of capital letters, numbers, and dashes
* (`-`). This can be validated with the regular expression:
* `/^[-A-Z0-9]+$/`.
*/
symbol: string;
/**
* An integer between `0` and `18` (inclusive) indicating the divisibility
* of the primary unit of this token category.
*
* This is the number of digits that can appear after the decimal separator
* in fungible token amounts. For a token category with a `symbol` of
* `SYMBOL` and a `decimals` of `2`, a fungible token amount of `12345`
* should be displayed as `123.45 SYMBOL`.
*
* If omitted, defaults to `0`.
*/
decimals?: number;
/**
* Display information for non-fungible tokens (NFTs) of this identity.
* Omitted for token categories without NFTs.
*/
nfts?: {
/**
* A string describing how this identity uses NFTs (for use in user
* interfaces). Descriptions longer than `160` characters may be elided in
* some interfaces.
*
* E.g. `ACME DEX NFT order receipts are issued when you place orders on
* the decentralized exchange. After orders are processed, order receipts
* can be redeemed for purchased tokens or sales proceeds.`; `ACME Game
* collectable NFTs unlock unique playable content, user avatars, and item
* skins in ACME Game Online.`; etc.
*/
description?: string;
/**
* A mapping of field identifier to field definitions for the data fields
* that can appear in NFT commitments of this category.
*/
fields: {
[identifier: string]: {
/**
* The name of this field for use in interfaces. Names longer than
* `20` characters may be elided in some interfaces.
*
* E.g. `BCH Pledged`, `Tokens Sold`, `Seat Number`,
* `IPFS Content Identifier`, `HTTPS URL` etc.
*/
name?: string;
/**
* A string describing how this identity uses NFTs (for use in user
* interfaces). Descriptions longer than `160` characters may be
* elided in some interfaces.
*
* E.g. `The BCH value pledged at the time this receipt was issued.`;
* `The number of tokens sold in this order.`; `The seat number
* associated with this ticket.`; `The IPFS`
* collectable NFTs unlock unique playable content, user avatars, and item
* skins in ACME Game Online.`; etc.
*/
description?: string;
/**
* The expected encoding of this field when read from the parsing
* altstack (see `token.nft.parse`). All encoding definitions must
* have a `type`, and some encoding definitions allow for additional
* hinting about display strategies in clients.
*
* Encoding types may be set to `binary`, `boolean`, `hex`, `number`,
* or `utf8`:
*
* - `binary` types should be displayed as binary literals (e.g.
* `0b0101`)
* - `boolean` types should be displayed as `true` if exactly `0x01`
* or `false` if exactly `0x00`. If a boolean value does not match one
* of these values, clients should represent the NFT as unable to be
* parsed (e.g. simply display the full `commitment`).
* - `hex` types should be displayed as hex literals (e.g.`0xabcd`).
* - `https-url` types are percent encoded with the `https://` prefix
* omitted; they may be displayed as URIs or as activatable links.
* - `ipfs-cid` types are binary-encoded IPFS Content Identifiers;
* they may be displayed as URIs or as activatable links.
* - `locktime` types are `OP_TXLOCKTIME` results: integers from `0`
* to `4294967295` (inclusive) where values less than `500000000` are
* understood to be a block height (the current block number in the
* chain, beginning from block `0`), and values greater than or equal
* to `500000000` are understood to be a Median Time Past (BIP113)
* UNIX timestamp. (Note, sequence age is not currently supported.)
* - `number` types should be displayed according the their configured
* `decimals` and `unit` values.
* - `utf8` types should be displayed as utf8 strings.
*/
encoding:
| {
type:
| 'binary'
| 'boolean'
| 'hex'
| 'https-url'
| 'ipfs-cid'
| `locktime`
| 'utf8';
}
| {
type: 'number';
/**
* The `aggregate` property indicates that aggregating this
* field from multiple NFTs is desirable in user interfaces. For
* example, for a field named `BCH Pledged` where `aggregate` is
* `add`, the client can display a `Total BCH Pledged` in any
* user interface listing more than one NFT.
*
* If specified, clients should aggregate the field from all
* NFTs within a view (e.g. NFTs held by a single wallet, NFTs
* existing in a single transaction's outputs, etc.) using the
* specified operation. Note, while aggregation could be
* performed using any commutative operation – multiplication,
* bitwise AND, bitwise OR, and bitwise XOR, etc. – only `add`
* is currently supported.
*/
aggregate?: 'add';
/**
* An integer between `0` and `18` (inclusive) indicating the
* divisibility of the primary unit of this token field.
*
* This is the number of digits that can appear after the
* decimal separator in amounts. For a field with a `decimals`
* of `2`, a value of `123456` should be displayed as `1234.56`.
*
* If omitted, defaults to `0`.
*/
decimals?: number;
/**
* The unit in which this field is denominated, taking the
* `decimals` value into account. If representing fungible token
* amount, this will often be the symbol of the represented
* token category.
*
* E.g. `BCH`, `sats`, `AcmeUSD`, etc.
*
* If not provided, clients should not represent this field as
* having a unit beyond the field's `name`.
*/
unit?: string;
};
/**
* A mapping of identifiers to URIs associated with this NFT field.
* 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.
*/
uris?: URIs;
/**
* A mapping of NFT field extension identifiers to extension
* definitions. Extensions may be widely standardized or
* registry-specific, and extension definitions may be values of
* any type.
*/
extensions?: Extensions;
};
};
/**
* Parsing and interpretation information for all NFTs of this category.
*
* Parsing instructions are provided in the `bytecode` property, and the
* results are interpreted using the `types` property.
*/
parse: {
/**
* A segment of hex-encoded Bitcoin Cash VM bytecode that parses NFT
* commitments of this category and returns a list of NFT field values
* via the altstack. The `bytecode` is taken as locking bytecode
* evaluated after pushing the full NFT commitment to the stack (as if
* pushed in a single-operation unlocking bytecode).
*
* If the resulting stack is not valid (a single "truthy" element
* remaining on the stack) – or if the altstack is empty – parsing has
* failed and clients should represent the NFT as unable to be parsed
* (e.g. simply display the full `commitment`).
*
* On successful parsing evaluations, the bottom item on the altstack
* indicates the type of the NFT according to the matching definition in
* `types`. If no match is found, clients should represent the NFT as
* unable to be parsed.
*/
bytecode: string;
/**
* A mapping of hex-encoded values to definitions of possible NFT types
* in this category.
*/
types: {
/**
* A definition for one type of NFT within a token category. NFT types
* are indexed by the expected hex-encoded value of the bottom
* altstack item following evaluation of `token.nft.parse.bytecode`.
* The remaining altstack items are mapped to NFT fields according to
* the `fields` property of the matching NFT type.
*/
[bottomAltStackItemHex: string]: {
/**
* The name of this NFT type for use in interfaces. Names longer than
* `20` characters may be elided in some interfaces.
*
* E.g. `Market Order Buys`, `Limit Order Sales`, `Pledge Receipts`,
* `ACME Stadium Tickets`, `Sealed Votes`, etc.
*/
name: string;
/**
* A string describing this NFT type for use in user interfaces.
* Descriptions longer than `160` characters may be elided in
* some interfaces.
*
* E.g. `Receipts issued by the exchange to record details about
* purchases. After settlement, these receipts are redeemed for the
* purchased tokens.`; `Receipts issued by the crowdfunding campaign
* to document the value of funds pledged. If the user decides to
* cancel their pledge before the campaign completes, these receipts
* can be redeemed for a full refund.`; `Tickets issued for events
* at ACME Stadium.`; `Sealed ballots certified by ACME
* decentralized organization during the voting period. After the
* voting period ends, these ballots must be revealed to reclaim the
* tokens used for voting.`; etc.
*/
description?: string;
/**
* A list of identifiers for fields contained in NFTs of this type.
* On successful parsing evaluations, the bottom item on the
* altstack indicates the matched NFT type, and the remaining
* altstack items represent NFT field contents in the order listed
* (where `fields[0]` is the second-to-bottom item, and the final
* item in `fields` is the top of the altstack).
*
* Fields should be ordered by recommended importance from most
* important to least important; in user interfaces, clients should
* display fields at lower indexes more prominently than those at
* higher indexes, e.g. if some fields cannot be displayed in
* minimized interfaces, higher-importance fields can still be
* represented. (Note, this ordering is controlled by the bytecode
* specified in `token.nft.parse.bytecode`.)
*/
fields: string[];
/**
* A mapping of identifiers to URIs associated with this NFT type.
* 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.
*/
uris?: URIs;
/**
* A mapping of NFT type extension identifiers to extension
* definitions. Extensions may be widely standardized or
* registry-specific, and extension definitions may be values of
* any type.
*/
extensions?: Extensions;
};
};
};
};
};
/**
* The status of this identity, must be `active`, `inactive`, or `burned`. If
* omitted, defaults to `active`.
* - Identities with an `active` status should be actively tracked by clients.
* - Identities with an `inactive` status may be considered for archival by
* clients and may be removed in future registry versions.
* - Identities with a `burned` status have been destroyed by setting the
* latest identity output to a data-carrier output (`OP_RETURN`), permanently
* terminating the authchain. Clients should archive burned identities and –
* if the burned identity represented a token type – consider burning any
* remaining tokens of that category to reclaim funds from those outputs.
*/
status?: 'active' | 'inactive' | 'burned';
/**
* 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.
*
* The following identifiers are recommended for all identities:
* - `icon`
* - `web`
*
* The following optional identifiers are standardized:
* - `blog`
* - `chat`
* - `forum`
* - `icon-intro`
* - `registry`
* - `support`
*
* For details on these standard identifiers, see:
* https://github.com/bitjson/chip-bcmr#uri-identifiers
*
* Custom 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]+$/`).
*
* For example, some common identifiers include: `discord`, `docker`,
* `facebook`, `git`, `github`, `gitter`, `instagram`, `linkedin`, `matrix`,
* `npm`, `reddit`, `slack`, `substack`, `telegram`, `twitter`, `wechat`,
* `youtube`.
*/
uris?: URIs;
/**
* A mapping of `IdentitySnapshot` extension identifiers to extension
* definitions. Extensions may be widely standardized or registry-specific,
* and extension definitions may be values of any type.
*
* Standardized extensions for `IdentitySnapshot`s include the `authchain`
* extension. See
* https://github.com/bitjson/chip-bcmr#authchain-extension for details.
*/
extensions?: Extensions;
};
/**
* An array of `IdentitySnapshot`s, ordered from newest to oldest documenting
* the evolution of a particular identity. Typically, the current identity
* information is the record at index `0`, but in cases where a planned
* migration has not yet begun (the snapshot's `time.begin` has not been
* reached), the record at index `1` is considered the current identity.
*
* This strategy allows wallets and other user interfaces to offer better
* experiences when an identity is rebranded, a token redenominated, or other
* important metadata is modified in a coordinated update. For example, a wallet
* may warn token holders of a forthcoming rebranding of fungible tokens they
* hold; after the change, the wallet may continue to offer prominent interface
* hints that the rebranded tokens was recently updated.
*
* Note, only the `IdentitySnapshot`s at index `0` and `1` can be considered
* part of an identities "current" information (based on their `time` settings
* in relation to current time). E.g. even if two snapshots have active,
* overlapping migration periods (i.e. the snapshot at `2` is still relevant for
* the snapshot at `1`), clients should only attempt to display the migration
* from the snapshot at index `1` to that at index `0`.
*/
export type IdentityHistory = IdentitySnapshot[];
package.json
+12
View File
@@ -0,0 +1,12 @@
{
"name": "chip-bcmr",
"private": true,
"scripts": {
"start": "ts-json-schema-generator --no-ref-encode --path 'bcmr-v1.schema.ts' --type 'Registry' > bcmr-v1.schema.json && prettier 'bcmr-v1.schema.json' --write"
},
"description": "This package provides package scripts to generate the Bitcoin Cash Metadata Registry JSON schema. To regenerate the schema, install the dependencies with 'npm install', then run 'npm start'.",
"dependencies": {
"prettier": "^2.7.1",
"ts-json-schema-generator": "^1.1.2"
}
}
readme.md
+385
View File
@@ -0,0 +1,385 @@
# CHIP-BCMR: Bitcoin Cash Metadata Registries
Title: Bitcoin Cash Metadata Registries
Type: Standards
Layer: Applications
Maintainer: Jason Dreyzehner
Status: Draft
Initial Publication Date: 2022-10-31
Latest Revision Date: 2022-10-31
Version: 1.0.0
<details>
<summary><strong>Table of Contents</strong></summary>
- [Summary](#summary)
- [Deployment](#deployment)
- [Motivation](#motivation)
- [Benefits](#benefits)
- [Technical Specification](#technical-specification)
- [Rationale](#rationale)
- [Prior Art & Alternatives](#prior-art--alternatives)
- [Test Vectors](#test-vectors)
- [Implementations](#implementations)
- [Feedback & Reviews](#feedback--reviews)
- [Acknowledgements](#acknowledgements)
- [Changelog](#changelog)
- [Copyright](#copyright)
</details>
## Summary
A standard for sharing authenticated metadata between Bitcoin Cash wallets.
## Deployment
This proposal does not require coordinated deployment. Clients can begin implementation upon acceptance of [`CHIP-2022-02-CashTokens`](https://github.com/bitjson/cashtokens).
## Motivation
Bitcoin Cash software requires standards for locating and verifying metadata, allowing user-recognizable names, descriptions, icons, ticker symbols, and other information to be associated with on-chain artifacts like identities, tokens, and contract systems.
## Benefits
### Extensible JSON Schema
Metadata registries use an extensible JSON schema, ensuring a baseline of compatibility across all ecosystem software while enabling individual vendors and industry groups to create extensions and rapidly innovate.
### Interpretation of NFT Commitments
Registries can encode structured information about NFT commitment APIs, allowing ecosystem software to parse and understand the contents of any NFT. This enables generalized user interfaces for all NFTs, and application-specific extensions can build on this NFT parsing infrastructure to enable richer experiences – for example:
- A table of the user's open orders for a decentralized exchange with sums for "Total Tokens for Sale" and "Total BCH Order Value".
- A list of the user's active crowdfunding pledges with information on each campaign and a sum of "Total BCH Pledged".
- A view of the user's tickets with times, dates, location, seat, class, gate, etc. prominently displayed.
- A gallery of the user's collectable NFTs for a particular game ecosystem with images and other metadata displayed using information encoded in each NFT.
### Decentralized Publishing & Verification
Metadata registries can be published by any entity or individual without an approval process. Registries can be authenticated via the Domain Name System (DNS) or via on-chain transactions, enabling strong censorship resistance.
### Contract-Held Identities
Identities are held by BCH contracts, enabling identities to employ the same security strategies as those used to secure funds and tokens, e.g. multisignature wallets, offline signers, time-delayed vaults, bounties/honeypots, and more. Identities can modify their security requirements over time, offering built-in support for key rotation and incremental security enhancement.
### SPV Validation of Identities and Claims
Identities can be verified by validating only the last transaction in a chain of transactions, so validation can be performed by low-resource clients using lightweight proofs (measured in kilobytes).
### Bootstrapped Trust via DNS
Registries may be published via both DNS and on-chain transactions, allowing trust in the registry's identity to be bootstrapped from a domain name that is already known to the user.
## Technical Specification
A **Bitcoin Cash Metadata Registry** (BCMR) is an authenticated JSON file containing metadata about tokens, individual and organizational identities, contract applications, and other on-chain artifacts. BCMRs conform to a [Metadata Registry JSON Schema](#metadata-registry-json-schema), and they can be published and maintained by any entity or individual.
**Client software** – wallets, indexers, and other software that utilizes metadata – can acquire and authenticate metadata registries using multiple strategies. **Metadata-validating clients** are clients that fully support acquiring and authenticating [chain-resolved registries](#chain-resolved-registries); **DNS-only clients** are clients that support only [DNS-resolved registries](#dns-resolved-registries).
### Embedded Registries
**Embedded metadata registries** are built in to published releases of client software, providing a default registry of metadata assembled by the software publisher.
It is recommended that all client software include an initially-trusted, embedded registry. Client software may support updating embedded registries [via DNS](#dns-resolved-registries) or [via on-chain transactions](#chain-resolved-registries).
### Manually-Imported Registries
Where appropriate, client software may provide advanced users with the ability to manually import registries (e.g. from a file or from an arbitrary URL). Note that malicious registries can mislead users into mislabeling token, identities, and contract applications, leading to loss of value. Implementers supporting manually-imported registries should review the [Guidelines for Client Software](#guidelines-for-client-software).
### DNS-Resolved Registries
**DNS-resolved metadata registries** are associated with a particular [Fully-Qualified Domain Name (FQDN)](https://en.wikipedia.org/wiki/Fully_qualified_domain_name); they are acquired and authenticated using [Hypertext Transfer Protocol Secure (HTTPS)](https://en.wikipedia.org/wiki/HTTPS).
DNS resolution allows registries to bootstrap trust from domain names that are already known to users. After initially importing a DNS-resolved registry, clients can receive faster updates and prevent targeted attacks by upgrading to [on-chain resolution](#chain-resolved-registries).
#### Well-Known URI
DNS-resolved metadata registries are published using a [Well-Known URI](https://en.wikipedia.org/wiki/Well-known_URI) with the `https` scheme and a suffix of `bitcoin-cash-metadata-registry.json`. For example, given a fully-qualified domain name of `test.example.com`, the metadata registry must be published at `https://test.example.com/.well-known/bitcoin-cash-metadata-registry.json` and accessed via `GET` request.
Registries must allow [Cross-Origin Resource Sharing (CORS)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) using `Access-Control-Allow-Origin: *`.
If the registry is returned with a `max-age` directive in its [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) HTTP header, clients must invalidated and refetch the registry after the stated expiration. If no `max-age` is set, clients should consider downloaded registries to expire after `7` days (`max-age=604800`).
#### HTTP Redirect Handling
All clients must support the HTTP [`301 Moved Permanently`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301) and [`302 Found`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302) redirect status response codes when fetching DNS-resolved metadata registries.
Clients may handle a status response code of `302` without notifying the user. The registry must be fetched from the alternative URL provided in the `Location` header, and `Location` URLs that do not conform to the [Well-Known URI](#well-known-uri) are acceptable.
Clients must handle a status response code of `301` by notifying the user of the permanent redirection. The registry must be fetched from the alternative URL provided in the `Location` header, and `Location` URLs that do not conform to the [Well-Known URI](#well-known-uri) are acceptable. The client must update its records of the canonical Fully-Qualified Domain Name (FQDN) for the metadata registry being fetched; future registry updates must be fetched from the [Well-Known URI](#well-known-uri) using the updated FQDN (even if the returned `Location` URL did not conform to the Well-Known URI).
#### Upgrade to On-Chain Resolution
DNS-resolved metadata registries may indicate a preference for [on-chain resolution](#chain-resolved-registries) by specifying an [authbase](#authbase) in the `registryIdentity` property of the metadata registry.
If a received registry indicates a `registryIdentity` authbase, clients with support for [chain-resolved registries](#chain-resolved-registries) (metadata-validating clients) must update their records to set the indicated authbase as the root of trust for that registry and immediately begin to fetch the registry using [chain resolution](#on-chain-metadata-registry-resolution). Clients without support for on-chain resolution (DNS-only clients) should warn the user that the fetched registry prefers on-chain resolution, but the client only supports DNS resolution.
If the DNS-resolved registry includes the [`authchain` extension](#authchain-extension) for the authbase indicated in `registryIdentity`, chain resolution should be [accelerated using the provided authchain data](#authchain-extension). (Note, the registry's authhead transaction must commit to the hash of the published registry, so the registry identity's `authchain` extension is expected to not include the latest authhead transaction.)
### Chain-Resolved Registries
**Chain-resolved metadata registries** are associated with a particular **authbase**, a 32-byte, hex-encoded transaction hash (A.K.A. TXID) for which the [**zeroth-descendant transaction chain** (ZDTC)](#zeroth-descendant-transaction-chain) authenticates and publishes all registry updates.
Chain resolution offers stronger security and better user experiences than DNS resolution:
- **Enhanced identity security** – identities are controlled by unspent transaction outputs, so identity owners can employ the same security strategies used to secure funds and tokens (e.g. multisignature wallets, offline signers, time-delayed vaults, bounties/honeypots, etc.); this avoids many classes of attacks possible against DNS-resolved registries.
- **Prevention of targeted attacks** – a hash of the registry is published on the blockchain, so clients can ensure that a received registry is identical to that received by every other client.
- **Real-time updates** – identity updates are broadcasted by spending the identity's latest [identity output](#zeroth-descendant-transaction-chain), so clients can detect updates using standard light wallet infrastructure (e.g. [Simplified Payment Verification](https://web.archive.org/web/20100704213649/https://bitcoin.org/bitcoin.pdf)).
#### Zeroth-Descendant Transaction Chains
A **zeroth-descendant transaction chain** – also known as an **authchain** – is a chain of transactions where the output at index `0` for each transaction is spent by the following transaction. In the context of authchains, the transaction output at index `0` is known as the transaction's **identity output**. Because all Bitcoin Cash transactions must have at least one output, every valid transaction has a single identity output.
The first transaction in an authchain is referred to as the **authbase transaction**; authbase transactions have no distinguishing features, and any valid transaction can serve as an authbase transaction. The final transaction in an authchain is referred to as the **authhead transaction**. By definition, the identity output of the authhead transaction is unspent.
#### Authchain Resolution
To resolve an authchain (a [zeroth-descendant transaction chain](#zeroth-descendant-transaction-chains)), clients must recursively identify the transaction that spent the output at index `0` of the current transaction, beginning with the authbase transaction. (Note, this process can be [accelerated using data from `authchain` extensions](#authchain-extension) in registries.)
Once validated, clients should retain a mapping of the authbase to the latest identity input to accelerate future resolutions. To track an identity for future updates, clients should monitor the latest identity input for spends (e.g. wallets may monitor tracked identity outputs as if they were UTXOs held by the wallet).
##### Burned Identities
Identities for which the authhead transaction includes a data-carrier output (an output beginning with `OP_RETURN`/`0x6a`) as the identity output are considered "**burned**". Identities may be burned to broadcast that the identity is no longer maintained and can be safely forgotten or archived by clients. Other standards may make use of identity-burning data-carrier output to broadcast additional information about the burned identity.
Note that identities undergoing name changes or other significant changes to metadata need not burn the identity; updated metadata can be published via [on-chain identity claims](#on-chain-identity-claims). Note also that identities can be seamlessly merged (e.g. after a merger or acquisition) by spending both identity outputs in the same transaction, so burning actively-used identities is rarely necessary.
#### On-Chain Identity Claims
By including standardized data-carrier outputs in [authhead](#zeroth-descendant-transaction-chains) transactions, identities can broadcast **on-chain identity claims** – public attestations by the identity about various topics.
On-chain identity claims can be used to broadcast information like metadata registries, hashes of software updates, [warrant canaries](https://en.wikipedia.org/wiki/Warrant_canary), [tamper-evident logs](https://transparency.dev/), [reusable payment addresses](https://github.com/imaginaryusername/Reusable_specs/blob/16025c2f9f20c9dd16e1619a7a742dad908865f3/reusable_addresses.md), [onion service](https://community.torproject.org/onion-services/) addresses, and other information relating to the broadcasting identity. (Note, metadata registry [extensions](#extensions) offer an off-chain alternative to on-chain identity claims.)
[Metadata Registry Publication Outputs](#metadata-registry-publication-outputs) are the only type of on-chain identity claim standardized by this specification.
#### On-Chain Metadata Registry Resolution
To resolve a metadata registry that is published on chain, clients must first [resolve and validate the authchain](#authchain-resolution) for the registry's identity. Once the registry's authhead transaction has been acquired and validated, the client must inspect the authhead transaction's outputs to locate the [metadata registry publication output](#metadata-registry-publication-outputs), then fetch and verify the registry using the appropriate strategy for that publication output (either [IPFS](#ipfs-publication-outputs) or [HTTPS](#https-publication-outputs)).
#### Metadata Registry Publication Outputs
Chain-resolved registries are published using **metadata registry publication outputs**, data-carrier outputs that include the hash and – optionally – an HTTPS URL from which the registry can be downloaded.
The locking bytecode of publication outputs must conform to the following structure:
```
OP_RETURN <'BCMR'> <hash> [<https_url>]
```
Metadata registry publication outputs are identified by the **locking bytecode prefix** `OP_RETURN <'BCMR'>` (`0x6a0442434d52`).
Every transaction can have **zero or one metadata registry publication output**; if multiple outputs share the required locking bytecode prefix, the first (the output at the lowest-value index) is considered the definitive publication output, and later outputs sharing the prefix must be ignored. (Note, even if the first matching output is malformed – e.g. it does not push a `hash` – later matching outputs should not be considered by clients.)
##### IPFS Publication Outputs
Publication outputs with only two pushed items (where the `<https_url>` is omitted) are **[IPFS](https://en.wikipedia.org/wiki/InterPlanetary_File_System) publication outputs**. For these outputs, the `hash` is a [binary-encoded IPFS Content Identifier (CID)](https://docs.ipfs.tech/concepts/content-addressing/#cid-conversion). Clients must fetch these registries using [IPFS](https://en.wikipedia.org/wiki/InterPlanetary_File_System).
Clients without access to full IPFS nodes may use [HTTP Gateways](https://docs.ipfs.tech/reference/http/gateway/) to resolve IPFS-published registries. Clients using HTTP gateways must self-verify the response to confirm it matches the requested CID.
##### HTTPS Publication Outputs
Publication outputs with the third pushed item (`https_url`) are **HTTPS publication outputs**. For these outputs, the `hash` is the SHA-256 hash (encoded in `OP_SHA256` byte order<sup>1</sup>) of the registry contents, and the `https_url` is the [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) URL from which the registry can be downloaded, excluding the `https://` protocol prefix<sup>2</sup>. It is recommended that `https_url` conform to the [Well-Known URI](#well-known-uri).
After fetching a registry from the published `https_url`, clients must verify the response to confirm it matches the published SHA-256 `hash`.
To avoid leaking connection information to registry hosts, clients may choose to download the registry via Tor or via a trusted proxy, VPN, or mirror service. Because the hash of the downloaded registry is verified, sources need not be trusted for registry integrity.
<details>
<summary>Notes</summary>
1. This is the byte order produced/required by all BCH VM operations which employ SHA-256 (including `OP_SHA256` and `OP_HASH256`), the byte order used for outpoint transaction hashes in the P2P transaction format, and the byte order produced by most SHA-256 libraries. For reference, the genesis block header in this byte order is little-endian – `6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000` – and can be produced by this script: `<0x0100000000000000000000000000000000000000000000000000000000000000000000003ba3edfd7a7b12b27ac72c3e67768f617fc81bc3888a51323a9fb8aa4b1e5e4a29ab5f49ffff001d1dac2b7c> OP_HASH256`. (Note, this is the opposite byte order as is commonly used in user interfaces like block explorers.)
2. For example, a registry hosted at `https://www.example.com/bcmr registry.json` with a hash of `0x6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000` would be encoded using the locking script: `OP_RETURN <'BCMR'> <0x6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000> <'www.example.com/bcmr%20registry.json'>` producing the locking bytecode: `0x6a0442434d52206fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000247777772e6578616d706c652e636f6d2f62636d7225323072656769737472792e6a736f6e`.
</details>
### Metadata Registry JSON Schema
Metadata registries conform to the [**Metadata Registry JSON Schema**](./registry.schema.json) ([source TypeScript type definitions](./registry.schema.ts)). The JSON schema is internally-documented, but notable features are discussed below.
#### Identities
Identities are the core primitive of metadata registries – they can encapsulate metadata about the metadata registry itself, other metadata registries, individuals, organizations, products, tokens, and various on-chain entities.
Every identity is defined by an [authbase](#chain-resolved-registries). **An identity's authbase is both a globally-unique identifier and its root of trust**: the entire history of an identity – it's [authchain](#zeroth-descendant-transaction-chains) – can be [trustlessly verified by light clients](#authchain-resolution), including globally-broadcasted, [on-chain identity claims](#on-chain-identity-claims).
Metadata registries map any number of authbases to concise representations of each identity's history. By standardizing a strategy for describing notable evolutions of an identity over time, clients can provide more consistent user experiences across the ecosystem.
#### Identity Snapshots
All identity metadata is organized into **identity snapshots**, data structures that contain metadata for a particular identity as of a specific time.
Snapshots can include general information about the identity like `name`, `description`, [`tags`](#tags), and [`uris`](#uri-identifiers). For identities that represent token categories, snapshots can include the current `category`, display information like `symbol`, and `decimals`, and detailed technical metadata like parsing, encoding, and semantic information about various types of NFTs available within the token category.
At any moment in time, only one snapshot is considered "current" for an identity. However, using the `time.complete` property, a snapshot can indicate that the identity's prior snapshot remains relevant (e.g. an in-circulation token identity is gradually migrating to a new token category).
#### Identity History
Each identity in a metadata registry is represented by an `IdentityHistory` data structure, an array of [`IdentitySnapshot`](#identitysnapshots)s ordered from newest (at index `0`) to oldest. `IdentityHistory` data structures allow clients to construct a timeline of the evolution of a particular identity, helping users recognize and disambiguate identities that have changed significantly since the user last interacted with that identity.
Typically, the current identity information is the record at index `0`, but in cases where a [planned migration](#handling-identity-snapshot-migrations) has not yet begun (the snapshot's `time.begin` has not been reached), the record at index `1` is considered the current identity.
#### Tags
Tags allow registries to classify and group identities by a variety of characteristics. Tags are standardized within a registry and may represent either labels applied by that registry or designations by external authorities (certification, membership, ownership, etc.) that are tracked by that registry.
Examples of possible tags include: `individual`, `organization`, `token`, `wallet`, `exchange`, `staking`, `utility-token`, `security-token`, `stablecoin`, `wrapped`, `collectable`, `deflationary`, `governance`, `decentralized-exchange`, `liquidity-provider`, `sidechain`, `sidechain-bridge`, `acme-audited`, `acme-endorsed`, etc.
Tags may be used by clients in search, discovery, and filtering of identities, and they can also convey information like accreditation from investor protection organizations, public certifications by security or financial auditors, and other designations that signal integrity or value to users.
#### URI Identifiers
Both the `IdentitySnapshot` and `Tag` types may include a `uris` property mapping any number of **URI Identifiers** to URIs. **Conforming clients must support both `https` and `ipfs` URIs**. (Note: rudimentary support for `ipfs` can be implemented using [trusted HTTPS gateways](https://docs.ipfs.tech/reference/http/gateway/).)
Several URI identifiers are standardized by this specification, and any number of [custom URI identifiers](#custom-uri-identifiers) may also be used by other standards or vendor-specific software. All URIs must be provided in full, including protocol prefix (e.g. `https://` or `ipfs://`). Other protocol prefixes may be specified, but they might not be supported by all clients.
##### Recommended URI Identifiers
The following identifiers are strongly recommended for all identities and tags:
| Identifier | Description |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `icon` | A URI pointing to a square, static icon that represents this identity or tag. Transparency is supported, and icons should be suitable for display against both light and dark backgrounds. Acceptable formats are `SVG`, `AVIF`, `WebP`, or `PNG`; `SVG` is recommended. For raster formats, the recommended size is `400px` by `400px`. |
| `web` | The URI for a website offering information about this registry, identity, or tag. |
##### Optional URI Identifiers
The following optional URI identifiers are standardized:
| Identifier | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blog` | A URI identifying a blog or other news source for this identity or tag. |
| `chat` | A URI identifying a community chatroom for this identity or tag. |
| `forum` | A URI identifying a community forum for this identity or tag. |
| `icon-intro` | A URI pointing to a square, animated icon that represents this identity or tag. The animation should play once (without looping) to introduce the static icon. Transparency is supported, and icons should be suitable for display against both light and dark backgrounds. Acceptable formats are `SVG`, `AVIF`, or `WebP`. For raster formats, the recommended size is `400px` by `400px`. |
| `registry` | The primary-source registry URI for this identity or tag. For DNS-resolved registries, this is the full, [Well-Known URI](#well-known-uri) from which the registry can be downloaded. For chain-resolved registries and other identities, this is the full URI of the latest registry published on-chain by the identity. For tags, The `registry` identifier should only be used when a tag represents a formal designation by a particular authority (certification, membership, ownership, etc.); when present, this URI points to the canonical registry published by that authority. Tags without this identifier are assumed to be created and applied by the containing registry. |
| `support` | A URI offering user-facing support for this identity or tag. |
##### Custom URI identifiers
Custom 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]+$/`).
For example, some common identifiers include: `discord`, `docker`, `facebook`, `git`, `github`, `gitter`, `instagram`, `linkedin`, `matrix`, `npm`, `reddit`, `slack`, `substack`, `telegram`, `twitter`, `wechat`, `youtube`. Note that the `CC0-1.0`-licensed [Simple Icons](https://simpleicons.org/) project offers icons for these and many other identifiers.
#### Extensions
The metadata registry includes an optional `extensions` property for registries, identities, tags, NFT types, and NFT fields. Extensions offer the flexibility to associate arbitrary, vendor-specific metadata with a particular registry, identity, or tag.
For example, a `contact` extension could specify common contact information for an identity:
```json
{
"extensions": {
"contact": {
"phone": "+1 (123) 456-7890",
"email": "contact@example.com",
"postal-address": "New Hampshire State House Museum\n107 N Main St\nConcord, NH 03301"
}
}
}
```
Like [Custom URI identifiers](#custom-uri-identifiers), extensions identifiers must be lowercase, alphanumeric strings, with no whitespace or special characters other than dashes (as a regular expression: `/^[-a-z0-9]+$/`).
This specification standardizes several extensions.
##### Locales Extension
The `locales` extension is standardized for the `Registry` type. When provided, `locales` specifies a mapping of Unicode locale identifiers (conforming to [ECMAScript's `Intl.Locale`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) object) to localized versions of metadata registry contents. The following optional properties may be provided within each locale: `identities`, `tags`, and `extensions`. (Note, registry property names and standardized identifiers are never localized.)
**Outside of the `locales` extension, metadata registries are considered to be provided in the `English` Unicode locale (identifier: `en`)**. All other locales – including regional English locales like `en-US` or `en-GB` – must be provided via the `locale` extension.
**It is acceptable for registries to be partially-localized.** For example, some locales may exclude identities that appear in the `en` locale (and vice versa). Clients with support for the `locale` extension will attempt to use metadata from the user's preferred locale, falling back to metadata from the closest available locale. (Note, it is not necessary for registries to include any metadata for the `en` locale; registries that omit both the `identities` and `tags` fields from the `en` locale may still provide either or both fields for any number of other locales using the `locales` extension.)
Registries should avoid localizing custom identifiers (like URI and tag identifiers) to ensure consistency across all locales.
###### Assembling Localized Registries
A localized registry is produced by the following algorithm:
1. Given the user's preferred locale, locate the registry's closest specified locale in the `locale` extension. If a precise match is not available, fall back recursively to the closest available locale. If no matching language is available, default to `en`. E.g. If the user's preferred locale is `de-AT`, fall back to `de`, then `en`.
2. Beginning from the closest available locale, assemble a list of matching locales in reverse order of specificity. E.g. `["en", "de", "de-AT"]`. (Note, `en` is a special case; other `en` locales should not be included in this list for non-english locales.)
3. Create a localized registry by inheriting from each locale beginning with the least specific locale:
1. From the current locale, assign all `identities`, `tags`, and `extensions` (excluding the `locale` extension) to the generated locale, overriding the full definition at that identifier with the localized definition from the more-specific locale. (Note, replacement is object-level; do not attempt to merge two definitions for the same identifier.)
2. If this client is deeply-validating the registry, verify the consistency of recognized, non-localized metadata and emit an error if any differences are found (e.g. metadata such as `token.category` and `token.symbol` should not vary between locales).
3. Repeat using the next-most-specific locale until all locales have been applied.
When the `locales` extension is configured, clients should use this localized registry for all metadata.
##### Authchain Extension
The `authchain` extension is standardized for `IdentitySnapshot`s. When provided, `authchain` reduces the work and data required for clients to [verify the metadata](#chain-verified-identities) of a particular identity.
The `authchain` extension value must be an array of strings. The first string (index `0`) must be the hex-encoded [authbase transaction](#zeroth-descendant-transaction-chains) for the identity (the identity's authbase is this transaction's ID). Each subsequent string must be the next transaction in the authchain, and the final string must be the latest known [authhead transaction](#zeroth-descendant-transaction-chains) for the identity.
Clients may use the `authchain` extension to rapidly update their records for a particular identity using the following validation algorithm:
1. Verify that the string at index `0` is the authbase transaction by double sha-256 hashing it and verifying the result is equal to the identity's known authbase.
2. Decode each successive transaction in the authchain, verifying that an input in each transaction spends the identity output (output index `0`) of the previous transaction.
3. After verifying that the final transaction spends the identity output of the second-to-last transaction, attempt to verify that the identity output of the final transaction is currently present in the Unspent Transaction Output (UTXO) set:
1. If currently in the UTXO set, the authchain is verified and this transaction is the identity's authhead – [metadata verification](#chain-verified-identities) can proceed immediately.
2. If not in the UTXO set, attempt to [continue resolution](#authchain-resolution) from this transaction. (The identity may have been updated since the registry was published.)
4. If any of these verifications fail – or if continued resolution from the last transaction fails, notify the user that registry's view of the chain has diverged from that of the client. (For trusted registries, this may indicate a network split or a client software bug; in other cases, this may indicate a flaw in the registry.)
### Guidelines for Token Issuers
If additional fungible tokens may be needed in the future, token issuers should initially mint an excess supply and hold them in the identity output with a [mutable token](https://github.com/bitjson/cashtokens#token-types) (using any `commitment` value) to indicate they are part of the [Reserved Supply](https://github.com/bitjson/cashtokens#reserved-supply). This enables light-client verification of the maximum possible [Circulating Supply](https://github.com/bitjson/cashtokens#circulating-supply).
### Guidelines for Client Software
The following recommendations are made for wallets, indexers, and other client software.
#### Adding and Updating Registries
To prevent malicious registries from causing users to misidentify tokens, clients should attempt to verify that newly imported identities are not impersonating identities that might be recognized by the user.
It is recommended that all supporting client software include at least one [embedded registry](#embedded-registries) to serve as a basis for anomaly detection. Additionally, clients should include a list of **reserved token symbols** that trigger further verification when used to represent token identities imported via metadata registries. For reference, this repository includes two sample lists [`reserved-token-symbols-ISO-4217.json`](./reserved-token-symbols-ISO-4217.json) (based on [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217)) and [`reserved-token-symbols-cryptocurrencies.json`](./reserved-token-symbols-cryptocurrencies.json) (top 100 cryptocurrencies by market cap at initial publication).
When adding or updating a registry, clients should perform basic validation of the newly-received registry:
1. Using the client's existing registries, build a mapping of identity `token.symbol` values to known authbases.
2. Iterating through the newly-received registry, verify that each new `token.symbol`:
1. Passes token symbol validation. (Regular expression: `/^[-A-Z0-9]+$/`)
2. Maps to the same authbase in existing registries as is represented in the new registry.
3. Does not appear on the client's list of reserved token symbols.
If this validation fails, clients should either:
- Notify users of each collision and request user confirmation that each newly-imported identity is acceptable;
- Refuse to import new identities that failed validation; or
- Refuse to import the new registry.
#### Handling Identity Snapshot Migrations
Each `IdentitySnapshot` must indicate a `time.begin` at which the snapshot begins to take effect. If no `time.complete` is provided, the snapshot's migration is considered **instant**: the new information should be displayed immediately after the specified time has been reached. If `time.complete` is provided, the snapshot's migration is considered **gradual**: the migration period begins at `time.begin` and should be complete by `time.complete`. Clients are encouraged to surface both kinds of migrations to users.
**Where possible, clients should notify users about upcoming and recent migrations that impact in-use identities.**
Note that while it is technically possible for registries to encode two overlapping migrations, clients should only attempt to use information from the latest migration (between the snapshots at index `0` and `1`). When validating registries, `IdentityHistory`s with out-of-order snapshots (i.e. snapshots are not ordered by `time.begin` with the latest snapshot at index `0`) or overlapping migrations should be considered malformed, and clients may refuse to accept malformed registries.
## Test Vectors
[TODO: after initial public feedback]
## Implementations
[TODO: after initial public feedback]
## Feedback & Reviews
- [CHIP-BCMR Issues](https://github.com/bitjson/chip-bcmr/issues)
<!-- - [`CHIP 2022-10 BCMR: Bitcoin Cash Metadata Registries` - Bitcoin Cash Research](https://bitcoincashresearch.org/t/) -->
## Changelog
This section summarizes the evolution of this document.
- **Draft**
- Initial publication
## Copyright
This document is placed in the public domain.
reserved-token-symbols-ISO-4217.json
+182
View File
@@ -0,0 +1,182 @@
[
"AED",
"AFN",
"ALL",
"AMD",
"ANG",
"AOA",
"ARS",
"AUD",
"AWG",
"AZN",
"BAM",
"BBD",
"BDT",
"BGN",
"BHD",
"BIF",
"BMD",
"BND",
"BOB",
"BOV",
"BRL",
"BSD",
"BTN",
"BWP",
"BYN",
"BZD",
"CAD",
"CDF",
"CHE",
"CHF",
"CHW",
"CLF",
"CLP",
"COP",
"COU",
"CRC",
"CUC",
"CUP",
"CVE",
"CZK",
"DJF",
"DKK",
"DOP",
"DZD",
"EGP",
"ERN",
"ETB",
"EUR",
"FJD",
"FKP",
"GBP",
"GEL",
"GHS",
"GIP",
"GMD",
"GNF",
"GTQ",
"GYD",
"HKD",
"HNL",
"HRK",
"HTG",
"HUF",
"IDR",
"ILS",
"INR",
"IQD",
"IRR",
"ISK",
"JMD",
"JOD",
"JPY",
"KES",
"KGS",
"KHR",
"KMF",
"KPW",
"KRW",
"KWD",
"KYD",
"KZT",
"LAK",
"LBP",
"LKR",
"LRD",
"LSL",
"LYD",
"MAD",
"MDL",
"MGA",
"MKD",
"MMK",
"MNT",
"MOP",
"MRU",
"MUR",
"MVR",
"MWK",
"MXN",
"MXV",
"MYR",
"MZN",
"NAD",
"NGN",
"NIO",
"NOK",
"NPR",
"NZD",
"OMR",
"PAB",
"PEN",
"PGK",
"PHP",
"PKR",
"PLN",
"PYG",
"QAR",
"RON",
"RSD",
"CNY",
"RUB",
"RWF",
"SAR",
"SBD",
"SCR",
"SDG",
"SEK",
"SGD",
"SHP",
"SLE",
"SOS",
"SRD",
"SSP",
"STN",
"SVC",
"SYP",
"SZL",
"THB",
"TJS",
"TMT",
"TND",
"TOP",
"TRY",
"TTD",
"TWD",
"TZS",
"UAH",
"UGX",
"USD",
"USN",
"UYI",
"UYU",
"UYW",
"UZS",
"VED",
"VES",
"VND",
"VUV",
"WST",
"XAF",
"XAG",
"XAU",
"XBA",
"XBB",
"XBC",
"XBD",
"XCD",
"XDR",
"XOF",
"XPD",
"XPF",
"XPT",
"XSU",
"XTS",
"XUA",
"XXX",
"YER",
"ZAR",
"ZMW",
"ZWL"
]
reserved-token-symbols-cryptocurrencies.json
+102
View File
@@ -0,0 +1,102 @@
[
"1INCH",
"AAVE",
"ADA",
"ALGO",
"APE",
"APT",
"ATOM",
"AVAX",
"AXS",
"BAT",
"BCH",
"BIT",
"BNB",
"BNX",
"BSV",
"BTC",
"BTT",
"BUSD",
"CAKE",
"CHZ",
"COMP",
"CRO",
"CRV",
"CSPR",
"CVX",
"DAI",
"DASH",
"DCR",
"DOGE",
"DOT",
"EGLD",
"ENJ",
"ENS",
"EOS",
"ETC",
"ETH",
"ETHW",
"FEI",
"FIL",
"FLOW",
"FTM",
"FTT",
"GRT",
"GT",
"HBAR",
"HNT",
"HOT",
"HT",
"ICP",
"KAVA",
"KCS",
"KLAY",
"LDO",
"LEO",
"LINK",
"LRC",
"LTC",
"LUNC",
"MANA",
"MATIC",
"MINA",
"MIOTA",
"MKR",
"NEAR",
"NEO",
"NEXO",
"OKB",
"PAXG",
"QNT",
"RUNE",
"RVN",
"SAND",
"SHIB",
"SNX",
"SOL",
"STX",
"THETA",
"TON",
"TRX",
"TUSD",
"TWT",
"UNI",
"USDC",
"USDD",
"USDN",
"USDP",
"USDT",
"USTC",
"VET",
"WAVES",
"WBTC",
"XCN",
"XDC",
"XEC",
"XLM",
"XMR",
"XRP",
"XTZ",
"ZEC",
"ZIL"
]