# Registro de sBTC

## Resumen

El [contrato del Registro sBTC](https://github.com/stacks-network/sbtc/blob/main/contracts/contracts/sbtc-registry.clar) (`sbtc-registry.clar`) sirve como el registro central del sistema sBTC. Gestiona las solicitudes de retiro, los depósitos completados y el conjunto actual de firmantes. Este contrato es crucial para mantener el estado y coordinar las operaciones dentro del ecosistema sBTC.

## Constantes de error

* `ERR_UNAUTHORIZED` (u400): Indica acceso no autorizado.
* `ERR_INVALID_REQUEST_ID` (u401): Significa un ID de solicitud de retiro inválido.
* `ERR_AGG_PUBKEY_REPLAY` (u402): Indica un intento de reproducir una clave pública agregada.
* `ERR_MULTI_SIG_REPLAY` (u403): Significa un intento de reproducir una dirección multifirma.

## Variables de estado

* `last-withdrawal-request-id`: Registra el ID de la solicitud de retiro más reciente.
* `current-signature-threshold`: Almacena el umbral actual de firmas requeridas.
* `current-signer-set`: Mantiene una lista de las claves públicas de los firmantes actuales.
* `current-aggregate-pubkey`: Contiene la clave pública agregada actual.
* `current-signer-principal`: Almacena la dirección principal del firmante actual.

## Mapas de datos

### withdrawal-requests

Almacena los detalles de las solicitudes de retiro indexados por ID de solicitud.

* Campos:
  * `amount`: Cantidad de sBTC que se retira (en sats)
  * `max-fee`: Tarifa máxima para el retiro
  * `sender`: Principal del remitente
  * `recipient`: Dirección BTC del destinatario (versión y hashbytes)
  * `block-height`: Altura del bloque de quema donde se creó la solicitud

### withdrawal-status

Registra el estado de las solicitudes de retiro indexadas por ID de solicitud.

* Valor: `bool` (true si se acepta, false si se rechaza, none si está pendiente)

### completed-deposits

Registra las transacciones de depósito completadas para evitar ataques de repetición.

* Clave: `{txid: (buff 32), vout-index: uint}`
* Valor: `{amount: uint, recipient: principal}`

### aggregate-pubkeys

Registra las claves públicas agregadas utilizadas para evitar ataques de repetición.

* Clave: `(buff 33)` (clave pública agregada)
* Valor: `bool`

### multi-sig-address

Registra las direcciones multifirma utilizadas para evitar ataques de repetición.

* Clave: `principal` (dirección multifirma)
* Valor: `bool`

### protocol-contracts

Almacena las direcciones de contratos de protocolo autorizados.

* Clave: `principal` (dirección del contrato)
* Valor: `bool`

## Funciones de solo lectura

### get-withdrawal-request

Recupera una solicitud de retiro por su ID.

* Parámetros:
  * `id`: `uint`
* Devuelve: `(optional {amount: uint, max-fee: uint, sender: principal, recipient: {version: (buff 1), hashbytes: (buff 32)}, block-height: uint, status: (optional bool)})`

### get-completed-deposit

Obtiene un depósito completado por ID de transacción e índice de salida.

* Parámetros:
  * `txid`: `(buff 32)`
  * `vout-index`: `uint`
* Devuelve: `(optional {amount: uint, recipient: principal})`

### get-current-signer-data

Devuelve la información actual del conjunto de firmantes.

* Devuelve: `{current-signer-set: (list 128 (buff 33)), current-aggregate-pubkey: (buff 33), current-signer-principal: principal, current-signature-threshold: uint}`

### get-current-aggregate-pubkey

Devuelve la clave pública agregada actual.

* Devuelve: `(buff 33)`

### get-current-signer-principal

Devuelve el principal del firmante actual.

* Devuelve: `principal`

### get-current-signer-set

Devuelve el conjunto actual de claves públicas de firmantes.

* Devuelve: `(list 128 (buff 33))`

## Funciones públicas

### create-withdrawal-request

Crea una nueva solicitud de retiro. Solo puede ser llamada por contratos de protocolo.

* Parámetros:
  * `amount`: `uint`
  * `max-fee`: `uint`
  * `sender`: `principal`
  * `recipient`: `{version: (buff 1), hashbytes: (buff 32)}`
  * `height`: `uint`
* Devuelve: `(response uint uint)`

### complete-withdrawal-accept

Marca una solicitud de retiro como aceptada.

* Parámetros:
  * `request-id`: `uint`
  * `bitcoin-txid`: `(buff 32)`
  * `output-index`: `uint`
  * `signer-bitmap`: `uint`
  * `fee`: `uint`
* Devuelve: `(response bool uint)`

### complete-withdrawal-reject

Marca una solicitud de retiro como rechazada.

* Parámetros:
  * `request-id`: `uint`
  * `signer-bitmap`: `uint`
* Devuelve: `(response bool uint)`

### complete-deposit

Registra una transacción de depósito completada.

* Parámetros:
  * `txid`: `(buff 32)`
  * `vout-index`: `uint`
  * `amount`: `uint`
  * `recipient`: `principal`
* Devuelve: `(response bool uint)`

### rotate-keys

Actualiza el conjunto de firmantes, el principal multifirma y la clave pública agregada.

* Parámetros:
  * `new-keys`: `(list 128 (buff 33))`
  * `new-address`: `principal`
  * `new-aggregate-pubkey`: `(buff 33)`
  * `new-signature-threshold`: `uint`
* Devuelve: `(response (buff 33) uint)`

## Funciones privadas

### increment-last-withdrawal-request-id

Incrementa y devuelve el siguiente ID de solicitud de retiro.

* Devuelve: `uint`

### is-protocol-caller

Comprueba si el llamador es un contrato de protocolo autorizado.

* Devuelve: `(response bool uint)`

### validate-protocol-caller

Valida si un principal dado es un contrato de protocolo autorizado.

* Parámetros:
  * `caller`: `principal`
* Devuelve: `(response bool uint)`

## Eventos

El contrato emite eventos (mediante `print`) para acciones importantes:

* Creación de solicitud de retiro: "withdrawal-create"
* Aceptación de retiro: "withdrawal-accept"
* Rechazo de retiro: "withdrawal-reject"
* Finalización de depósito: "completed-deposit"

{% hint style="info" %}
Los eventos se emiten mediante `print` instrucciones en el contrato para las acciones enumeradas arriba.
{% endhint %}

## Consideraciones de seguridad

{% stepper %}
{% step %}
**Control de acceso**

Solo los contratos de protocolo autorizados pueden llamar a ciertas funciones.
{% endstep %}

{% step %}
**Prevención de repetición**

El contrato evita ataques de repetición en depósitos, claves públicas agregadas y direcciones multifirma.
{% endstep %}

{% step %}
**Gestión del estado**

El contrato administra cuidadosamente el estado de los retiros y el conjunto actual de firmantes.
{% endstep %}
{% endstepper %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stacks.co/learn/es/sbtc/clarity-contracts/sbtc-registry.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.