Private Token API

ElGamal Structures

This section outlines two basic data structures utilized throughout our system. The ElGamal structure, holds the necessary fields to represent an ElGamal cyphered value within our system. Following that, we have the AmountInfo structure, used to represent token amounts and their associated details like ID and type. These are basic building blocks that you'll see reused in various parts of the system.

‍

The structure ElGamal has definition

struct ElGamal {
        Uint256 cl_x;
        Uint256 cl_y;
        Uint256 cr_x;
        Uint256 cr_y;
}

‍

The structure AmountInfo is defined as 

struct AmountInfo {       
  uint256 id;        
  uint256 token_type;    //ERC1155 token_type  (for ERC20 token, use 0)  
  Elgamal amount; 
};

‍

privateMint

This function has signature

/**
 * to: receipient of the minted amount
 * amountInfo: information of the minted private amount
 * proof: transaction's ZK proof 
 **/
function privateMint(
    address to, 
    AmountInfo calldata amountInfo, 
    bytes calldata proof
) external;

‍

privateReserveAmount

This function is for reserving amounts for future usage (e.g. burn, transfer). The reserved amounts will be put in the owner’s out-box.  It has signature

/**   
 * owner: token owner to reserve amount   
 * currentBalance: current balance of the owner 
 * newBalance: new balance of the owner after reservation  
 * reservedAmounts: a list of reserved private amounts  
 * proof: transaction's ZK proof 
 **/‍
function privateReserveAmount(
    address owner, 
    ElGamal memory currentBalance, 
    ElGamal memory newBalance, 
    AmountInfo[] memory reservedAmounts,
    bytes calldata proof
) external; 

‍

privateTransfer

This function will move a list of private amounts from msg.sender’s out-box to to_address’s in-box. This function has signature 

/**
 * to: receipient of the transfer 
 * amountIds:  ids of the reserved private amounts
 **/
function privateTransfer(address to, uint256[] memory amountIds) external; 

We can transfer a list of private amount Ids (including those with real zero amount) to make transaction tracing difficult.

‍

privateApprove

This function has signature 

Function privateApprove(address spender, uint256[] memory amountIds)

To approve, first call the function privateReserveAmount to reserve an amount, which will put the private amount in its owner’s out-box. This function is used to move the reserved amounts from the out-box to the approved-box.

‍

privateSplitApproval

This function is for splitting an approved private amount. The result amounts will still be put in the owner’s approved-box.  It has signature

/**
  Owner: token owner to split approval for 
  approvedAmount: approved amount to be split
  splitAmounts: the results
  Proof: zkp proof
**/

function privateSplitApproval(address owner, AmountInfo memory approvedAmount, AmountInfo[] memory splitAmounts, byte[] calldata proof) 

‍

privateTransferFrom

This function will move the approved private amount in the from_address’s approved-box to the to_address’s in-box. 

function privateTransferFrom(address from, address to, unit256[] memory amountIds)

‍

privateRollbackAmount

This function will rollback a private amount in the approved-box or out-box and to its owner’s in-box. It has signature 

function privateRollbackAmount(unit256 amountId)

‍

privateAllowance

This function has signature 

function privateAllowance(address owner, address spender) returns (memory ElGamal);

‍

privateBalanceOf

This function returns the total private amount in ElGamal format. It has signature 

function privateBalanceOf(address owner, uint256 token_type) returns  (memory ElGamal)

The total amount includes all private amounts in the owner's in-box, approved-box, and out-box.

‍

privateBurn

This function has signature

function privateBurn(uint256 amountId)

‍

‍