Contrato de Activo Stellar
El Contrato de Activo Stellar (SAC) es una implementación de CAP-46-6 Activo Estandarizado de Contrato Inteligente y [SEP-41 Interfaz de Token] para los activos Stellar.
Ve ejemplos de cómo usar el SAC en las Guías de Cómo Hacer Tokens.
Descripción general
Los activos Stellar son emitidos por cuentas Stellar. Emite un activo en Stellar siguiendo el Tutorial para Emitir un Activo.
El Contrato de Activo Stellar permite a usuarios y contratos realizar pagos con, e interactuar con, activos. El SAC puede interactuar con activos mantenidos por cuentas o contratos Stellar.
El SAC es un contrato incorporado especial que tiene acceso a la funcionalidad de la red Stellar que le permite usar activos Stellar directamente.
Cada activo Stellar tiene una instancia del SAC reservada en la red. Para usar el SAC reservado para un activo, solo necesita ser implementada la instancia.
Cuando el SAC transfiere activos entre cuentas, ocurren los mismos débitos y créditos que cuando se utiliza una operación de pago Stellar, porque el SAC interactúa directamente con las líneas de confianza de la cuenta Stellar. Cuando el SAC transfiere activos entre contratos, utiliza entradas del libro mayor de Datos del Contrato para almacenar los saldos de los contratos.
Los saldos de cuentas Stellar para el activo nativo siempre se almacenan en la cuenta, y los saldos de contratos Stellar para el activo nativo siempre se almacenan en una entrada de datos del contrato.
Los saldos de cuentas Stellar para activos emitidos siempre se almacenan en líneas de confianza, y los saldos de contratos Stellar para activos emitidos siempre se almacenan en una entrada de datos del contrato.
Por ejemplo, al transferir de una cuenta Stellar a un contrato Stellar, se debita la entrada de la línea de confianza de la cuenta Stellar y se acredita una entrada de datos del contrato.
Y, por ejemplo, al transferir de un contrato Stellar a una cuenta Stellar, se debita una entrada de datos del contrato y se acredita la entrada de la línea de confianza de la cuenta.
En ambos ejemplos, es un solo activo el que se transfiere de la cuenta al contrato y de regreso. No se requiere puente y no se necesitan tokens intermedios. Un activo en Stellar y su Contrato de Activo Stellar representan el mismo activo. El SAC de un activo es simplemente una API para interactuar con el activo.
El SAC implementa la Interfaz de Token SEP-41, que es similar al ampliamente utilizado estándar de token ERC-20. Los contratos que dependen solo de la parte SEP-41 de la interfaz del SAC, también son compatibles con cualquier token personalizado que implemente SEP-41.
Algunas funcionalidades disponibles en la red Stellar en operaciones de transacción, como el libro de órdenes, no tienen funciones expuestas en el Contrato de Activo Stellar en el protocolo actual.
Implementación
Cada activo Stellar en Stellar tiene una dirección de contrato reservada a la que se puede implementar el Contrato de Activo Stellar. Cualquiera puede iniciar la implementación y el emisor del activo Stellar no necesita estar involucrado.
Se puede implementar utilizando la CLI Stellar como se muestra aquí.
O se puede usar el SDK Stellar como se muestra aquí llamando a InvokeHostFunctionOp con HOST_FUNCTION_TYPE_CREATE_CONTRACT y CONTRACT_ID_FROM_ASSET. El recurso token tendrá un identificador determinista, que será el hash sha256 de HashIDPreimage::ENVELOPE_TYPE_CONTRACT_ID_FROM_ASSET xdr especificado aquí.
Cualquiera puede implementar las instancias del Contrato de Activo Stellar. Nota que la inicialización de los Contratos de Activo Stellar ocurre automáticamente durante la implementación. El emisor del activo tendrá los permisos administrativos después de que se haya implementado el contrato.
Interacción con activos clásicos de Stellar
El Contrato de Activo Stellar es la única manera para que los contratos interactúen con activos Stellar, ya sea el activo nativo XLM, o aquellos emitidos por cuentas Stellar.
El emisor del activo será el administrador del contrato implementado. Debido a que el token nativo Stellar no tiene un emisor, tampoco tendrá un administrador. Tampoco puede ser quemado.
Después de que se ha implementado el contrato, los usuarios pueden usar su saldo de cuenta clásica (para lúmenes) o línea de confianza (para otros activos). Hay algunas diferencias dependiendo de si estás usando una cuenta clásica Address vs un Address de contrato (correspondiente a un contrato regular o a un contrato de cuenta personalizado). La siguiente sección hace referencia a algunas banderas de emisor y línea de confianza de Stellar clásico, sobre las cuales puedes aprender más aquí.
- Usando
Address::Account- El saldo debe existir en una línea de confianza (o en una cuenta para el saldo nativo). Esto significa que el contrato no almacenará el saldo en ContractData. Si falta la línea de confianza o la cuenta, cualquier función que intente interactuar con ese saldo fallará.
- Se seguirán las Semánticas de Línea de Confianza clásicas.
- Las transferencias solo tendrán éxito si las líneas de confianza correspondientes tienen el
AUTHORIZED_FLAGconfigurado. - Un saldo de línea de confianza solo puede recuperarse usando la función de contrato
clawbacksi la línea de confianza tiene la banderaTRUSTLINE_CLAWBACK_ENABLED_FLAGconfigurada. - Las transferencias a la cuenta del emisor quemarán el token, mientras que las transferencias desde la cuenta del emisor acuñarán.
- Los saldos de la línea de confianza se almacenan en un entero con signo de 64 bits, aunque la interfaz acepta enteros con signo de 128 bits. Cualquier operación que intente enviar o recibir un monto mayor que el monto máximo que puede ser representado por un entero con signo de 64 bits fallará.
- Las transferencias solo tendrán éxito si las líneas de confianza correspondientes tienen el
- Usando
Address::Contract- El saldo y el estado de autorización se almacenarán en el almacenamiento del contrato, en lugar de una línea de confianza.
- Los saldos se almacenan en un entero con signo de 128 bits.
- Un saldo solo puede recuperarse si la cuenta del emisor tenía la bandera
AUTH_CLAWBACK_ENABLED_FLAGconfigurada cuando se creó el saldo. Un saldo se crea cuando unAddress::Contractestá en el extremo receptor de una transferencia exitosa, o si el administrador establece el estado de autorización. Lee más sobreAUTH_CLAWBACK_ENABLED_FLAGaquí.
Autorización de Saldo Requerida
En el caso de Address::Contract, si el emisor tiene la bandera AUTH_REQUIRED_FLAG configurada, entonces el Address::Contract especificado necesitará ser autorizado explícitamente con set_auth antes de poder recibir un saldo. Esta lógica se alinea con cómo interactúan las líneas de confianza con la bandera de emisor AUTH_REQUIRED_FLAG, permitiendo a los emisores de activos tener el mismo control en Soroban que tienen en Stellar clásico. Lee más sobre AUTH_REQUIRED_FLAG aquí.
Revocación de Autorización
El administrador solo puede revocar la autorización de un Address, si el emisor del activo tiene la bandera AUTH_REVOCABLE_FLAG configurada. La desautorización fallará si falta el emisor. Este requisito es verdadero tanto para los saldos de línea de confianza de Address::Account como para los saldos de contrato de Address:Contract. Nota que cuando una línea de confianza es desautorizada desde Soroban, la bandera AUTHORIZED_FLAG se borra y la bandera AUTHORIZED_TO_MAINTAIN_LIABILITIES_FLAG se establece para evitar tener que retirar ofertas y canjear participaciones en el fondo.
Semánticas de Autorización
Consulta la visión general de autorización y el ejemplo de autenticación para información general sobre autorización en Soroban.
El contrato de token contiene tres tipos de operaciones que siguen la interfaz:
- obtenedores, como
balance, que no cambian el estado del contrato - mutadores no privilegiados, como
incr_allowyxfer, que cambian el estado del contrato pero no requieren privilegios especiales - mutadores privilegiados, como
clawbackyset_admin, que cambian el estado del contrato pero requieren privilegios especiales
Los obtenedores no requieren autorización porque no cambian el estado del contrato y todos los datos del contrato son públicos. Por ejemplo, balance simplemente devuelve el saldo del Address especificado sin cambiarlo.
Los mutadores no privilegiados requieren autorización del Address que gasta o permite gastar su saldo. Las excepciones son las operaciones xfer_from y burn_from donde el Address requiere autorización de la entidad 'gastos' que ha recibido una autorización de otro Address previamente.
Los mutadores privilegiados requieren autorización de una identidad privilegiada específica, conocida como el "administrador". Por ejemplo, solo el administrador puede mint más del token. De manera similar, solo el administrador puede nombrar a un nuevo administrador.
Interfaz del Contrato
Esta interfaz se puede encontrar en el SDK. Extiende la común Interfaz de Token SEP-41.