Design for ARC20

[ghostant-1017]

---

arc: 35
title: Design for ARC20
authors: syyanyuhui@gmail.com
discussion: #35
topic: Application
status: Draft
created: 19/6/2023

Abstract

This ARC introduces a design for Fungible Tokens just like ERC20 which is upgradeable and extensible.

Data Structures

• Record Type
  • Credential: Credential is a record type that includes information about the token_id, owner, total_supplyand supplied indicates the amount already issued.
  • Token: Token is a record type that includes information about the owner, token_id , amount.
• Struct
  • Order: Order is a struct to store the exchange information.
  • Pair: Pair is a struct contains token_id and address. As leo doesn't support two-dimensional arrary yet, we can work around it. This is the key type of mapping balance.
• Mapping
  • balance: mapping(token_id, address) => u64 stores the public balance on chain.
  • exist: mapping exist: u64 => bool indicates whether certain token_id is registered or not. Maybe we can store the (address, total_supply) as the value.

Core Transitions

• register: This transiton will create a Credential which contains a unique token_id and determine the total_supply at the same time.
• drop: This transition destroy a Credential.
• mint: This transition need a Credential as one of inputs to mint the token which has the same token_id with Credential.
• transfer: This transition need a Token as one of inputs to transfer tokens to others.
• split: This transition splits Token into two parts.
• burn: This transition will destroy the token.

Extensional Transtions

• exchange: This transtion input a Token to exchange another token_id and amount.
• ...

Upgradeable Transitions for V2

When we want to add more features to ARC20, we can upgrade it to the v2 version using the following method.

• credentialv1_for_credentialv2: This transition will destory the Credential from arc20.aleo and create a new CredentialV2 from arc20_v2.aleo contains the same token_id.
• tokenv1_for_tokenv2: This transition will destroy the Token from arc20.aleo and create TokenV2 with the same token_id and amount.

Specification

// The 'arc20' program.
program arc20.aleo {
    record Credential {
        owner: address,
        token_id: u64,
        total_supply: u64,
        supplied: u64,
    }
    
    record Token {
        owner: address,
        token_id: u64,
        amount: u64,
    }
		
    mapping exist: u64 => bool;
    mapping balances: Pair => u64;
		
	// register
    transition register(public token_id: u64, public total_supply: u64) -> Credential {
        return Credential {
            owner: self.caller,
            token_id: token_id,
            total_supply: total_supply,
            supplied: 0u64,
        };
    }
    // Finalize to ensure the token_id is unique
    finalize register(token_id: u64) {
        let flag: bool = Mapping::get_or_use(exist, token_id, false);
        assert_eq(flag, false);
        Mapping::set(exist, token_id, true);
    }

    transition drop(c: Credential) {}

    transition mint(c: Credential, to: address, amount: u64) -> (Credential, Token) {
        assert(c.supplied + amount <= c.total_supply);
        let new_c: Credential = Credential {
            owner: c.owner,
            token_id: c.token_id,
            total_supply: c.total_supply,
            supplied: amount + c.supplyed
        };
        let t: Token = Token {
            owner: to,
            token_id: c.token_id,
            amount: amount
        };
        return (new_c, t);
    }
    transition transfer(t: Token, to: address, amount: u64) -> (Token, Token)  {
        let t1: Token = Token {
            owner: t.owner,
            token_id: t.token_id,
            amount: t.amount - amount,
        };
        let t2: Token = Token {
            owner: to,
            token_id: t.token_id,
            amount: amount,
        };
        return (t1, t2);
    }

    transition burn(t: Token) {}

    transition exchange(t: Token, expect_token_id: u64, expect_token_amount: u64) {
		// ...
    }
}

// The 'arc20_v2' program.
import arc20.leo;

