Contrato inteligente de Dual Stacking

Resumen

El contrato de Doble Stacking permite a los participantes ganar recompensas sBTC aumentadas al mantener sBTC y, opcionalmente, hacer stacking de STX. Opera en ciclos con capturas periódicas (snapshots) para calcular las recompensas basadas en las tenencias y la participación en el stacking.

Para el contrato de doble stacking en mainnet en vivo, consulta la página del contrato aquí.

El 15 de diciembre de 2025, el contrato de doble stacking se actualizará a .dual-stacking-v2_0_2

Arquitectura Descentralizada

• Operaciones sin permisos: Cualquiera puede ejecutar operaciones críticas del ciclo, incluyendo la captura de snapshots, la propuesta/validación de la ratio, el cálculo de pesos y la distribución de recompensas.

• Solo datos on-chain: Todos los datos de los participantes (saldos sBTC, cantidades de STX en stacking) se leen directamente desde la cadena de bloques — no se requieren oráculos fuera de la cadena ni fuentes de datos de confianza.

• Descubrimiento competitivo de la ratio: Múltiples participantes pueden proponer diferentes ratios doradas; el sistema valida basado en criterios matemáticos (percentil 95), no en la aprobación de un administrador.

• Ejecución transparente: Todas las operaciones se ejecutan on-chain con resultados verificables y registros públicos de eventos.

• Inscripción autoservicio: Los usuarios pueden inscribirse, darse de baja y gestionar su participación de forma independiente.

Operaciones Principales

1

Inicialización

El contrato se inicializa una vez con un parámetro de altura de bloque Stacks que es el primero en el bloque de Bitcoin especificado, o después de él, en caso de que no haya bloques STX anclados a ese bloque.

2

Inscripción

Los usuarios pueden inscribirse por sí mismos para participar con direcciones de recompensa personalizadas. Los protocolos DeFi pueden ser inscritos por el administrador con seguimiento personalizado, direcciones de stacking y de recompensa. Todos los participantes pueden darse de baja o cambiar sus direcciones en cualquier momento.

3

Snapshots y Ciclos

Cualquiera puede desencadenar snapshots periódicos que capturan los saldos sBTC de los participantes y las cantidades de STX en stacking a partir de datos on-chain basados en intervalos de bloques predefinidos.

4

Cálculo de la Ratio

Después de completar los snapshots, cualquiera puede proponer una ratio dorada (ratio STX/sBTC óptima), contabilizar las distribuciones de los participantes y validar si su propuesta cumple el criterio del percentil 95 para determinar el punto de referencia de las recompensas máximas.

5

Cálculo de Pesos

Cualquiera puede desencadenar el cálculo de pesos de los participantes usando la fórmula de doble stacking validada que proporciona hasta 10x de impulso (configurable) para quienes cumplen o exceden la ratio dorada.

6

Recompensas

Cualquiera puede desencadenar la distribución de recompensas cada ciclo basada en los pesos calculados. Los administradores pueden actualizar configuraciones como APR, multiplicador de impulso de rendimiento, duración del snapshot y número de snapshots por ciclo.

7

Controles Administrativos

Los administradores mantienen los parámetros del protocolo, inscriben/dan de baja protocolos DeFi con configuraciones de direcciones especiales, gestionan listas blancas y negras, y pueden realizar operaciones de emergencia si es necesario.

---

Estructura del Ciclo

• Cada ciclo consiste en un número fijo de snapshots (por defecto 14).

• Cada snapshot ocurre después de un número establecido de bloques de Bitcoin (por defecto 150).

• La longitud total del ciclo es por tanto 2100 bloques de Bitcoin por defecto (14 snapshots × 150 bloques).

• Estos valores por defecto pueden ajustarse para entornos de producción (p. ej., 1 snapshot por día con el conteo de bloques apropiado).

Fórmula de Doble Stacking

Cálculo de Peso:

$$w_i = \cfrac{[B_i \cdot (1 + M \cdot \sqrt{r_i})]}{n}$$

Dónde:

• w_i = peso para el usuario i

• B_i = saldo sBTC del usuario i (suma a través de todos los snapshots)

• M = multiplicador de impulso de rendimiento (por defecto 9, lo que significa impulso máximo de 10x)

• r_i = min(d_i/D, 1), el factor de ajuste de la ratio

