Cardano Improvement Proposals


CIP 14 - User-Facing Asset Fingerprint

Contents

Abstract

This specification defines a user-facing asset fingerprint as a bech32-encoded blake2b-160 digest of the concatenation of the policy id and the asset name.

Motivation

The Mary era of Cardano introduces the support for native assets. On the blockchain, native assets are uniquely identified by both their so-called policy id and asset name. Neither the policy id nor the asset name are intended to be human-readable data.

On the one hand, the policy id is a hash digest of either a monetary script or a Plutus script. On the other hand, the asset name is an arbitrary bytestring of up to 32 bytes (which does not necessarily decode to a valid UTF-8 sequence). In addition, it is possible for an asset to have an empty asset name, or, for assets to have identical asset names under different policies.

Because assets are manipulated in several user-facing features on desktop and via hardware applications, it is useful to come up with a short(er) and human-readable identifier for assets that user can recognize and refer to when talking about assets. We call such an identifier an asset fingerprint.

Specification

We define the asset fingerprint in pseudo-code as:

assetFingerprint := encodeBech32
      ( datapart = hash
        ( algorithm = 'blake2b'
        , digest-length = 20
        , message = policyId | assetName
        )
      , humanReadablePart = 'asset'
      )
    

where | designates the concatenation of two byte strings. The digest-length is given in bytes (so, 160 bits).

Rationale

Design choices

Security Considerations

Backwards Compatibility

N/A

Reference Implementation

Haskell (GHC >= 8.6.5)

Language Extensions

{-# LANGUAGE OverloadedStrings #-}
    {-# LANGUAGE QuasiQuotes #-}
    {-# LANGUAGE TypeApplications #-}
    

Imports

-- package: base >= 4.0.0
    import Prelude
    import Data.Function
        ( (&) )
    
    -- package: bech32 >= 1.0.2
    import qualified Codec.Binary.Bech32 as Bech32
    
    -- package: bech32-th >= 1.0.2
    import Codec.Binary.Bech32.TH
        ( humanReadablePart )
    
    -- package: bytestring >= 0.10.0.0
    import Data.ByteString
        ( ByteString )
    
    -- package: cryptonite >= 0.22
    import Crypto.Hash
        ( hash )
    import Crypto.Hash.Algorithms
        ( Blake2b_160 )
    
    -- package: memory >= 0.14
    import Data.ByteArray
        ( convert )
    
    -- package: text >= 1.0.0.0
    import Data.Text
        ( Text )
    

newtype PolicyId = PolicyId ByteString
    newtype AssetName = AssetName ByteString
    newtype AssetFingerprint = AssetFingerprint Text
    
    mkAssetFingerprint :: PolicyId -> AssetName -> AssetFingerprint
    mkAssetFingerprint (PolicyId policyId) (AssetName assetName)
        = (policyId <> assetName)
        & convert . hash @_ @Blake2b_160
        & Bech32.encodeLenient hrp . Bech32.dataPartFromBytes
        & AssetFingerprint
      where
        hrp = [humanReadablePart|asset|]
    

Test Vectors

:information_source: policy_id and asset_name are hereby base16-encoded; their raw, decoded, versions should be used when computing the fingerprint.

- policy_id: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc373
      asset_name: ""
      asset_fingerprint: asset1rjklcrnsdzqp65wjgrg55sy9723kw09mlgvlc3
    
    - policy_id: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc37e
      asset_name: ""
      asset_fingerprint: asset1nl0puwxmhas8fawxp8nx4e2q3wekg969n2auw3
    
    - policy_id: 1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209
      asset_name: ""
      asset_fingerprint: asset1uyuxku60yqe57nusqzjx38aan3f2wq6s93f6ea
    
    - policy_id: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc373
      asset_name: 504154415445
      asset_fingerprint: asset13n25uv0yaf5kus35fm2k86cqy60z58d9xmde92
    
    - policy_id: 1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209
      asset_name: 504154415445
      asset_fingerprint: asset1hv4p5tv2a837mzqrst04d0dcptdjmluqvdx9k3
    
    - policy_id: 1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209
      asset_name: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc373
      asset_fingerprint: asset1aqrdypg669jgazruv5ah07nuyqe0wxjhe2el6f
    
    - policy_id: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc373
      asset_name: 1e349c9bdea19fd6c147626a5260bc44b71635f398b67c59881df209
      asset_fingerprint: asset17jd78wukhtrnmjh3fngzasxm8rck0l2r4hhyyt
    
    - policy_id: 7eae28af2208be856f7a119668ae52a49b73725e326dc16579dcc373
      asset_name: 0000000000000000000000000000000000000000000000000000000000000000
      asset_fingerprint: asset1pkpwyknlvul7az0xx8czhl60pyel45rpje4z8w
    

Copyright

CC-BY-4.0