/** * 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[];