CIP: <unassigned>
Title: Blockchain Validated Asset Metadata (BVAM)
Author: Devon Weller <devon@tokenly.com>
Discussions-To: https://counterpartytalk.org/t/cip-proposal-blockchain-validated-asset-metadata-bvam/2210
Status: Draft
Type: Informational
Created: 2016-07-22
Blockchain Validated Asset Metadata provides a mechanism to define detailed information about a Counterparty asset. A hash of the information is stored in the bitcoin blockchain as proof that the metadata is validated by the issuer of the asset. Wallets and explorers can use untrusted data sources to retrieve the BVAM information and verify the both the integrity and ownership of the asset.
Counterparty provides a simple standard for enhanced asset info. This standard is useful, but is limited. It does not provide the fields needed by some tokens for use in the marketplace. The enhanced asset info standard requires a static URL and a trusted data source. It cannot be used for serverless peer-to-peer sharing of asset metadata.
The BVAM standard is more detailed, extensible and does not rely on a single central web server to host the asset metadata file. BVAM provides optional identity validation to prove ownership of a token.
The BVAM format is a superset of the enhanced asset info standard and maintains backwards compatibility.
The goals of this BVAM specification are as follows:
Standardized fields such as full ownership information and a suggested retail price (MSRP) make tokens more commerce friendly and facilitate legal compliance in some jurisdictions.
BVAM allows embedding arbitrary key/value data into the token data. This allows token users to embed their own validated metadata.
A BVAM json file may be provided by any source including untrusted ones. Wallet software can compare the hash of the data with the hash of the most recent Counterparty issuance transaction. If the hash matches, then the wallet has validated that the metadata is exactly what the issuer intended.
Some token issuers may want to prove their identity beyond the use of a PGP key. BVAM signatures allow issuers to validate their identity with a Certificate Authority. By signing the BVAM document with the private key of an x.509 (SSL) certificate, a company or individual can assert that they are the issuer of the token.
Companies can use an Extended Validation certificate to prove their company name as well as website address. Individuals can use inexpensive or free domain validation certificates from a service such as Let's Encrypt to prove ownership via a website address.
Here is BVAM v1.0.0-draft schema. It uses JSON Schema v4.
https://gist.github.com/deweller/319cc0f33ad7e7e57623
Here is some sample BVAM data that validates against the schema above validate it here:
https://gist.github.com/deweller/bc782720013eec7c95a465e7294b34ce
And here is the corresponding signature file:
https://gist.github.com/deweller/706bc856b668a392a068bba5c9ebbc5f
Here are the steps to hash the BVAM data
- Start with the string representation of the JSON.
- Optionally, sign the file with the private key of an x.509 certificate and append the signature to the string
- Hash the resulting string using SHA-256
- Hash the resulting binary data using RIPEMD-160
- Encode the resulting binary data using base58
- Prefix the resulting string with a T. (Note that a Category Schema uses a prefix of S instead of T)
The resulting hash looks like T2C11qRcpKTuGJSbSyneW61GbHZSG.
Here is javascript-like pseudocode demonstrating the process:
var jsonDataAsString = '{"asset": "A1111573289275", "name": "Tokenly VIP Gold Club Member"}';
var shaHexString = Crypto.SHA256(jsonDataAsString);
var hash160HexString = Crypto.RIPEMD160(Crypto.util.hexToBytes(shaHexString));
var base58EncodedString = Bitcoin.Base58.encode(Crypto.util.hexToBytes(hash160HexString));
var BVAMHash = "T"+base58EncodedString;Upload the BVAM json file and signature file to one or more BVAM providers or host your own. BVAM data is also suitable for publishing to decentralized peer-to-peer networks such as webtorrent or IPFS.
Broadcast a counterparty issuance transaction. In the description field, publish a URI in the description field. The URI should be in the format https://{hostname}{prefix}/{BVAM hash}.json.
The hostname and prefix are specific to one BVAM provider. But multiple BVAM providers can read this information and host the data. BVAM consumers will read the last path component and use that to derive the BVAM hash. Using a URI to publish the BVAM hash maintains backwards compatibility with the Enhanced Asset Info standard.
Note that any changes to the BVAM will require these 3 steps to be repeated.
Different categories of tokens need category-specific token metadata. One schema cannot possibly cover all of the metadata needed by different categories of tokens. A game currency token and a physical product token, for example, may require different sets metadata.
BVAM allows for a token to subscribe to one or more category schemas. Category schemas are optional metadata that are specific to a type of token. A Category Schema might be Car Title and define additional fields such as vin, vehicle_make, vehicle_model, and vehicle_year.
Every category schema has a unique name. To register a new category schema, upload the category schema dcoument to a public web server or BVAM provider and broadcast the following text from any address:
BVAMCS;ACME Car Title;1.0.0;https://bvam-provider.com/bvamcs/S4RGTgM6BJtuu2EUsvsG3GkTpGr2T.json
This text contains 5 elements, separated by a semicolon:
- The text
BVAMCS - The unique ID of the schema. This should be 128 characters or less in length. This can contain letters, numbers, spaces, dashes and underscores. IDs are case insensitive.
- The semantic version number if the category schema.
- A URL where the BVAM Category Schema may be found. The URL must end with the hash of the category schema document followed by
.json.
The hash of a BVAM Category Schema is calculated in the same way as a BVAM document by using a prefix of S instead of T.
The address of the first broadcaster becomes the owner of a given category schema ID. This owner address may broadcast future updates to the BVAM Category Schema with this ID by increasing the version number and providing a new URL.
Here is an example of a category schema.
Entities can prove the ownership of asset metadata by signing the BVAM JSON document with the private key from an x.509 (SSL) certificate. Individuals may use a cheap or free domain validated certificate to prove ownership by a website. Larger organizations may use an extended validation (EV) certificate that validates a company name via a certificate authority.
To prove ownership, the issuer generates a signature proving the authenticity of the BVAM JSON document. The issuer signs the sha256 digest of the full text of the BVAM JSON file using the private key of the x.509 certificate as the signing key. The result should be encoded in base64 format. Here is an example using openssl:
openssl dgst -sha256 -sign my-x509-private-key.pem bvam-source.json | openssl base64The x.509 certificate can be referenced by URL in BVAM JSON file as demonstrated in the example BVAM document. Alternatively, the full certificate chain can be embedded in PEM format using the attribute of "certificate_chain". Here is an example of including an embedded certificate chain.
"signature": {
"certificate_chain": "-----BEGIN CERTIFICATE-----
MIIGMzCCBRugAwIBAgISA1akaBYLeqqkm262kPQncG+UMA0GCSqGSIb3DQEBCwUA
MEoxCzAJBgNVBAYTAlVTMRYwFAYDVQQKEw1MZXQncyBFbmNyeXB0MSMwIQYDVQQD
( ...ommitted... )
5taH5TbZn9S878U/JkJkwQhDDKswFFl5Sw3VyA475nfkuVRpGUFS07jA634WBzes
1HIH6EuPRQ==
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEkjCCA3qgAwIBAgIQCgFBQgAAAVOFc2oLheynCDANBgkqhkiG9w0BAQsFADA/
( ...ommitted... )
KOqkqm57TH2H3eDJAkSnh6/DNFu0Qg==
-----END CERTIFICATE-----"
}A BVAM provider serves the BVAM data to wallet software using the https protocol. A provider must serve a json resource using a URI of https://{hostname}{prefix}/{BVAM hash}.json. The prefix is optional and may contain one or more URI path components.
The JSON document served must be the exact file or files that were hashed to derive the BVAM hash. No formatting changes are allowed after the document hash is determined.
For signed BVAM documents, the signature is served as a separate resource with a URI of https://{hostname}{prefix}/{BVAM hash}-signature.sha256.
The signature file must be the exact file used to derive the hash. No whitespace must be added or removed.
Say, for example, our BVAM provider hostname is "bvamprovider.com" and the prefix is "/bvam". The URIs from our example above would looks like the following:
- The BVAM JSON document would be served from
https://bvamprovider.com/bvam/T2C11qRcpKTuGJSbSyneW61GbHZSG.json. - The signature file, if it exists, would be served from
https://bvamprovider.com/bvam/T2C11qRcpKTuGJSbSyneW61GbHZSG-signature.sha256.
If there is no signature file available, the BVAM provider should return a not found response with an HTTP status code of 404.
Wallets and client software must validate BVAM data when it is received from a provider. The steps to validate the BVAM data are as follows:
- Obtain the most recent issuance transaction for a given asset from the blockchain. The client must extract the BVAM Hash from the URI in the description field of that issuance transaction.
- Request the BVAM JSON and BVAM signature files from a BVAM provider using this hash retrieved from the blockchain.
- Recompute the hash of the concatenated JSON file and any signature file.
- Check that the computed hash matches the hash published in the blockchain. The BVAM data is invalid if these hashes do not match.
- Compare the asset in the BVAM JSON document with the asset name of the issuance transaction. The BVAM data is invalid if the asset name is different.
If the steps above are completed then the client software can be assured that the BVAM document was created by the issuer of the asset.
The steps to validate the identity of the issuer are as follows:
- obtain the public key and the certificate chain. If a certificate chain is provided in the BVAM JSON file, use the public key and chain provided there. If a certificate location URI is provided, the client must contact the remote server and obtain the public key and certificate chain using the TLS handshake protocol.
- Validate that the certificate is valid with a trusted certificate authority.
- Verify that the signature is valid according to the public key of the x.509 certificate. Here is a sample script using openssl to verify the message:
openssl base64 -d < signature.base64 > signature.binary
openssl dgst -sha256 -verify pubkey.pem -signature signature.binary < BVAM.jsonIf the message is verified successfully, then the client software can be assured that the BVAM document was created by the owner of the x.509 (SSL) certificate.
BVAM schema is backwards compatible with the enhanced asset info specification.
The BVAM schema version may be updated in the future. All BVAM schemas are versioned using semantic versioning. Any BVAM schema with the major version of 1 will be backwards compatible with this schema and thus backwards compatible with the enhanced asset info specification.
This document is placed in the public domain.
This BVAM spec is based on Joe Looney's original idea for Blockchain Validated Asset Metadata.
Very good.
Just wonder if the RIPEMD160 and Base58.encode steps are necessary?
Why not let
var BVAMHash = "T"+ shaHexString;? AlternativelyshaBase64Stringor a truncated sha string?Base58 encoding isn't that straight forward without the Bitcoin library, i.e. for many programming languages.