    CIP: 5
    Title: Subassets
    Author: JP Janssen (fork from Jeremy Johnson's CIP 4)
    Status: Draft
    Type: Standards
    Created: 2016-03-04

Abstract

Establishes a protocol for issuing subassets

(ex. PIZZA, PIZZA.DOMINOS, PIZZA.DOMINOS.COUPON, PIZZA.DOMINOS.COUPON-5-OFF)

Motivation

To enable named asset owners the ability and flexibility to issue new easily identified and related named assets. It will make the namespace appear more orderly for end users.

This proposal is identical to CIP 4 except for strickter name rules and lower issuance fee.

Definitions

asset

An ordinary alphabetic asset with right to issue a subasset

subasset

A numeric asset, issued by owner of an asset, whose longname is according to subasset rules

longname

An alphabetical string which indicates the full subasset name (_ex._ `PIZZA`, `PIZZA.DOMINOS`, `PIZZA.DOMINOS.COUPON`, `PIZZA.DOMINOS.COUPON-5-OFF`)

Specifications

Longnames must meet following requirements :
- Max 30 characters in length (e.g. PIZZA.X or [email protected])
- Contain only characters : A-Z0-9.-@
- Must begin with an asset owned by the issuer followed by a period (.)
- Cannot start or end with a period (.), dash (-), or alpha (@)
- Cannot contain consecutive non-alphanumeric characters [.-@]
Subasset can only be issued from the same address that owns the parent asset at the time of the issuance.
Subasset can be transferred to a new owner address after initial issuance (if necessary)
Subasset has issuance cost of 0.05 XCP (anti-spam)

Differences from CIP 4

Max length is 30, not 250
Lowercase letters are not allowed
Exclamation point and underscore are not allowed
Cannot contain consecutive non-alphanumeric characters [.-@]
Issuance fee is 0.05 XCP, not 0.25 XCP

Reasons for differences

The longname, not the number, is what should be displayed in wallets. A too long name is confusing and impractical
Names must be easy to differentiate. Not allowing lowercase chars makes the namespace cleaner, as well as prevents potential misunderstandings, e.g. if there were both a PIZZA.DOMINOS and PIZZA.Dominos
Exclamation point and underscore may cause confusion and adds little value, e.g. PIZZA.DOMINOS vs PIZZA.DOMINOS!
An issuance fee is not needed to prevent squatting because the asset owner has the sole right to issue subassets. A fee may only be needed to discourage massive automated registrations that could slow down the CP server. A fee of 0.05 XCP ensures this while it's low enough to keep subassets affordable even if XCP increases significantly in price.

#Changes

Database

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:

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
When issuing a valid subasset (issuance.compose):
- Issue random numeric asset and set description to EXISTING DESCRIPTION + 3b3b6C50495a5a412e444f4d494e4f53
```
(hex) 3b3b6C50495a5a412e444f4d494e4f53
(text) ;;lPIZZA.DOMINOS

;; = marks start of key/value pairs
l  = longname

PIZZA.DOMINOS = long asset name
```
When parsing/reparsing issuance transactions (issuance.parse):
- After block X, description.rsplit('3b3b',1) to get any name/value pairs.
- Create issuance record
- If name/value pairs are present
  - Decode name/value pairs from hex to text
  - Parse in longname
- If longname is present
  - 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

API

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.XMAS-16

payload = {
   "method": "create_issuance",
   "params": {
              "source": "1Mqn41zrgRKXRjwkT8MZ3ENhyrKy5nWJVW",
              "asset": "PIZZA.DOMINOS.CPN.XMAS-16",
              "quantity": 0,
              "divisible": true,
              "description": "Dominos pizza customer loyalty coupon"
             },
   "jsonrpc": "2.0",
   "id": 0,
}

Jpja/Counterparty Subassets Proposal.md