• d_i = S_i/B_i, ratio personal STX/sBTC del usuario

• S_i = STX en stacking por el usuario i (suma a través de todos los snapshots)

• D = ratio dorada (ratio STX/sBTC en el percentil 95 entre todos los participantes)

• n = número de snapshots por ciclo (por defecto 14)

Distribución de Recompensas:

$$R_i = (\frac{w_i}{Σw}) \cdot Total Rewards$$

Dónde:

• R_i = recompensa para el usuario i

• Σw = suma de todos los pesos de los participantes

• Recompensas Totales = min(saldo del pool, tope basado en APR)

Propiedades Clave:

• Participantes con d_i ≥ D reciben el impulso máximo de (M+1) x (por defecto 10x).

• Participantes con d_i = 0 (sin STX en stacking) reciben recompensas base (1x).

• El impulso escala con la raíz cuadrada de la ratio para valores intermedios.

• Las direcciones de seguimiento DeFi en la whitelist reciben automáticamente el impulso máximo sin necesidad de hacer stacking de STX.

• Los pesos se dividen por el número de snapshots por ciclo para normalizar a lo largo de la duración del ciclo.

---

Flujo de Trabajo del Ciclo

El contrato inteligente de Doble Stacking opera en ciclos, cada uno dividido en snapshots. El proceso asegura una distribución precisa de recompensas mediante una serie de operaciones sin permisos que cualquiera puede ejecutar.

1

Fase de Snapshot (Cualquiera Puede Ejecutar)

• capture-snapshot-balances: Cualquiera puede capturar saldos para usuarios inscritos después de cada snapshot.

• advance-to-next-snapshot: Cualquiera puede pasar al siguiente snapshot.

• finalize-snapshots: Cualquiera puede concluir todos los datos de snapshots después del snapshot final.

2

Fase de Validación de Ratio (Competitiva y Sin Permisos)

• propose-golden-ratio: Cualquiera puede proponer una ratio dorada.

• tally-participant-ratios: El proponente contabiliza las ratios de los participantes en relación con su ratio propuesta.

• validate-ratio: El proponente valida su propuesta — tiene éxito solo si representa el percentil 95.

• Se pueden presentar múltiples propuestas; la primera válida se fija para el ciclo.

3

Fase de Cómputo de Pesos (Cualquiera Puede Ejecutar)

• calculate-participant-weights: Cualquiera puede calcular los pesos de los participantes usando la fórmula de doble stacking.

• finalize-weight-computation: Cualquiera puede finalizar el cómputo de pesos.

4

Fase de Distribución de Recompensas (Cualquiera Puede Ejecutar)

• set-is-distribution-enabled: Cualquiera puede habilitar la distribución de recompensas determinando el pool de recompensas disponible.

• distribute-rewards: Cualquiera puede distribuir recompensas a los usuarios inscritos según sus pesos.

• finalize-reward-distribution: Cualquiera puede finalizar la distribución de recompensas después de que todos los participantes hayan sido recompensados.

5

Transición de Ciclo (Cualquiera Puede Ejecutar)

• advance-to-next-cycle: Cualquiera puede avanzar al siguiente ciclo después de que todas las recompensas hayan sido distribuidas.

Nota: Todas las operaciones leen datos directamente de la blockchain (saldos sBTC desde el contrato token sBTC, STX en stacking desde el protocolo nativo Stacks). No se requieren fuentes de datos fuera de la cadena ni intermediarios de confianza.

---

Funciones Públicas

1. Inicialización del Contrato

initialize-contract

Activa el contrato con un ciclo inicial.

• Parámetros: stx-block-height (uint)

• Afirmaciones:

  • La altura de bloque actual de Bitcoin debe ser >= a la altura de bloque de inicio del ciclo configurada.

  • El contrato no debe estar activo.

  • La altura del bloque Stacks debe abarcar la altura de bloque de Bitcoin configurada.

• Efecto:

  • Inicializa las variables de estado para el primer ciclo y marca el contrato como activo.

  • Registra los datos del ciclo y el primer snapshot.

update-initialize-block

Actualiza la altura de bloque de Bitcoin de inicialización antes de que el contrato sea activado.

• Parámetros: new-bitcoin-block-height (uint)

