Aleo Credits
Overview
The official currency of Aleo Network are called Aleo Credits. All fees paid for transactions, as well as rewards for staking and mining, are in the form of Aleo Credits.
Unlike other popular Blockchains like Ethereum, there is no special transfer transaction type. Instead, a native
program called credits.aleo governs transfers, usage, and ownership
of Aleo Credits. All value transfers on the Aleo Network are done by calling functions in the credits.aleo program
via Execute transactions. This enables users to send Aleo Credits privately, publicly, or a mix of both as well as
initiate staking and other advanced on-chain operations with Aleo credits.
Aleo Credits are denominated as either credits or microcredits, where the smallest unit is 1 microcredit (equal to 0.000001 credit). The credits.aleo program function parameters take amounts in microcredits. There is a denomination table here for reference.
The same credits.aleo program also hosts all staking-related functions and states. For more information about staking functionality, please refer to the Staking documentation.
A small selection of the credit transfer functions available in credits.aleo is visualized below:
Important distinction between function caller and transaction signer:
- Function Caller: The immediate function caller, which could be an intermediate program or contract that initiated the current function call
- Transaction Signer: The original transaction signer who initiated the entire transaction, regardless of how many intermediate programs are involved in the call chain
Private transfers or any functions involving records should use a private key controlled account address as the recipient. This is because:
- Records are encrypted with the recipient's public key and can only be decrypted with the corresponding private key
- A program address is derived from a hash function and has no associated private key, making it incapable of decrypting any records
- Records should never be sent to a program address because they would become permanently inaccessible
When performing private transfers or any operations involving records, always ensure the recipient is a user account address (controlled by a private key) rather than a program address.
Public/Private Credits
There are two main ways to hold Aleo Credits on the network:
Private Balances via credits Records
The first method is owning a credits record which enables a participant in the Aleo
network to hold a private balance of Aleo credits.
record credits:
owner as address.private;
microcredits as u64.private;
A user's total private credits balance will consist of all unspent credits records owned by the user with a non-zero
microcredits value. These records are analogous to UTXOs in Bitcoin. It is generally the responsibility of a wallet
application to scan the chain for records that belong to a user and determine which are spent and unspent in order
to calculate the user's total private balance and private transaction history.
Public Balances via the account Mapping
The second method is by holding a balance in the account mapping in the credits.aleo program on the Aleo network.
This mapping is an on-chain key-value store that is maintained and updated by Aleo validators at each block. This public balance is visible to all participants in the network and is analogous to the account balances in Ethereum.
mapping account:
key owner as address.public;
value microcredits as u64.public;
The total public credits balance of a user is the value of the account mapping at the user's address. Users can hold both private and public balances simultaneously.
Transferring Aleo Credits
There are five transfer functions available within credits.aleo.
transfer_private
Takes a credits record owned by the sender, subtracts an amount from it, and adds that amount
to a new record owned by the receiver. This function is 100% private and does not affect the account mapping.
Input Parameters:
credits.record- The sender's record containing the credits to transferaddress.private- The receiver's address (private)u64.private- The amount of microcredits to transfer in u64 (private)
transfer_private_to_public
Takes a credits record owned by the sender, subtracts an amount from it, and adds
that amount to the account mapping of the receiver. This function is 50% private and 50% public. It consumes a record
as a private input and generates a public balance in the account mapping entry belonging to the receiver.
Input Parameters:
credits.record- The sender's record containing the credits to transferaddress.public- The receiver's address (public)u64.public- The amount of microcredits to transfer in u64 (public)
transfer_public
Subtracts an amount of credits stored in the account mapping of the credits.aleo program, and
adds that amount to the account mapping of the receiver. This function is 100% public and does not consume or generate
any records.
Input Parameters:
address.public- The receiver's address (public)u64.public- The amount of microcredits to transfer in u64 (public)
The mapping key being modified is intermediate_program.aleo, which this is the "from" address in this transfer, not the transaction signer's address.
transfer_public_to_private
Subtracts an amount credits stored in the account mapping of the credits.aleo program
and adds that amount to a new private record owned by the receiver. This function is 50% private and 50% public.
It publicly consumes a balance in the account mapping entry belonging to the sender and generates a private record
as a private output.
Input Parameters:
address.private- The receiver's address (private)u64.public- The amount of microcredits to transfer in u64 (public)
The mapping key being modified is same as transfer_public, where the "from" address in this transfer is the immediate caller of the function. Not the signer's address, if there is an intermediate program in between.
transfer_public_as_signer
Similar to transfer_public, this function subtracts an amount of credits stored in the account mapping of the credits.aleo program, and adds that amount to the account mapping of the receiver. However, this function uses the signer's address as the sender instead of the caller's address, ensures that the "from" context is always the original transaction initiator. This function is 100% public and does not consume or generate any records.
Input Parameters:
address.public- The receiver's address (public)u64.public- The amount of microcredits to transfer in u64 (public)
The mapping key being modified is the transaction signer, which this is the "from" address in this transfer, not the intermediate program address.
A program can use transfer_public_from_signer to receive funds from a user to itself, then use transfer_public to transfer funds from itself back to the user.