Saltar al contenido principal

Federación

El Stellar federation protocol mapea direcciones Stellar a un identificador similar a un correo electrónico que proporciona más información sobre un usuario dado. Es una manera para que el software cliente Stellar resuelva direcciones similares a correos electrónicos como nombre*tu dominio.com en IDs de cuenta como: GCCVPYFOHY7ZB7557JKENAX62LUAPLMGIWNZJAFV2MITK6T32V37KEJU. Las direcciones federadas proporcionan una manera fácil para que los usuarios compartan detalles de pago utilizando una sintaxis que interopera entre diferentes dominios y proveedores.

Direcciones federadas​

Las direcciones federadas Stellar se dividen en dos partes separadas por el carácter asterisco (*): el nombre de usuario y el dominio. Por ejemplo: jed*stellar.org:

  • jed es el nombre de usuario
  • stellar.org es el dominio

El dominio puede ser cualquier nombre de dominio válida según el RFC 1035. El nombre de usuario está limitado a UTF-8 imprimible con espacios en blanco y los siguientes caracteres excluidos: <*,>.

Nota que el símbolo @ está permitido en el nombre de usuario. Esto significa que puedes usar direcciones de correo electrónico en el nombre de usuario de una dirección federada. Por ejemplo: [email protected]*stellar.org.

Admitir federación​

Para admitir la federación, primero, crea un archivo stellar.toml y publícalo en https://TU_DOMINIO/.well-known/stellar.toml. Instrucciones completas para hacer eso se pueden encontrar en la especificación de stellar.toml (también conocida como SEP-1).

En general, querrás incluir cualquier y toda la información sobre tu integración Stellar en tu stellar.toml. Para admitir la federación específicamente, necesitas añadir una sección FEDERATION_SERVER a tu archivo stellar.toml que indique a otras personas la URL de tu endpoint de federación.

Por ejemplo: FEDERATION_SERVER="https://api.tudominio.com/federation"

Nota: tu servidor de federación debe usar el protocolo https

Una vez que hayas publicado la ubicación de tu servidor de federación, implementa un endpoint HTTP de federación que acepte una solicitud HTTP GET y emita respuestas de la forma detallada a continuación:

Para facilitar la configuración de un servidor de federación, puedes usar la implementación de referencia diseñada para ser integrada en tu infraestructura existente.

Solicitudes de federación​

Puedes usar el endpoint de federación para buscar un ID de cuenta si tienes una dirección Stellar. También puedes hacer federación inversa y buscar una dirección Stellar desde un ID de cuenta o un ID de transacción. Esto es útil para ver quién te ha enviado un pago.

Las solicitudes de federación son solicitudes HTTP GET con la siguiente forma:

?q=<string to look up>&type=<name,forward,id,txid>

Tipos admitidos:

  • Ejemplo de nombre: https://TU_SERVIDOR_DE_FEDERACION/federation?q=jed*stellar.org&type=name
  • Reenvío Utilizado para reenviar el pago a una red diferente o institución financiera diferente. Los otros parámetros de la consulta variarán dependiendo de qué tipo de institución es el destino final del pago y qué es lo que admite tu anchor de reenvío. Tu archivo stellar.toml debe especificar qué parámetros esperas en una solicitud de federación de reenvío. Si no puedes reenviar o los otros parámetros en la solicitud son incorrectos, deberías devolver un error al respecto. Ejemplo de solicitud: https://TU_SERVIDOR_DE_FEDERACION/federation?type=forward&forward_type=bank_account&swift=BOPBPHMM&acct=2382376
  • Id Not supported by all federation servers. La federación inversa devolverá el registro de federación de la dirección Stellar asociada con el ID de cuenta dado. En algunos casos, esto es ambiguo. For instance, if an anchor sends transactions on behalf of its users, the account id will be of the anchor, and the federation server won’t be able to resolve the particular user that sent the transaction. En casos como ese, puede que necesites usar txid en su lugar. Ejemplo: https://TU_SERVIDOR_DE_FEDERACION/federation?q=GD6WU64OEP5C4LRBH6NK3MHYIA2ADN6K6II6EXPNVUR3ERBXT4AN4ACD&type=id
  • Txid No admitido por todos los servidores de federación. Devolverá el registro de federación del remitente de la transacción si lo conoce el servidor. Ejemplo: https://TU_SERVIDOR_DE_FEDERACION/federation?q=c1b368c00e9852351361e07cc58c54277e7a6366580044ab152b8db9cd8ec52a&type=txid

Respuesta de federación​

El servidor de federación debe responder con un código de estado HTTP apropiado, encabezados, y una respuesta JSON.

Debes habilitar CORS en el servidor de federación para que los clientes puedan enviar solicitudes desde otros sitios. El siguiente encabezado HTTP debe ser establecido para todas las respuestas del servidor de federación.

Access-Control-Allow-Origin: *

Cuando se haya encontrado un registro, la respuesta debe devolver un código de estado http 200 OK y el siguiente cuerpo JSON:

{
  "stellar_address": <username*domain.tld>,
  "account_id": <account_id>,
  "memo_type": <"text", "id" , or "hash"> *optional*
  "memo": <memo to attach to any payment. if "hash" type then will be base64 encoded> *optional*
}

Si se necesita una redirección, el servidor de federación debe devolver un código de estado http 3xx y redirigir inmediatamente al usuario a la URL correcta utilizando el encabezado Location.

Cuando no se haya encontrado un registro, se debe devolver un código de estado http 404 Not Found. Cualquier otro código de estado http será considerado un error. El cuerpo debe contener detalles de error:

{
  "detail": "extra details provided by the federation server"
}

Buscar proveedor de federación a través de una entrada de dominio principal​

Las cuentas pueden tener un dominio principal especificado opcionalmente. Esto permite que una cuenta especifique programáticamente el proveedor de federación principal para esa cuenta.

Almacenamiento en caché​

No deberías almacenar en caché las respuestas de los servidores de federación. Algunas organizaciones pueden generar IDs aleatorios para proteger la privacidad de sus usuarios. Esos IDs pueden cambiar con el tiempo.