usdcx-token

.usdcx

;; token USDCx
;;
;; Este contrato implementa el trait SIP-010 para contratos fungibles.
;;
;; Este contrato utiliza un sistema de control de acceso basado en roles para gestionar permisos del protocolo.
;; Hay tres roles:
;;
;; - `governance`: Permitido para actualizar los contratos del protocolo y agregar/eliminar roles
;; - `mint`: Permitido para acuñar y quemar tokens
;; - `pause`: Permitido para pausar y reanudar el protocolo
;;

(impl-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait)

;; `tx-sender` o `contract-caller` intentó mover un token que no posee.
(define-constant ERR_NOT_OWNER (err u4))
;; `contract-caller` intentó usar una función para la que no está autorizado.
(define-constant ERR_UNAUTHORIZED (err u400))
;; Protocolo en pausa.
(define-constant ERR_PAUSED (err u401))

(define-fungible-token usdcx-token)

(define-data-var token-name (string-ascii 32) "USDCx")
(define-data-var token-symbol (string-ascii 10) "USDCx")
;; El URI SIP-16 para los metadatos del token
(define-data-var token-uri (optional (string-utf8 256)) (some u"https://ipfs.io/ipfs/bafkreifkhq47bgrlq2z2qgtps65eawgp6xsqkwldz57y2bjpefgo5zvza4"))
(define-constant token-decimals u6)

;; Permitido para actualizar los contratos del protocolo
(define-constant governance-role 0x00)
;; Permitido para acuñar y quemar tokens
(define-constant mint-role 0x01)
;; Permitido para pausar y reanudar el protocolo
(define-constant pause-role 0x02)

;; Permitir que el protocolo sea pausado
(define-data-var paused bool false)

;; Mapeo de contratos activos del protocolo (por rol)
(define-map active-protocol-contracts
  {
    caller: principal,
    role: (buff 1),
  }
  bool
)

;; El contrato .usdcx-v1 tiene automáticamente el rol `mint`
(map-set active-protocol-contracts {
  caller: .usdcx-v1,
  role: mint-role,
}
  true
)
;; Por defecto el desplegador del contrato tiene el rol `governance`
(map-set active-protocol-contracts {
  caller: tx-sender,
  role: governance-role,
}
  true
)

;; Funciones SIP-010

(define-public (transfer
    (amount uint)
    (sender principal)
    (recipient principal)
    (memo (optional (buff 34)))
  )
  (begin
    (asserts! (or (is-eq tx-sender sender) (is-eq contract-caller sender))
      ERR_NOT_OWNER
    )
    (try! (ft-transfer? usdcx-token amount sender recipient))
    (match memo
      to-print (print to-print)
      0x
    )
    (ok true)
  )
)

(define-read-only (get-name)
  (ok (var-get token-name))
)

(define-read-only (get-symbol)
  (ok (var-get token-symbol))
)

(define-read-only (get-decimals)
  (ok token-decimals)
)

(define-read-only (get-balance (who principal))
  (ok (ft-get-balance usdcx-token who))
)

(define-read-only (get-balance-available (who principal))
  (ok (ft-get-balance usdcx-token who))
)

(define-read-only (get-balance-locked (who principal))
  (ok (ft-get-balance usdcx-token who))
)

(define-read-only (get-total-supply)
  (ok (ft-get-supply usdcx-token))
)

(define-read-only (get-token-uri)
  (ok (var-get token-uri))
)

;; Validación de llamantes del protocolo

;; Verifica si contract-caller es un contrato del protocolo
(define-read-only (is-protocol-caller
    (contract-flag (buff 1))
    (contract principal)
  )
  (validate-protocol-caller contract-flag contract)
)

;; Valida que un principal dado sea un contrato del protocolo
(define-read-only (validate-protocol-caller
    (contract-flag (buff 1))
    (contract principal)
  )
  (begin
    ;; Comprueba que el llamante tenga el rol requerido
    (asserts!
      (default-to false
        (map-get? active-protocol-contracts {
          caller: contract,
          role: contract-flag,
        })
      )
      ERR_UNAUTHORIZED
    )
    (ok true)
  )
)

;; Pausa del protocolo

(define-read-only (is-protocol-paused)
  (var-get paused)
)

