cip-0004.md

    CIP: 4
    Title: Subassets
    Author: Jeremy Johnson (J-Dog)
    Discussions-To: https://counterpartytalk.org/t/subassets-a-proposal/1690/27
    Status: Active
    Type: Standards
    Created: 2016-01-29

Abstract

Establishes a protocol for issuing subassets

(ex. PIZZA, PIZZA.DOMINOS, PIZZA.DOMINOS.COUPON, PIZZA.Dominos.Coupon!)

Motivation

To enable named asset owners the ability and flexibility to issue new easily identified and related named assets.

Definitions

asset

A named asset which acts as PARENT to a subasset

subasset

A numeric asset which is a CHILD of a named asset

longname

A alphabetical string which indicates the full subasset name (_ex._ PIZZA.DOMINOS, PIZZA.dominos, PIZZA.DoMiNoS.Coupon )

Specifications

1. Subasset names must meet following requirements :

   • 1 to 250 characters in length (ie. PIZZA.X or PIZZA.REALLY-long-VALID-Subasset-NAME)
   • Contain only characters : a-zA-Z0-9.-_@!
   • Cannot start or end with a period (.)
   • Cannot contain multiple consecutive periods (..)

2. Subasset can only be issued from same address that owns the parent asset at the time of the issuance.

3. Subasset can be transferred to a new owner address after initial issuance (if necessary)

4. Subasset has issuance cost of 0.25 XCP (anti-spam)

Changes

Database

1. Add asset_longname TEXT UNIQUE field to Assets table

Issuances

Given the example of asset PIZZA and subasset PIZZA.DOMINOS counterparty-lib would require the following changes:

1. When validating a subasset issuance attempt (issuance.validate):

   • Verify that issuing address is owner of PIZZA asset.
   • Verify that PIZZA.DOMINOS does not already exist by checking asset_longname for PIZZA.DOMINOS

2. When issuing a valid subasset (issuance.compose):

   • Issue random numeric asset
   • Use a new subasset issuance transaction id (21)
   • Encode the subasset longname in a base68 compressed format

434e545250525459|00000015|01530821671b1001|0000000005f5e100|01|0a|58063e323088276f3551|59756d6d79
    |               |           |             |              |  |  |                    |
    |               |           |             |              |  |  |                    └─── Description - "Yummy"
    |               |           |             |              |  |  └─── Compacted subasset data - "PIZZA.DOMINOS"
    |               |           |             |              |  └─── Length of the compacted subasset name (up to 255) - 10
    |               |           |             |              └─── divisible (1 byte)
    |               |           |             └───── quantity (8 bytes) - 100000000
    |               |           └──────────────── asset name (8 bytes) - A95428956661682177 (26**12 + 1)
    |               └────────────────── Type ID (4 bytes) - type 21/subasset
    └────────────────── Prefix of "CNTRPRTY"

3. When parsing/reparsing issuance transactions (issuance.parse):
   • After block X, read the subasset name from messages with type 21
   • parse and validate the subasset longname
     • Verify that asset is numeric and this is first issuance.
     • Verify that issuing address is owner of PIZZA asset.
     • Verify that PIZZA.DOMINOS does not already exist by checking asset_longname for PIZZA.DOMINOS
   • If longname is valid
     • Update Assets table to set asset_longname to longname value
   • Create issuance record

Reissuances

1. When calling the create_issuance API method for reissuance, the asset can be identitifed by either the numeric asset or the longname.

API

1. When making requests to get asset information (get_issuances & get_asset_info):
   • return new asset_longname value (if any)

API Examples

Asset Issuances

Issue the named asset PIZZA.

payload = {
   "method": "create_issuance",
   "params": {
              "source": "1Mqn41zrgRKXRjwkT8MZ3ENhyrKy5nWJVW",
              "asset": "PIZZA",
              "quantity": 0,
              "divisible": true,
              "description": "Pizza is good",
             },
   "jsonrpc": "2.0",
   "id": 0,
}

Issue a random numeric asset with the asset_longname field set to PIZZA.DOMINOS

payload = {
   "method": "create_issuance",
   "params": {
              "source": "1Mqn41zrgRKXRjwkT8MZ3ENhyrKy5nWJVW",
              "asset": "PIZZA.DOMINOS",
              "quantity": 0,
              "divisible": true,
              "description": "Dominos pizza is really good"
             },
   "jsonrpc": "2.0",
   "id": 0,
}

Issue a random numeric asset with the asset_longname field set to PIZZA.DOMINOS.Coupon.Christmas.2016!

payload = {
   "method": "create_issuance",
   "params": {
              "source": "1Mqn41zrgRKXRjwkT8MZ3ENhyrKy5nWJVW",
              "asset": "PIZZA.DOMINOS.Coupon.Christmas.2016!",
              "quantity": 0,
              "divisible": true,
              "description": "Dominos pizza customer loyalty coupon"
             },
   "jsonrpc": "2.0",
   "id": 0,
}