El Address es un tipo opaco que representa ya sea una cuenta de propiedad externa 'por defecto' en la red Stellar, o un contrato (que también puede proporcionar lógica para cuentas externas personalizadas, consulta los documentos de autorización para más detalles). Para los contratos inteligentes normalmente no importa qué tipo de Address se utilice. Sin embargo, en algunos contextos es útil convertir Address a/de diferentes tipos de datos, como cadena o XDR. Las conversiones tienen propósitos claramente diferentes dependiendo de si ocurren en el propio contrato inteligente o en el código cliente.

Conversiones de cadena

El formato de cadena por defecto para Address es el llamado 'string key' (o 'strkey'), definido completamente en SEP-23. Para las cuentas externas por defecto, strkey siempre empieza con G y para todos los contratos empieza con C.

Conversiones en SDKs cliente

Fuera de los contratos inteligentes, es conveniente representar Address como cadena la mayor parte del tiempo. Puede almacenarse en formatos de serialización de cadena como JSON y XML. Almacenar direcciones como cadenas en bases de datos puede simplificar el diseño de esquemas de bases de datos y consultas. Las cadenas son más fáciles de manipular y son más compatibles con interfaces de usuario y APIs. Por lo tanto

JavaScript

const StellarSdk = require("@stellar/stellar-sdk");

// Example Stellar address
const stellarAddress =
  "GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN";
// Create an Address object from string
const address = new StellarSdk.Address(stellarAddress);
// Convert the address back to string
const addressToString = address.toString();

Conversiones en contratos inteligentes

Generalmente se prefiere que los contratos operen directamente sobre el tipo Address. Las conversiones de cadena pueden ser útiles para casos de uso especializados, como pasar las direcciones Stellar Address a/de otras cadenas.

Rust

use soroban_sdk::{Address, String, Env};

pub fn address_to_string(address: Address) -> String {
    address.to_string()
}

pub fn address_from_string(strkey: &String) -> Address {
    Address::from_string(strkey)
}

Address también puede crearse a partir de un literal de cadena, lo que puede ser útil para pruebas.

Rust

let test_address = Address::from_str(
    &env,
    "GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN",
);

Conversiones XDR

XDR es un formato de serialización binaria basado en esquema utilizado por la red Stellar. Se utiliza para todas las interacciones con la blockchain Stellar, como crear las transacciones, almacenar datos en el ledger, comunicar los resultados de las transacciones, etc. Los SDK Stellar proporcionan envoltorios tipados para todos los tipos de datos XDR de Stellar. Address se representa como tipo ScAddress, que puede envolverse dentro de ScVal, un tipo que representa cualquier tipo de contrato admitido por los contratos Stellar.

Conversiones en SDKs cliente

En el lado cliente, las conversiones XDR son útiles para crear las transacciones y procesar los resultados de las transacciones.

JavaScript

// Example Stellar address
const stellarAddress =
  "GCM5WPR4DDR24FSAX5LIEM4J7AI3KOWJYANSXEPKYXCSZOTAYXE75AFN";
// Create an Address object from string
const address = new StellarSdk.Address(stellarAddress);
// Convert the Address to xdr.ScVal
const scVal = address.toScVal();
// Convert scVal structure to the binary format
const scValBuffer = scVal.toXDR("raw");
// Convert the Address to xdr.ScAddress
const scAddress = address.toScAddress();

Python

from stellar_sdk.address import Address

# Example Stellar address
stellar_address = 'GBJCHUKZMTFSLOMNC7P4TS4VJJBTCYL3XKSOLXAUJSD56C4LHND5TWUC'
# Create an Address object
address = Address(stellar_address)
# Convert the Address object to an ScAddress
sc_address_xdr = address.to_xdr_sc_address()

Conversiones en contratos inteligentes

Los contratos inteligentes no necesitan interactuar explícitamente con los tipos XDR, ya que todos los tipos de datos de contratos inteligentes se convierten automáticamente a XDR por el entorno de ejecución del contrato. Cada tipo de contrato, incluyendo Address, puede serializarse a bytes XDR. Esta conversión es útil, por ejemplo, para realizar hashing en los contratos inteligentes. También es posible convertir los bytes XDR serializados de nuevo a tipos de contrato, lo que puede ser útil en casos de uso específicos, como esquemas de autenticación personalizados.

Nota, que las conversiones XDR son una característica avanzada y no son necesarias para la mayoría de los contratos inteligentes Stellar.

Rust

use soroban_sdk::{
    xdr::{FromXdr, ToXdr},
    Address, Bytes, Env,
};

pub fn address_to_xdr_bytes(env: &Env, address: Address) -> Bytes {
    address.to_xdr(env)
}

pub fn address_from_xdr_bytes(env: &Env, bytes: &Bytes) -> Address {
    Address::from_xdr(env, bytes).unwrap()
}