• Afirmaciones:

  • El contrato no debe estar activo.

  • El llamante debe ser el administrador.

• Efecto:

  • Actualiza la altura de bloque de inicio para el primer ciclo.

update-cycle-data-before-initialized

Actualiza tanto los snapshots por ciclo como los bloques por snapshot para el primer ciclo antes de la inicialización.

• Parámetros: updated-snapshots-per-cycle (uint), updated-blocks-per-snapshot (uint)

• Afirmaciones:

  • El contrato no debe estar activo.

  • El llamante debe ser el administrador.

• Efecto:

  • Establece la estructura del ciclo para el primer ciclo.

---

2. Inscripción

enroll

Inscribe al llamante para recibir recompensas en ciclos futuros.

• Parámetros: rewarded-address (principal opcional)

• Afirmaciones:

  • El llamante no debe estar ya inscrito.

  • El llamante no debe estar en la lista negra.

  • El llamante debe poseer al menos la cantidad mínima requerida de sBTC.

• Efecto:

  • Añade al llamante al mapa de participantes con las direcciones de tracking, stacking y rewarded configuradas apropiadamente.

  • Incrementa el conteo de participantes para el siguiente ciclo.

enroll-defi

Inscribe un protocolo DeFi para recompensas con direcciones personalizadas (solo administrador).

• Parámetros:

  • defi-contract (principal)

  • tracking-address (principal)

  • rewarded-address (principal)

  • stacking-address (principal opcional)

• Afirmaciones:

  • El llamante debe ser el administrador.

  • El contrato DeFi no debe estar ya inscrito.

  • El contrato DeFi no debe estar en la lista negra.

• Efecto:

  • Añade el protocolo DeFi al mapa de participantes con direcciones personalizadas.

  • Incrementa el conteo de participantes para el siguiente ciclo.

enroll-defi-batch

Inscripción por lotes de múltiples protocolos DeFi (solo administrador).

• Parámetros: defi-contracts (lista 900 {...})

• Afirmaciones:

  • El llamante debe ser el administrador.

• Efecto:

  • Inscribe múltiples protocolos DeFi en una sola transacción.

opt-out

Permite al llamante darse de baja de la participación en ciclos futuros.

• Afirmaciones:

  • El llamante debe estar inscrito.

• Efecto:

  • Elimina al llamante del mapa de participantes.

  • Decrementa el conteo de participantes para el siguiente ciclo.

opt-out-defi

Da de baja a un protocolo DeFi de la participación (solo administrador).

• Parámetros: defi-contract (principal)

• Afirmaciones:

  • El llamante debe ser el administrador.

  • El contrato DeFi debe estar inscrito.

• Efecto:

  • Elimina el protocolo DeFi del mapa de participantes.

opt-out-defi-batch

Baja por lotes de múltiples protocolos DeFi (solo administrador).

• Parámetros: defi-contracts (lista 200 principal)

• Afirmaciones:

  • El llamante debe ser el administrador.

• Efecto:

  • Da de baja múltiples protocolos DeFi en una sola transacción.

---

3. Gestión de Direcciones de Participantes

• change-reward-address

• change-reward-address-defi

• change-stacking-address-defi

• change-tracking-address-defi

• change-addresses-defi

• change-addresses-defi-batch

(Cada función tiene parámetros, afirmaciones de administrador donde corresponda, y actualiza las direcciones de participantes/DeFi como se describe en la especificación original.)

---

4. Snapshots y Ciclos

capture-snapshot-balances

Captura saldos de snapshot para una lista de participantes en la altura de bloque del snapshot actual. Sin permisos.

• Parámetros: principals (lista de hasta 900 principals)

• Afirmaciones:

  • El contrato debe estar activo.

  • La altura de bloque Stacks del snapshot actual debe estar disponible.

• Efecto:

  • Lee el saldo sBTC desde el contrato token sBTC para cada participante.

  • Lee la cantidad de STX en stacking desde el protocolo nativo Stacks (incluyendo stacking líquido si está habilitado).

  • Actualiza totales de snapshot y tenencias de participantes.

  • Rastrea direcciones de stacking y tracking.

advance-to-next-snapshot

Avanza el contrato al siguiente snapshot dentro del ciclo actual. Sin permisos.

• Parámetros: new-stx-block-height (uint)