;; Valida que el protocolo no esté en pausa
(define-read-only (validate-protocol-active)
  (ok (asserts! (not (is-protocol-paused)) ERR_PAUSED))
)

;; --- Funciones del protocolo

;; Transferir tokens de una cuenta a otra.
;; Solo el rol `mint` puede llamar a esta función.
(define-public (protocol-transfer
    (amount uint)
    (sender principal)
    (recipient principal)
  )
  (begin
    ;; #[filter(amount, sender, recipient)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller mint-role contract-caller))
    (ft-transfer? usdcx-token amount sender recipient)
  )
)

;; Acuñar tokens a una cuenta.
;; Solo el rol `mint` puede llamar a esta función.
(define-public (protocol-mint
    (amount uint)
    (recipient principal)
  )
  (begin
    ;; #[filter(amount, recipient)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller mint-role contract-caller))
    (ft-mint? usdcx-token amount recipient)
  )
)

;; Quemar tokens de una cuenta.
;; Solo el rol `mint` puede llamar a esta función.
(define-public (protocol-burn
    (amount uint)
    (owner principal)
  )
  (begin
    ;; #[filter(amount, owner)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller mint-role contract-caller))
    (ft-burn? usdcx-token amount owner)
  )
)

;; Establecer el nombre del token.
;; Solo el rol `governance` puede llamar a esta función.
(define-public (protocol-set-name (new-name (string-ascii 32)))
  (begin
    ;; #[filter(new-name)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller governance-role contract-caller))
    (ok (var-set token-name new-name))
  )
)

;; Establecer el símbolo del token.
;; Solo el rol `governance` puede llamar a esta función.
(define-public (protocol-set-symbol (new-symbol (string-ascii 10)))
  (begin
    ;; #[filter(new-symbol)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller governance-role contract-caller))
    (ok (var-set token-symbol new-symbol))
  )
)

;; Establecer el URI SIP-16 para los metadatos del token.
;; Solo el rol `governance` puede llamar a esta función.
(define-public (protocol-set-token-uri (new-uri (optional (string-utf8 256))))
  (begin
    ;; #[filter(new-uri)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller governance-role contract-caller))
    (ok (var-set token-uri new-uri))
  )
)

;; Función auxiliar para acuñar tokens a múltiples destinatarios.
;; Solo el rol `mint` puede llamar a esta función.
(define-private (protocol-mint-many-iter (item {
  amount: uint,
  recipient: principal,
}))
  ;; #[allow(unchecked_data)]
  (ft-mint? usdcx-token (get amount item) (get recipient item))
)

;; Acuñar tokens a múltiples destinatarios.
;; Solo el rol `mint` puede llamar a esta función.
(define-public (protocol-mint-many (recipients (list 200 {
  amount: uint,
  recipient: principal,
})))
  (begin
    ;; #[filter(recipients)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller mint-role contract-caller))
    (ok (map protocol-mint-many-iter recipients))
  )
)

;; Establecer un llamante de protocolo activo.
;; Solo el rol `governance` puede llamar a esta función.
(define-public (set-active-protocol-caller
    (caller principal)
    (role (buff 1))
    (enabled bool)
  )
  (begin
    ;; #[filter(caller, role, enabled)]
    (try! (validate-protocol-active))
    (try! (validate-protocol-caller governance-role contract-caller))
    (map-set active-protocol-contracts {
      caller: caller,
      role: role,
    }
      enabled
    )
    (ok true)
  )
)

;; Pausar el protocolo.
;; Solo el rol `pause` puede llamar a esta función.
(define-public (pause)
  (begin
    (try! (validate-protocol-caller pause-role contract-caller))
    (print {
      topic: "pause",
      paused: true,
      caller: contract-caller,
    })
    (ok (var-set paused true))
  )
)

;; Reanudar el protocolo.
;; Solo el rol `pause` puede llamar a esta función.
(define-public (unpause)
  (begin
    (try! (validate-protocol-caller pause-role contract-caller))
    (print {
      topic: "pause",
      paused: false,
      caller: contract-caller,
    })
    (ok (var-set paused false))
  )
)

Resumen del Contrato USDCx-Token

