Struct Address

pub struct Address { /* private fields */ }

A high-level address representation with metadata in a Zcash wallet.

Address serves as the primary container for all Zcash addresses, wrapping the protocol-specific address details with additional wallet-level metadata such as a user-assigned name, purpose descriptor, and arbitrary attachments. This structure bridges the raw cryptographic address formats with the user-facing wallet experience.

Zcash Concept Relation

In Zcash wallets, users typically assign labels or metadata to their addresses for easier identification. Address preserves these user-defined attributes alongside the underlying cryptographic address details. It supports all Zcash address protocols:

• Transparent addresses: Bitcoin-compatible addresses (t-prefixed)
• Sapling addresses: Shielded Sapling protocol addresses (z-prefixed)
• Unified addresses: Multi-protocol addresses (u-prefixed)

Data Preservation

During wallet migration, the following components are preserved:

• Address Data: The complete protocol-specific address details
• User Labels: Custom names assigned to addresses by users
• Purpose Strings: Descriptions of the address’s intended use
• Attachments: Any additional metadata associated with the address

Examples

// Create a transparent address
let t_addr = transparent::Address::new("t1exampleaddress");
let protocol_addr = ProtocolAddress::Transparent(t_addr);

// Wrap it in an Address with metadata
let mut address = Address::new(protocol_addr);
address.set_name("Donation Address".to_string());
address.set_purpose("Receiving public donations".to_string());

// Access the address string
assert!(address.as_string().starts_with("t1"));
assert_eq!(address.name(), "Donation Address");

Implementations

impl Address

pub fn new(address: ProtocolAddress) -> Self

Creates a new Address with the specified protocol address.

This constructor creates an Address with default empty metadata (blank name, no purpose) and the provided protocol-specific address.

Arguments

• address - The protocol-specific address implementation

Examples

let t_addr = transparent::Address::new("t1example");
let protocol_addr = ProtocolAddress::Transparent(t_addr);
let address = Address::new(protocol_addr);

pub fn name(&self) -> &str

Returns the user-assigned name for this address.

Returns

The name string assigned to this address, or an empty string if no name has been set.

Examples

let t_addr = transparent::Address::new("t1example");
let protocol_addr = ProtocolAddress::Transparent(t_addr);
let mut address = Address::new(protocol_addr);

address.set_name("Personal Savings".to_string());
assert_eq!(address.name(), "Personal Savings");

pub fn purpose(&self) -> Option<&str>

Returns the purpose descriptor for this address, if available.

Returns

Some(&str) containing the purpose string if set, or None if no purpose was assigned.

Examples

let mut address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1example")
));

// Initially there is no purpose
assert!(address.purpose().is_none());

// Set a purpose and verify it was stored
address.set_purpose("Business expenses".to_string());
assert_eq!(address.purpose(), Some("Business expenses"));

pub fn set_purpose(&mut self, purpose: String)

Sets the purpose descriptor for this address.

Arguments

• purpose - A string describing the intended use of this address

Examples

let mut address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1example")
));

address.set_purpose("Donations".to_string());

pub fn as_string(&self) -> String

Returns the address as a string in its canonical format.

Returns

A string representation of the address.

Examples

let address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1exampleaddress")
));

let addr_string = address.as_string();
assert_eq!(addr_string, "t1exampleaddress");

pub fn address(&self) -> &ProtocolAddress

Returns a reference to the protocol-specific address.

Returns

A reference to the ProtocolAddress contained within this address.

Examples

let t_addr = transparent::Address::new("t1example");
let protocol_addr = ProtocolAddress::Transparent(t_addr);
let address = Address::new(protocol_addr);

let protocol = address.address();
assert!(matches!(protocol, ProtocolAddress::Transparent(_)));

pub fn address_mut(&mut self) -> &mut ProtocolAddress

Returns a mutable reference to the protocol-specific address.

Returns

A mutable reference to the ProtocolAddress contained within this address.

Examples

let mut address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1example")
));

// Swap the address out for a Sapling address
if let ProtocolAddress::Transparent(_) = address.address() {
    *address.address_mut() = ProtocolAddress::Sapling(
        Box::new(sapling::Address::new("zs1example".to_string()))
    );
}

assert!(matches!(address.address(), ProtocolAddress::Sapling(_)));

pub fn set_name(&mut self, name: String)

Sets the name for this address.

Arguments

• name - The user-defined name or label to assign to this address

Examples

let mut address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1example")
));

address.set_name("Cold Storage".to_string());
assert_eq!(address.name(), "Cold Storage");

pub fn set_address(&mut self, address: ProtocolAddress)

Replaces the protocol-specific address.

Arguments

• address - The new protocol address to store

Examples

let mut address = Address::new(ProtocolAddress::Transparent(
    transparent::Address::new("t1old")
));

// Replace with a new address
let new_addr = transparent::Address::new("t1new");
address.set_address(ProtocolAddress::Transparent(new_addr));

assert_eq!(address.as_string(), "t1new");

Trait Implementations

impl Attachable for Address

fn attachments(&self) -> &Attachments

Returns a reference to the attachments container.

fn attachments_mut(&mut self) -> &mut Attachments

Returns a mutable reference to the attachments container.

fn add_attachment( &mut self, payload: impl EnvelopeEncodable, vendor: &str, conforms_to: Option<&str>, )

Adds a new attachment with the specified payload and metadata.

fn get_attachment(&self, digest: &Digest) -> Option<&Envelope>

Retrieves an attachment by its digest.

fn remove_attachment(&mut self, digest: &Digest) -> Option<Envelope>

Removes an attachment by its digest.

fn clear_attachments(&mut self)

Removes all attachments from the object.

fn has_attachments(&self) -> bool

Returns whether the object has any attachments.

impl Clone for Address

fn clone(&self) -> Address

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Address

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Address> for Envelope

fn from(value: Address) -> Self

Converts to this type from the input type.

impl Indexed for Address

fn index(&self) -> usize

fn set_index(&mut self, index: usize)

impl PartialEq for Address

fn eq(&self, other: &Address) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<Envelope> for Address

type Error = Error

The type returned in the event of a conversion error.

fn try_from(envelope: Envelope) -> Result<Self, Self::Error>

Performs the conversion.

impl StructuralPartialEq for Address