• Afirmaciones:

  • El contrato debe estar activo.

  • Todos los participantes deben haber sido snapshoteados.

  • La altura de bloque actual de Bitcoin debe haber alcanzado el siguiente bloque de snapshot.

  • El ciclo no debe haber terminado.

  • La altura de bloque Stacks debe abarcar la siguiente altura de bloque de snapshot de Bitcoin.

• Efecto:

  • Incrementa el índice de snapshot.

  • Agrega los totales del snapshot a los totales del ciclo.

  • Restablece contadores de snapshot.

  • Registra las nuevas alturas de bloque del snapshot.

finalize-snapshots

Finaliza todos los snapshots para el ciclo actual después de que el último snapshot esté completo. Sin permisos.

• Afirmaciones:

  • El contrato debe estar activo.

  • Los snapshots no deben estar ya finalizados.

  • Debe estar en el último snapshot del ciclo.

  • Todos los participantes deben haber sido snapshoteados en el snapshot final.

• Efecto:

  • Agrega los totales del snapshot final a los totales del ciclo.

  • Marca los snapshots como finalizados.

  • Establece el estado de la última operación a "concluido".

  • Habilita la fase de propuesta de ratio.

advance-to-next-cycle

Avanza el contrato al siguiente ciclo después de que todas las recompensas sean distribuidas. Sin permisos.

• Parámetros: stx-block-height (uint)

• Afirmaciones:

  • El contrato debe estar activo.

  • La altura de bloque actual de Bitcoin debe haber alcanzado el siguiente ciclo.

  • Todos los participantes deben haber sido recompensados.

  • La distribución de recompensas debe estar finalizada.

  • La altura de bloque Stacks debe abarcar la siguiente altura de bloque de Bitcoin del ciclo.

• Efecto:

  • Incrementa el ID del ciclo.

  • Restablece las variables de estado para el nuevo ciclo.

  • Actualiza la configuración del ciclo desde los ajustes de next-cycle.

  • Inicializa el primer snapshot del nuevo ciclo.

---

5. Cálculo y Validación de Ratio

propose-golden-ratio

Propone una ratio dorada para el ciclo actual. Sin permisos.

• Parámetros: ratio (uint) — ratio propuesta escalada por 10^8

• Afirmaciones:

  • Los snapshots deben estar finalizados.

  • No debe haber ya una ratio validada para este ciclo.

  • El llamante no debe haber propuesto ya una ratio para este ciclo.

• Efecto:

  • Registra la ratio propuesta para el llamante.

  • Inicializa el seguimiento para la contabilización de participantes.

  • Establece el estado de la última operación a "proposed-ratio".

change-proposed-golden-ratio

Cambiar una ratio dorada propuesta anteriormente antes de la validación.

• Parámetros: ratio (uint)

• Afirmaciones:

  • El llamante debe haber propuesto ya una ratio.

  • La ratio aún no debe estar validada.

• Efecto:

  • Actualiza la ratio propuesta y restablece los datos de contabilización.

tally-participant-ratios

Cuenta cuántos participantes tienen ratios por encima, por debajo o iguales a la ratio dorada propuesta.

• Parámetros: principals (lista de hasta 900 principals)

• Afirmaciones:

  • El llamante debe haber propuesto una ratio.

  • La ratio aún no debe estar validada.

  • No debe haber ya contabilizado a todos los participantes.

• Efecto:

  • Calcula la ratio STX/sBTC de cada participante.

  • Rastrea las cantidades de sBTC por encima, por debajo e iguales a la ratio propuesta.

  • Incrementa el conteo de participantes contabilizados.

validate-ratio

Valida que la ratio propuesta representa el percentil 95 de las ratios de los participantes.

• Afirmaciones:

  • El llamante debe haber propuesto una ratio.

  • Todos los participantes deben haber sido contabilizados.

  • La ratio no debe estar ya validada.

  • Si nadie ha hecho stacking de STX, la ratio debe ser igual a 1.0 (línea base).

  • El sBTC por encima de la ratio debe ser ≤ 5% del sBTC total.

  • El sBTC en o por encima de la ratio debe ser ≥ 5% del sBTC total.

• Efecto:

  • Marca la ratio como validada.

  • Registra la ratio validada para el ciclo.

  • Establece el estado de la última operación a "ratio-validated".

