The Address is an opaque type that represents either a 'default' externally owned account on the Stellar network, or a contract (that may also provide logic for custom externally owned accounts, see authorization docs for details). For the smart contracts it normally doesn't matter which kind of Address is used. However, in some contexts it's useful to convert Address to/from different data types, such as string or XDR. The conversions have distinctly different purpose depending on whether they happen in the smart contract itself, or in the client code.

String conversions

The default string format for Address is a so called 'string key' (or 'strkey'), defined fully in SEP-23. For the default externally owned accounts strkey always starts with G and for all the contracts it starts with C.

Conversions in Client SDKs

Outside of the smart contracts, it is convenient to represent Address as string most of the time. It can be stored in string serialization formats such as JSON and XML. Storing addresses as strings in databases can simplify database schema design and queries. Strings are easier to manipulate and are more compatible with user interfaces and APIs. Thus

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();

Conversions in Smart Contracts

It's generally preferred for contracts to operate directly on the Address type. String conversions may be useful for specialized use cases, such as passing the Stellar Addresses to/from other chains.

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 can also be built from a string literal, which may be useful for testing.

Rust

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

XDR conversions

XDR is schema-based binary serialization format used by the Stellar network. It is used for all the Stellar blockchain interactions, such as building the transactions, storing data in the ledger, communicating the transaction results etc. Stellar SDKs provide the typed wrappers for all the Stellar XDR data types. Address is represented as ScAddress type, which can then be wrapped into ScVal which is a type that represents any contract type supported by Stellar contracts.

Conversions in Client SDKs

On the client side XDR conversions are useful to build the transactions and process the transaction results.

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()

Conversions in Smart Contracts

Smart contracts don't need to explicitly interact with the XDR types, as all the smart contract data types are automatically converted to XDR by the smart contract runtime. Every contract type, including Address, can be serialized to XDR bytes. This conversion is useful, for example, for performing hashing in smart contracts. It is also possible to convert the serialized XDR bytes back to contract types, which can be useful in some narrow use cases, such as custom authentication schemes.

Note, that XDR conversions are and advanced feature and are not necessary for most of the Stellar smart contracts.

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()
}