Estándar de Moneda de Aptos (Legacy)

Coin proporciona un framework estándar y seguro de tipos para tokens o monedas fungibles simples.

Una moneda se define en Move como:

module 0x1::coin {
  struct Coin<phantom CoinType> has store {
    /// Cantidad de moneda que tiene esta dirección.
    value: u64,
  }
}

Una Coin usa el CoinType para soportar la reutilización del framework Coin para monedas distintas. Por ejemplo, Coin<A> y Coin<B> son dos monedas distintas.

Coin también soporta un recurso para almacenar monedas en el almacenamiento global:

module 0x1::coin {
  struct CoinStore<phantom CoinType> has key {
    coin: Coin<CoinType>,
    frozen: bool,
    deposit_events: EventHandle<DepositEvent>,
    withdraw_events: EventHandle<WithdrawEvent>,
  }
}

La información o metadatos de la moneda se almacenan en el almacenamiento global bajo la cuenta del creador de la moneda:

module 0x1::coin {
  struct CoinInfo<phantom CoinType> has key {
    name: string::String,
    /// Símbolo de la moneda, generalmente una versión más corta del nombre.
    /// Por ejemplo, Dólar de Singapur es SGD.
    symbol: string::String,
    /// Número de decimales usados para obtener su representación de usuario.
    /// Por ejemplo, si `decimals` es igual a `2`, un saldo de `505` monedas debería
    /// mostrarse al usuario como `5.05` (`505 / 10 ** 2`).
    decimals: u8,
    /// Cantidad de este tipo de moneda en existencia.
    supply: Option<OptionalAggregator>,
  }
}

Coin proporciona las primitivas para usuarios que crean y gestionan la moneda y los usuarios que la usan.

Los creadores y gestores de monedas pueden:

• Inicializar una moneda y establecer sus metadatos y monitoreo de suministro.
• Acuñar y quemar valor de Coin.
• Quemar monedas de un CoinStore.
• Congelar la movilidad hacia y desde un CoinStore.

Los usuarios de monedas pueden:

• Fusionar dos estructuras Coin del mismo tipo.
• Extraer valor de una estructura Coin a una nueva estructura Coin.
• Capacidad de depositar y retirar de un CoinStore y emitir eventos como resultado.
• Permite a los usuarios registrar un CoinStore<CoinType> en su cuenta para manejar la moneda.

Las siguientes tablas describen campos a nivel de estructura. Para la lista definitiva, consulta el Framework de Aptos que contiene coin.

Un creador de moneda puede publicar un nuevo módulo en una cuenta de cadena de bloques que defina una estructura para representar un nuevo CoinType. El creador de moneda luego llamará coin:initialize<CoinType> desde esa cuenta para registrar esto como una moneda válida, y en retorno recibirá estructuras que permiten llamar a las funciones para quemar y acuñar monedas y congelar CoinStores. Estos necesitarán ser almacenados por el creador para gestionar el uso de la moneda.

module 0x1::coin {
  public fun initialize<CoinType>(
    account: &signer,
    name: string::String,
    symbol: string::String,
    decimals: u8,
    monitor_supply: bool,
  ): (BurnCapability<CoinType>, FreezeCapability<CoinType>, MintCapability<CoinType>) {
    // ...
  }
}

El creador tiene la oportunidad de definir un nombre, símbolo, decimales y si el suministro total de la moneda se monitorea. Esto aplica:

• Los primeros tres de los anteriores (name, symbol, decimals) son puramente metadatos y no tienen impacto para las aplicaciones de cadena de bloques. Algunas aplicaciones pueden usar decimal para equiparar una sola moneda de moneda fraccionaria.
• El monitoreo de suministro (monitor_supply) ayuda a rastrear el total de monedas en suministro. Sin embargo, debido a la forma en que el ejecutor paralelo funciona, activar esta opción impedirá cualquier ejecución paralela de acuñar y quemar. Si la moneda se acuñará o quemará regularmente, considere deshabilitar monitor_supply.

Si el creador o gestor desea acuñar monedas, deben obtener una referencia a su MintCapability, que se produjo en initialize, y llamar:

module 0x1::coin {
  public fun mint<CoinType>(
    amount: u64,
    _cap: &MintCapability<CoinType>,
  ): Coin<CoinType> acquires CoinInfo {
    // ...
  }
}

Esto producirá una nueva estructura Coin que contiene un valor según lo dictado por el amount. Si el suministro se monitorea, entonces también se ajustará.

Si el creador o gestor desea quemar monedas, deben obtener una referencia a su BurnCapability, que se produjo en initialize, y llamar:

module 0x1::coin {
  public fun burn<CoinType>(
    coin: Coin<CoinType>,
    _cap: &BurnCapability<CoinType>,
  ) acquires CoinInfo {
    // ...
  }
}

El creador o gestor también puede quemar monedas de un CoinStore:

module 0x1::coin {
  public fun burn_from<CoinType>(
    account_addr: address,
    amount: u64,
    burn_cap: &BurnCapability<CoinType>,
  ) acquires CoinInfo, CoinStore {
   // ...
  }
}

Si el creador o gestor desea congelar un CoinStore en una cuenta específica, deben obtener una referencia a su FreezeCapability, que se produjo en initialize, y llamar:

module 0x1::coin {
  public entry fun freeze_coin_store<CoinType>(
    account_addr: address,
    _freeze_cap: &FreezeCapability<CoinType>,
  ) acquires CoinStore {
    // ...
  }
}

Dos monedas del mismo tipo pueden fusionarse en una sola estructura Coin que representa el valor acumulado de las dos monedas independientemente llamando:

module 0x1::coin {
  public fun merge<CoinType>(
    dst_coin: &mut Coin<CoinType>,
    source_coin: Coin<CoinType>,
  ) {
    // ...
  }
}

Una Coin puede tener valor deducido para crear otra Coin llamando:

module 0x1::coin {
  public fun extract<CoinType>(
    coin: &mut Coin<CoinType>,
    amount: u64,
  ): Coin<CoinType> {
    // ...
  }
}

Un poseedor de un CoinStore puede extraer una Coin de un valor específico llamando:

module 0x1::coin {
  public fun withdraw<CoinType>(
    account: &signer,
    amount: u64,
  ): Coin<CoinType> acquires CoinStore {
    // ...
  }
}

Cualquier entidad puede depositar monedas en un CoinStore de una cuenta llamando:

module 0x1::coin {
  public fun deposit<CoinType>(
    account_addr: address,
    coin: Coin<CoinType>,
  ) acquires CoinStore {
    // ...
  }
}

Un poseedor de un CoinStore puede transferir monedas directamente de su cuenta a la cuenta de otro CoinStore llamando:

module 0x1::coin {
  public entry fun transfer<CoinType>(
    from: &signer,
    to: address,
    amount: u64,
  ) acquires CoinStore {
    // ...
  }
}

module 0x1::coin {
  struct DepositEvent has drop, store {
    amount: u64,
  }
}

module 0x1::coin {
  struct WithdrawEvent has drop, store {
    amount: u64,
  }
}