set-max-percentage-above-ratio

Actualiza el umbral porcentual para la validación (solo administrador).

• Parámetros: new-max-percentage-above-ratio (uint) — por defecto 500 = 5%

• Afirmaciones:

  • El llamante debe ser el administrador.

• Efecto:

  • Actualiza el umbral de validación.

---

6. Cómputo de Pesos

calculate-participant-weights

Calcula los pesos de los participantes usando la fórmula de doble stacking. Sin permisos.

• Parámetros: principals (lista de hasta 900 principals)

• Afirmaciones:

  • La ratio debe estar validada.

  • La altura de bloque Stacks del ciclo actual debe estar disponible.

• Efecto:

  • Recupera la ratio dorada validada D.

  • Aplica un umbral mínimo a D para prevenir la división por cero $D = max(D, 10^-8)$.

  • Para cada participante, calcula el peso usando: $w_i = \cfrac{[B_i \cdot (1 + M \cdot √r_i)]}{n}$

  • Acumula los pesos totales en total-weights-sum.

  • Registra los pesos individuales por dirección de tracking (no por dirección inscrita).

Notas:

• Múltiples direcciones inscritas que compartan la misma dirección de tracking compartirán el mismo peso.

• Puede llamarse en lotes de hasta 900 participantes.

finalize-weight-computation

Finaliza la fase de cómputo de pesos. Sin permisos.

• Afirmaciones:

  • La ratio debe estar validada.

  • Los pesos no deben estar ya finalizados.

  • Todos los participantes deben tener pesos calculados.

• Efecto:

  • Marca los pesos como calculados.

  • Establece el estado de la última operación a "weights-finalized".

  • Habilita la fase de distribución de recompensas.

---

7. Distribución de Recompensas

set-is-distribution-enabled

Prepara el contrato para distribuir recompensas determinando el pool de recompensas disponible. Sin permisos.

• Afirmaciones:

  • El contrato debe estar activo.

  • La distribución no debe estar ya habilitada.

  • Los pesos deben estar calculados.

• Efecto:

  • Lee el saldo sBTC del contrato.

  • Calcula las recompensas a distribuir: min(saldo del pool, tope basado en APR).

  • El tope es: $(CPR × total-weights-sum) / (M + 1)$

  • Marca las recompensas como listas para distribución.

  • Establece el estado de la última operación a "set-can-distribute".

distribute-rewards

Distribuye recompensas a los participantes basadas en sus pesos calculados. Sin permisos.

• Parámetros: principals (lista de hasta 900 principals)

• Afirmaciones:

  • La distribución debe estar habilitada.

• Efecto:

  • Calcula la recompensa para cada participante: (peso / total-pesos) × recompensas-totales

  • Transfiere recompensas sBTC a las direcciones de recompensa.

  • Marca a los participantes como recompensados.

  • Agrega recompensas por dirección recompensada.

Notas:

• Puede llamarse en lotes de hasta 900 participantes.

• Múltiples direcciones inscritas que compartan la misma dirección recompensada agregan las recompensas y solo disparan una transferencia por dirección de tracking.

finalize-reward-distribution

Marca la distribución de recompensas como finalizada para el ciclo actual. Sin permisos.

• Afirmaciones:

  • El contrato debe estar activo.

  • Todos los participantes deben haber sido recompensados.

  • La distribución debe estar habilitada.

  • No debe estar ya finalizada.

• Efecto:

  • Registra la altura de bloque de finalización.

  • Establece el estado de la última operación a "finalized".

  • Habilita el avance de ciclo.

  • Dispara a los protocolos DeFi externos para que distribuyan sus recompensas internas (ellos monitorean este evento de finalización).

---

8. Controles Administrativos

• update-admin

• update-min-sbtc-hold-required-for-enrollment

• update-snapshot-length

• update-snapshots-per-cycle

• update-cycle-data

• update-bitcoin-blocks-per-year

• update-APR

• update-yield-boost-multiplier

• set-liquid-stacking

• emergency-withdraw-sbtc

(Cada uno de los anteriores tiene parámetros, afirmaciones solo para administradores donde corresponda, y efectos descritos en la especificación original. Las restricciones notables incluyen límites de APR y límites del multiplicador.)

---

9. Gestión de Lista Negra

