Contrato inteligente de stacking dual

Descripción general

El contrato de Dual Stacking permite a los participantes ganar recompensas aumentadas en sBTC manteniendo sBTC y, opcionalmente, apilando STX. Opera en ciclos con capturas periódicas (snapshots) para calcular las recompensas en función de las participaciones y la participación en el stacking.

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

El 15 de diciembre de 2025, el contrato de dual stacking se actualizó 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 participantes (saldos de sBTC, cantidades de STX apiladas) se leen directamente de la cadena de bloques — no se requieren oráculos off-chain ni fuentes de datos de confianza.

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

• 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 corresponde al primero en el bloque de Bitcoin especificado, o después de éste, en caso de que no haya bloques STX anclados a él.

2

Inscripción

Los usuarios pueden autoinscribirse para participar con direcciones de recompensa personalizadas. Los protocolos DeFi pueden ser inscritos por el administrador con direcciones personalizadas de seguimiento, stacking y 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 de sBTC de los participantes y las cantidades de STX apiladas a partir de datos on-chain según intervalos de bloques predefinidos.

4

Cómputo de la ratio

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

5

Cálculo de pesos

Cualquiera puede desencadenar cálculos de peso de los participantes usando la fórmula validada de dual stacking que proporciona hasta un booster de 10x (configurable) para quienes alcanzan o superan la ratio dorada.

6

Recompensas

Cualquiera puede desencadenar la distribución de recompensas en cada ciclo basándose en los pesos calculados. Los administradores pueden actualizar configuraciones como APR, multiplicador de aumento 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/retiran la inscripción de protocolos DeFi con configuraciones especiales de direcciones, gestionan listas blancas y negras, y pueden realizar operaciones de emergencia si es necesario.

---

Estructura del ciclo

• Cada ciclo consta de 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 de 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 recuentos de bloques apropiados).

Fórmula de Dual Stacking

Cálculo de peso:

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

Donde:

• w_i = peso para el usuario i

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

• M = multiplicador de aumento de rendimiento (por defecto 9, lo que significa un aumento 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 apilado por el usuario i (suma a través de todos los snapshots)

• D = ratio dorada (percentil 95 de la ratio STX/sBTC 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$$

Donde:

• R_i = recompensa para el usuario i

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

• Recompensas totales = min(saldo del pool, límite basado en APR)

Propiedades clave:

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

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

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

• Las direcciones de seguimiento DeFi en la lista blanca reciben automáticamente el aumento máximo sin necesitar apilar 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 Dual Stacking opera en ciclos, cada uno dividido en snapshots. El proceso garantiza 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 avanzar al siguiente snapshot.

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

2

Fase de validación de la 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 enviar múltiples propuestas; la primera válida se fija para el ciclo.

3

Fase de cálculo de pesos (Cualquiera puede ejecutar)

• calculate-participant-weights: Cualquiera puede calcular los pesos de los participantes usando la fórmula de dual 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 se hayan distribuido todas las recompensas.

Nota: Todas las operaciones leen datos directamente de la blockchain (saldos de sBTC desde el contrato del token sBTC, STX apilado desde el protocolo nativo Stacks). No se requieren fuentes de datos off-chain 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 Bitcoin configurada para iniciar el ciclo.

  • El contrato no debe estar activo.

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

• Efecto:

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

  • Registra datos del ciclo y el primer snapshot.

update-initialize-block

Actualiza la altura de bloque Bitcoin de inicialización antes de que el contrato se active.

• 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 Bitcoin 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 direcciones de tracking, stacking y rewarded ajustadas apropiadamente.

  • Incrementa el conteo de participantes para el siguiente ciclo.

enroll-defi

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

• 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 lote de múltiples protocolos DeFi (solo admin).

• 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 optar por no participar 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 admin).

• 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 lote de múltiples protocolos DeFi (solo admin).

• 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 admin cuando proceda, 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 de sBTC del contrato token sBTC para cada participante.

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

  • Actualiza totales de snapshot y participaciones de los participantes.

  • Registra las 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 capturados en snapshot.

  • 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 Bitcoin del snapshot.

• Efecto:

  • Incrementa el índice de snapshot.

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

  • Restablece contadores de snapshot.

  • Registra las nuevas alturas de bloque de 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 capturados en el snapshot final.

• Efecto:

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

  • Marca los snapshots como finalizados.

  • Establece el último estado de operación a "concluded".

  • Habilita la fase de propuesta de ratio.

advance-to-next-cycle

Avanza el contrato al siguiente ciclo después de que todas las recompensas hayan sido 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 Bitcoin del ciclo.

• Efecto:

  • Incrementa el ID del ciclo.

  • Restablece variables de estado para el nuevo ciclo.

  • Actualiza la configuración del ciclo desde los ajustes del siguiente ciclo.

  • Inicializa el primer snapshot del nuevo ciclo.

---

5. Cómputo y validación de la 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 existir 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 el conteo de participantes.

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

change-proposed-golden-ratio

Cambia una ratio dorada previamente propuesta 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 recuento.

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.

  • Registra las cantidades de sBTC por encima, por debajo y iguales a la ratio propuesta.

  • Incrementa el número 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 apilado 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 último estado de operación a "ratio-validated".

set-max-percentage-above-ratio

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

• 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 dual 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 divisiones 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 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.

• Se puede llamar 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 último estado de 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 de sBTC del contrato.

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

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

  • Marca las recompensas como listas para distribución.

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

distribute-rewards

Distribuye recompensas a los participantes según 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-weights) × recompensas totales

  • Transfiere recompensas en sBTC a las direcciones rewarded.

  • Marca a los participantes como recompensados.

  • Agrega las recompensas por dirección rewarded.

Notas:

• Se puede llamar en lotes de hasta 900 participantes.

• Múltiples direcciones inscritas que compartan la misma dirección rewarded agregan recompensas y solo desencadenan 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 último estado de operación a "finalized".

  • Habilita el avance del ciclo.

  • Desencadena a protocolos DeFi externos para distribuir sus recompensas internas (ellos supervisan 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 admin cuando proceda, 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 listas negras

• add-blacklisted

• add-blacklisted-batch

• remove-blacklisted

• remove-blacklisted-batch

(Operaciones solo admin para gestionar la lista negra; añadir una dirección inscrita la da de baja automáticamente.)

---

10. Gestión de lista blanca DeFi

whitelist-defi-tracking

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

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

• Afirmaciones:

  • El llamante debe ser el administrador.

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

• Efecto:

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

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

  • Durante los snapshots, a las direcciones en la lista blanca se les registra su STX apilado como 0 (no necesitan apilar STX para recibir el aumento máximo).

remove-whitelisted-defi-tracking

Elimina una dirección de tracking DeFi de la lista blanca (solo admin).

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

• Afirmaciones:

  • El llamante debe ser el administrador.

  • La dirección debe estar en la lista blanca.

• Efecto:

  • Elimina la dirección de tracking de la lista blanca.

remove-whitelisted-defi-tracking-batch

Elimina por lote direcciones de tracking DeFi de la lista blanca (solo admin).

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

• Afirmaciones:

  • El llamante debe ser el administrador.

• Efecto:

  • Elimina múltiples direcciones de tracking de la lista blanca.

---

Funciones privadas

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

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

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

• calculate-participant-weight: Calcula el peso por dirección de tracking usando la fórmula de dual 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 reward.

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

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

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

(Las funciones privadas implementan los efectos descritos y consideraciones de escalado entero; remítase a 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 del 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 de participantes

• 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