Denominate fractional values in units

[bitbeckers]

Goal

Our hypercerts implementation expands on EIP1155 by making the tokens semi-fungible by default. We should both remain compliant with EIP1155 and expose methods for transfering value between tokens representing (a fraction of) the same claim.

Technical

EIP1155

All hypercert tokens are NFTs balanceOf(_owner, tokenID) => for all existing tokens, if owned by _owner should return 1

Hypercert

All hypercert tokens belonging to the same type should be fungible. In this case, fungible means:

• Merge the units held by tokens belonging to the same typeID
• Transfer units between tokens belonging to the same typeID
• Do not allow merge/transfer of tokens belonging to different typeID
• Minting fractions is adding new tokens with the same typeID and incrementing index

Hypercert -> claimID -> typeID -> tokenID (upper 128bits of uint256) HypercertFraction -> tokenID (upper 128 bits + index)

Implementations

• [x] Mint claim single fraction => generate typeID baseToken, generate 1st fractionToken Example (assume owner = creator):

• mint(10_000, "ipfs://exampleuenf83nufvresvn9"); creates baseToken (tokenID 10) creates fractionToken (tokenID11)

• balanceOf(creator, 10) = 1;

• balanceOf(creator, 11) = 1;

• uri(10) = "ipfs://exampleuenf83nufvresvn9";

• uri(11) = "ipfs://exampleuenf83nufvresvn9";

• unitsOf(10) = 10_000;

• unitsOf(11) = 10_000;

• unitsOf(creator, 10) = 10_000;

• unitsOf(creator, 11) = 10_000;

• safeTransferFrom(_from, _to, 11,10_000,"") reverts, value is 1

• safeTransferFrom(_from, _to, 11,1,"") transfers 11 to _to unitsOf(_to, 10) = 10_000;
  unitsOf(_to, 11) = 10_000; unitsOf(creator, 10) = 0;
  unitsOf(creator, 11) = 0;

• [x] Mint claim two fractions => generate typeID baseToken, generate fractionTokens Example (assume owner = creator):

• mint([10_000, 10_000], "ipfs://exampleuenf83nufvresvn9"); creates baseToken (tokenID 10) creates fractionToken (tokenID11) ** creates fractionToken (tokenID12)

• balanceOf(creator, 10) = 1;

• balanceOf(creator, 11) = 1;

• balanceOf(creator, 12) = 1;

• uri(10) = "ipfs://exampleuenf83nufvresvn9";

• uri(11) = "ipfs://exampleuenf83nufvresvn9";

• uri(12) = "ipfs://exampleuenf83nufvresvn9";

• unitsOf(10) = 20_000;

• unitsOf(11) = 10_000;

• unitsOf(12) = 10_000;

• unitsOf(creator, 10) = 20_000;

• unitsOf(creator, 11) = 10_000;

• unitsOf(creator, 12) = 10_000;

• safeTransferFrom(_from, _to, 11,1,"") transfers 11 to _to unitsOf(_to, 10) = 10_000;
  unitsOf(_to, 11) = 0; unitsOf(_to, 12) = 10_000; unitsOf(creator, 10) = 10_000;
  unitsOf(creator, 11) = 10_000; unitsOf(creator, 12) = 0;

[bitbeckers]

74

[ryscheng]

What's the difference between a claimId and a typeId?

In the following?

Hypercert -> claimID -> typeID -> tokenID (upper 128bits of uint256)

We've also used the terminology baseId, which I assume is the same as typeId right?

[bitbeckers]

Yes we should get that more clear. The terminalogy also changes because ClaimID is part of the hypercert spec, where other IDs belong to the SFTs:

• ClaimID is in the interface level and also used in the event emitted
• TypeID is a trait of SemiFungible1155, basically the upper 128 bits
• TokenID is the token used for reference in the 1155 contract. Can be both a claim entry (e.g. tokenID 10) or a fractional token (e.g. tokenID 11).
• BaseType is the upper 128 bits TokenID
• TokenID can also refer to a fractional token belonging to BaseType at a given index. The are the lower 128 bits of the TokenID

@ryscheng what would be the best way to simplify and/or document this?

[ryscheng]

Ah this is super helpful. Thanks for explaining.

Am I reading this right, that TypeID and BaseType are effectively the same thing? If so, I'm cool with combining those into 1 term.

Here's a strawman proposal:

• a TokenID is 256 bits.
• it consists of 2 parts, the upper 128 bits (TokenType). and the lower 128 bits (TokenIndex).
• The TokenType represents which hypercert we are talking about
• The TokenIndex represents which fraction of the hypercert

Then there's a question of what the claimID is then. Is the claimId just the TokenType?