• add-blacklisted

• add-blacklisted-batch

• remove-blacklisted

• remove-blacklisted-batch

(Operaciones solo para administradores para gestionar la lista negra; agregar una dirección inscrita la da de baja automáticamente.)

---

10. Gestión de Whitelist DeFi

whitelist-defi-tracking

Añade una dirección de tracking DeFi a la whitelist (otorga el impulso máximo de peso automáticamente).

• Parámetros: defi-rewards-contract (principal)

• Afirmaciones:

  • El llamante debe ser el administrador.

  • La dirección no debe estar ya en la whitelist.

• Efecto:

  • Añade la dirección de tracking a la whitelist.

  • Las direcciones en la whitelist reciben el impulso máximo (r_i = 1.0) en los cálculos de peso.

  • Durante los snapshots, a las direcciones en la whitelist se les registra su STX en stacking como 0 (no necesitan hacer stacking de STX para recibir el impulso máximo).

remove-whitelisted-defi-tracking

Elimina una dirección de tracking DeFi de la whitelist (solo administrador).

• Parámetros: defi-rewards-contract (principal)

• Afirmaciones:

  • El llamante debe ser el administrador.

  • La dirección debe estar en la whitelist.

• Efecto:

  • Elimina la dirección de tracking de la whitelist.

remove-whitelisted-defi-tracking-batch

Elimina por lotes direcciones de tracking DeFi de la whitelist (solo administrador).

• Parámetros: defi-rewards-contract (lista 200 principal)

• Afirmaciones:

  • El llamante debe ser el administrador.

• Efecto:

  • Elimina múltiples direcciones de tracking de la whitelist.

---

Funciones Privadas

• update-snapshot-for-new-cycle: Restablece contadores de snapshot y establece las alturas de bloque iniciales del snapshot.

• reset-state-for-cycle: Aplica la configuración de next-cycle, restablece banderas y totales, registra los datos del ciclo, actualiza el conteo de participantes.

• capture-participant-balances: Lee sBTC y STX en stacking en la altura de snapshot, actualiza tenencias y agrega totales.

• calculate-participant-weight: Calcula el peso por dirección de tracking usando la fórmula de doble stacking (detalles de aritmética entera en la especificación original).

• tally-user-ratio: Clasifica la ratio de un usuario en relación con una ratio propuesta y acumula totales de sBTC.

• distribute-reward-user: Transfiere la recompensa por dirección de tracking y actualiza el estado de recompensado.

• remove-participant: Elimina al participante y decrementa conteos.

• enroll-defi-one / change-addresses-defi-one: auxiliares para operaciones por lotes.

• is-blacklisted: comprueba la pertenencia a la lista negra.

(Las funciones privadas implementan los efectos descritos y consideraciones de escalado entero; consulte los detalles de las funciones arriba para el comportamiento matemático/escalado.)

---

Funciones de Solo Lectura

Información del Ciclo

• get-current-cycle-id

• cycle-data

• get-cycle-current-state

• current-overview-data

• get-yield-cycle-data

• nr-cycles-year

• cycle-percentage-rate

Información de Snapshot

• snapshot-data

• get-stacks-block-height-for-cycle-snapshot

• get-bitcoin-block-height-for-cycle-snapshot

Información de Recompensas

• get-reward-distribution-status

• is-distribution-ready

• reward-amount-for-cycle-and-address

• reward-amount-for-cycle-and-reward-address

• is-distribution-finalized-for-current-cycle

• get-distribution-finalized-at-height

Información de Ratio y Pesos

• get-ratio-data

• get-weight-computation-status

• get-participant-weight

Información del Participante

• is-enrolled-in-next-cycle

• is-enrolled-this-cycle

• get-is-blacklisted

• get-is-blacklisted-list

• get-is-whitelisted-defi

• get-latest-reward-address

• get-participant-cycle-info

Estado y Configuración

• get-last-operation-state

• get-admin

• get-is-contract-active

• get-current-bitcoin-block-height

• get-minimum-enrollment-amount

• get-next-action-bitcoin-height

• get-contract-sbtc-balance

• get-apr-data

Consultas de STX Stacking

• get-amount-stx-stacked

• get-amount-stx-stacked-at-block-height

• get-amount-stacked-at-block-height

• get-amount-stacked-now