Title: Asset Definition Protocol Author: Flavien Charlon <flavien@charlon.net> Created: 2014-11-03
This document defines a process for associating metadata with an asset issued through the Open Assets Protocol.
Assets issued through the Open Assets Protocol represent value exiting outside of the Blockchain. Issuers need to be able to inform end-users about their assets and the conditions attached to them.
It is also important for an issuer to be able to prove their identity so that the user can decide whether or not to trust the issuer of an asset.
All of this can be handled transparently by client software, and this document describes a way to achieve this.
The metadata association process works in three stages:
- Blockchain association: The asset definition URL is embedded in the Blockchain by the issuer.
- Asset definition file: The asset definition file is created and made available at the specified URL.
- Proof of Authenticity (optional): SSL is used to guarantee the real-world identity of the issuer.
When issuing an asset, the issuer can associate it with a metadata file using a string called the asset definition pointer.
The asset definition pointer has the following format:
u=<asset definition URL>
or
u=<asset definition URL>&sha256=<sha256 hash>
or
h<binary hash160> (21 bytes)
Where <asset definition URL> is the absolute URL of the asset definition, and <sha256 hash> is the optional SHA-256 hash of the asset definition in hex format. Both values must be URL-encoded, and the asset definition pointer is encoded using UTF-8.
The asset definition URL can use any valid URI scheme (http, https, ftp, magnet, safe). Clients are free to choose which subset to support.
The compact form starting with h serves two purposes: to fit in the marker output (limited to 40 bytes by IsStandard checks as of May 2015) and to provide privacy for parties exchanging the asset. The compact form uses Bitcoin Hash160 function defined as RIPEMD-160(SHA-256(asset definition)). If the compact form is used, clients should use one or more pre-defined locations to fetch the data from. These could be generic well-known asset tracking servers or servers known for a given application or a given asset ID.
There are two ways to associate an asset definition pointer with an asset:
- Store it in the
metadatafield of the marker output when issuing the asset. - Issue the asset using a pay-to-script-hash output whose redeem script is constructed as follow:
PUSHDATA(<asset definition pointer>) OP_DROP [remainder of the script]
With the first method, the asset definition pointer can be changed by reissuing the asset. With the second method, the asset definition pointer cannot be changed without changing the asset ID, since the asset definition pointer is part of the issuance script, and therefore determines the asset ID.
The current asset definition file of a given asset is determined by clients using the following process:
The output script responsible for issuing the asset (of which the hash is equal to the asset ID) is determined, as well as the input script used to redeem it when the asset was issued.
If the following conditions are true:
- The output script is a pay-to-script-hash script
- The corresponding redeem script starts with a PUSHDATA followed by a OP_DROP
- The PUSHDATA payload is a valid asset definition pointer (as defined in the Blockchain association section)
Otherwise:
- All transactions where the first input is redeeming that script, and with a valid Open Assets marker output, are retrieved from the Blockchain.
- Transactions with an empty metadata field (zero bytes) in the marker output are excluded.
- The last of those transactions in Blockchain order (block number, then order within the block) is retained. If no such transaction if found, no metadata is associated to this asset.
- The metadata field of the marker output of that transaction is the asset definition pointer. If it has an incorrect format, no metadata is associated to this asset.
After the asset definition pointer is determined, the file stored at the given URL is retrieved. If a hash is provided in the asset definition pointer, the file is verified against it. If the file can not be retrieved or if the hash doesn't match, no metadata is associated to this asset.
The file is a JSON file using the following schema:
{
"asset_ids": [
"<base 58 asset id>"
],
"name_short": "<string>",
"name": "<string>",
"contract_url": "<url>",
"issuer": "<string>",
"description": "<string>",
"description_mime": "<mime type>",
"type": "<string>",
"divisibility": <integer>,
"link_to_website": <boolean>,
"icon_url": "<url>",
"image_url": "<url>",
"version": "<string>"
}
This table describes each field:
| Field | Description |
|---|---|
| asset_ids | (required) An array containing the base 58 representation of all the asset IDs authorized to use this asset definition file. Clients must verify that the ID of the asset is listed in this array. If the asset definition pointer was stored in the Blockchain using the pay-to-script-hash method (method 2 in the Blockchain association section), the asset ID to be included in this list is calculated by hashing only the remainder script (without the initial PUSHDATA and OP_DROP), to work around the circular dependency problem. |
| name_short | (required) A ticker used to denominate amounts of this asset, such as USD, MSFT, BTC. Clients may reject the asset definition if the value of this field is longer than 10 characters. |
| name | (required) The name of the asset. |
| contract_url | The URL containing more information about the asset. It must be usable by end users. |
| issuer | The name of the issuer. Clients may choose not to display this value as it is unverified. |
| description | A description of the asset. Clients must be able to support descriptions of at least 4096 characters. |
| description_mime |
The MIME type used to interpret the description field. By default, text/plain is assumed. Clients can choose which MIME types they support.
|
| type | The type of asset. |
| divisibility |
A signed integer indicating how many decimal places amounts of this asset can have. This changes how amounts are displayed. The displayed amount is obtained by taking the asset quantity and dividing it by 10^divisibility.
|
| link_to_website |
A boolean indicating whether proof of authenticity should be used. If set to false, proof of authenticity is disabled even if the SSL certificate is available and valid.
|
| icon_url | The URL to an icon representing the asset. The image file should be 48x48 pixels but clients should be able to handle images of a different format. |
| image_url | The URL to an image representing the asset. The image file should have a width of at least 260 pixels but clients should be able to handle images of a different format. |
| version |
A string which must be 1.0 for this version of the asset definition format.
|
The order of fields is not significant. If the file is not valid, no metadata is associated to the asset at the current time.
Proof of Authenticity is an optional step for the issuer to prove its identity, and associate it with the asset. It can only be used if the asset definition URL uses the https scheme.
Clients must extract the subject field of the SSL certificate presented by the web server when querying the metadata file. The subject is used as the issuer of the asset.
Clients must follow HTTP redirections when retrieving the asset metadata file, however, the full redirection chain must use HTTPS for the proof of authenticity to be valid. Furthermore, in case of redirections, the SSL certificate of the last resource is used for the purpose of proof of authenticity (i.e. the request that did not result in a redirection).
The issuer is not required to provide a hash of the asset definition file along with the URL and the definition may be changed at the issuer's discretion.
The asset metadata is provided by the issuer for informational purposes only, and should not be considered as a contract enforceable in court, unless specified otherwise by the issuer. Providing a framework for legally enforceable contracts is out of scope of this specification.