program arc20_v2.aleo {
    record CredentialV2 {
        owner: address,
        token_id: u64,
        total_supply: u64,
        supplied: u64,
    }

    record TokenV2 {
        owner: address,
        token_id: u64,
        amount: u64,
    }

    struct PairV2{
        addr: address,
        token_id: u64,
    }
    mapping existV2: u64 => bool;
    mapping balancesV2: PairV2 => u64;

    // Destroy the token_v1 and create token_v2
    transition credentialv1_for_credentialv2(c1: arc20.leo/Credential.record) -> CredentialV2 {
        let c2: CredentialV2 = CredentialV2 {
            owner: c1.owner,
            token_id: c1.token_id,
            total_supply: c1.total_supply,
            supplied: c1.supplied,
        };
        arc20.leo/drop(c1);
        return c2;
    }
    
    transition tokenv1_for_tokenv2(t1: arc20.leo/Token.record) -> TokenV2{
        let t2: TokenV2 = TokenV2 {
            owner: t1.owner,
            token_id: t1.token_id,
            amount: t1.amount,
        };
        arc20.leo/burn(t1);
        return t2;   
    }

    // transfer 
    // mint 
}

Test Cases

Each case outlined in the specification of each feature should be tested.

Dependencies

Leo's current features already support it.

Backwards Compatibility

Everyone could choose to stay at v1 or upgrade to v2 or v3 v4... as they like!

Security & Compliance

There should be no regulatory concerns.

[evanmarshall]

Thank you for starting this discussion again. Linking from the previous discussion: #13

Pieces that are missing:

1. There should be both private and public methods for transferring and conversion between the states: transfer_private, transfer_public, convert_private_to_public, convert_public_to_private.
2. There should be a program_transfer. This would use self.parent to enable other contracts to lock up funds. Even though it's not implemented yet, we should add it to this spec.
3. We should consider using allowances which may be a better pattern for DApps than transferring: https://github.com/AleoHQ/sdk/pull/304/files#diff-34ed4dabecf71a6a2db55da718ffbd17767d9c7ec0245300e4da5a348ab0114eR4
4. I'm not sure if the token_id should be part of the record. We'll know which program it comes from and a symbol or something may be more appropriate once we can use public state without mappings ie const symbol = "...."
5. Exchange shouldn't be part of the standard. That should be a program on top.
6. When you upgrade a token contract, I'm not sure if you have to call burn. Does an imported record input to another program automatically get marked as spent?

[ghostant-1017]

For 4 && 5:
It is a different token design from ERC20. Since every ERC20's token need to deploy a contract separately.
In this design, someone who want to create his own token don't need to deploy their contract. He just only to register a unique token_id, and the token will be able to exchange automatically. All tokens share the program here.
For 6:
Imported record won't be marked as spent as it's a external record, you can check yourself.

[ghostant-1017]

For 1:
I will add these methods later.
For 2 & 3:
The opcode self.parent is quiet useful but I don't know if the opcode self.parent is easy and feasible to implement and it will not be implemented in the short term.

[jinqiao0423]

This is exactly same as what I considered. But currently there lacks some essential facilities in Leo language:

a. self.parent is needed for access control. Contract needs to know who is calling before performing any activities.

b. program id should be replaced by program address similar to evm, so that tokens can be transferred to program smoothly. Furthermore, programs should also be able to keep Aleo token, which can be very helpful to dex projects.

c. Public states as well as finalize function codes of a program should be accessable by other programs. Currently in Leo language design, an earlier published program cannot call a later one. This is not reasonable in case of finalize functions, as their bytecode is actually on chain. It might be practical to define whether a finalize function 'public' or not in contract code, so that public finalize functions can be called by other program without importing. This is essential especially in cases like allowance: an earlier deployed dex contract should be able to transfer a later deployed token.

Within these needed features self.parent is already on the plan, but I'm not sure about the latter 2. Is there any future plans for any similar features in Aleo project? Thx:)

[jinqiao0423]

Furthermore, I think it essential to support 2 other features in Aleo for arc-20 token standard to be applicable:

Firstly DYNAMIC CIRCUIT should be supported. Currently transitions cannot read or write values in mappings, as only static circuit are supported in Aleo. In other words, circuit's logic is solid once published. But this feature makes it impossible for a program to fetch another program's data storage, which is a must for programs to interact with each other. I.e. a Dex might want to know or extract the token balance of a specified address before actions. But this is currently impossible on Aleo.

Secondly interfaces or similiar things should be supported. Currently if a program want to call another one, the former must include the latter's code. This makes it impossible for older published programs to call newer ones. What's more, what we want to propose is something similiar to erc-20: a standard that everyone accept rather than a piece of code. Some basic logics should be kept the same, while higher level logic might be different.