Este contrato implementa USDCx, un token fungible SIP-010 en Stacks con un sistema de control de acceso basado en roles y funcionalidad de pausa para la seguridad del protocolo. Expone la interfaz estándar SIP-010 para transferencias, consultas de suministro y metadatos, mientras proporciona funciones sólo para el protocolo para acuñar, quemar, actualizaciones de gobernanza y pausa.

Roles

El contrato define tres roles privilegiados:

• Gobernanza (governance-role) – gestiona la configuración del protocolo, actualiza los metadatos del token y asigna roles.

• Acuñar (mint-role) – autorizado para acuñar, quemar y realizar transferencias a nivel de protocolo.

• Pausa (pause-role) – autorizado para pausar y reanudar el protocolo.

Una pausa del protocolo detiene las operaciones que cambian el estado por seguridad. El desplegador del contrato recibe automáticamente el gobernance rol. El contrato complementario .usdcx-v1 recibe automáticamente el mint rol.

---

Desglose Función por Función

Funciones Estándar SIP-010

transfer(amount, sender, recipient, memo)

Transfiere USDCx entre principales, siguiendo las reglas SIP-010. La función verifica que el remitente sea ya sea tx-sender o contract-caller (para contratos que gestionan custodia o bóvedas) y luego realiza la transferencia. Se registra en la cadena un memo opcional.

get-name(), get-symbol(), get-decimals()

Getters de metadatos estándar SIP-010 que devuelven el nombre del token, el símbolo y la precisión decimal.

get-balance(who), get-balance-available(who), get-balance-locked(who)

Devuelve el saldo de tokens para el principal dado. En esta implementación, las tres funciones de acceso devuelven el mismo valor de saldo SIP-010.

get-total-supply()

Devuelve la oferta total de USDCx acuñada menos la quemada.

get-token-uri()

Devuelve el URI de metadatos del token.

---

Validación de llamantes del protocolo

Estas funciones hacen cumplir los permisos basados en roles del contrato.

is-protocol-caller(role, contract)

Comprueba si el principal de contrato especificado posee el rol requerido.

validate-protocol-caller(role, contract)

Asegura que el llamante tenga el rol correcto. Si no, devuelve ERR_UNAUTHORIZED.

is-protocol-paused()

Devuelve si el protocolo está actualmente en pausa.

validate-protocol-active()

Asegura que el protocolo no esté en pausa, de lo contrario devuelve ERR_PAUSED.

---

Operaciones de Token Exclusivas del Protocolo

Estas funciones habilitan acuñación/quemado/transferencias exclusivamente para contratos de protocolo autorizados.

protocol-transfer(amount, sender, recipient)

Realiza una transferencia a nivel de protocolo en nombre de otro contrato. Sólo los llamantes con el rol mint pueden usarla. Falla si el protocolo está en pausa.

protocol-mint(amount, recipient)

Acuña nuevos USDCx a un principal. Restringido al rol mint y deshabilitado cuando está en pausa.

protocol-burn(amount, owner)

Quema tokens del saldo de un principal. También restringido al rol mint y deshabilitado cuando está en pausa.

protocol-mint-many(recipients)

Acuña por lotes tokens a múltiples destinatarios en una sola llamada. Cada elemento incluye { amount, recipient }. Sólo invocable por entidades con el rol mint.

---

Funciones de Gobernanza

Sólo el rol governance puede llamar a estas funciones.

protocol-set-name(new-name)

Actualiza el nombre SIP-010 del token.

protocol-set-symbol(new-symbol)

Actualiza el símbolo ticker SIP-010 del token.

protocol-set-token-uri(new-uri)

Actualiza el URI de metadatos SIP-016.

set-active-protocol-caller(caller, role, enabled)

Agrega o elimina un principal de un rol específico del protocolo. Se usa para rotar sistemas, actualizar contratos complementarios o delegar nueva responsabilidad.

---

Controles de Pausa

Estas funciones permiten al protocolo detener operaciones por seguridad o mantenimiento.

pause()

Pausa el contrato, deshabilitando acuñación, quemado y todas las acciones exclusivas del protocolo. Sólo invocable por el rol pause.

unpause()

Vuelve a habilitar el protocolo después de una pausa. También restringido al rol pause.

Ambas funciones emiten un evento on-chain para transparencia.