Identity Associations

pub struct AssociationState {
    pub(crate) inbox_id: String,
    pub(crate) members: HashMap<MemberIdentifier, Member>,
    pub(crate) recovery_identifier: Identifier,
    pub(crate) seen_signatures: HashSet<Vec<u8>>,
}

impl AssociationState {
    /// Get inbox ID
    pub fn inbox_id(&self) -> InboxIdRef<'_>;

    /// Get the recovery identifier (primary wallet)
    pub fn recovery_identifier(&self) -> &Identifier;

    /// Get all members, sorted by timestamp
    pub fn members(&self) -> Vec<Member>;

    /// Get a specific member
    pub fn get(&self, identifier: &MemberIdentifier) -> Option<&Member>;

    /// Get members by kind (Installation, Ethereum, Passkey)
    pub fn members_by_kind(&self, kind: MemberKind) -> Vec<Member>;

    /// Get members added by a specific parent
    pub fn members_by_parent(&self, parent_id: &MemberIdentifier) -> Vec<Member>;

    /// Get all wallet identifiers (excludes installations)
    pub fn identifiers(&self) -> Vec<Identifier>;

    /// Get all installation IDs
    pub fn installation_ids(&self) -> Vec<Vec<u8>>;

    /// Get installations with metadata
    pub fn installations(&self) -> Vec<Installation>;
}

let state = AssociationState::new(
    account_identifier,
    nonce,
    chain_id,  // Optional, for SCW
)?;

use xmtp_id::associations::get_state;

let updates: Vec<IdentityUpdate> = /* ... */;
let state = get_state(updates)?;

pub enum MemberIdentifier {
    Installation(Installation),  // Ed25519 public key
    Ethereum(Ethereum),          // Ethereum address
    Passkey(Passkey),           // WebAuthn public key
}

// Installation
let installation = MemberIdentifier::installation(public_key_bytes);

// Ethereum wallet
let wallet = MemberIdentifier::eth("0x1234...")?;

// Passkey
let passkey = MemberIdentifier::Passkey(Passkey {
    key: public_key_bytes,
    relying_party: Some("example.com".to_string()),
});

// Check member kind
let kind = member_identifier.kind();

// Extract specific types
if let Some(key) = member_identifier.installation_key() {
    println!("Installation: {:?}", key);
}

if let Some(addr) = member_identifier.eth_address() {
    println!("Ethereum: {}", addr);
}

pub struct Member {
    pub identifier: MemberIdentifier,
    pub added_by_entity: Option<MemberIdentifier>,
    pub client_timestamp_ns: Option<u64>,
    pub added_on_chain_id: Option<u64>,
}

impl Member {
    pub fn new(
        identifier: MemberIdentifier,
        added_by_entity: Option<MemberIdentifier>,
        client_timestamp_ns: Option<u64>,
        added_on_chain_id: Option<u64>,
    ) -> Self;

    pub fn kind(&self) -> MemberKind;
}

Recovery Wallet (0x1234...)
├── Installation A (added by 0x1234...)
├── Installation B (added by 0x1234...)
└── Secondary Wallet (0x5678...)
    ├── Installation C (added by 0x5678...)
    └── Installation D (added by 0x5678...)

// Get children of a member
let children = state.members_by_parent(&parent_identifier);

// Check who added a member
if let Some(added_by) = member.added_by_entity {
    println!("Added by: {:?}", added_by);
}

pub struct SignatureRequestBuilder {
    inbox_id: String,
    client_timestamp_ns: u64,
    actions: Vec<PendingIdentityAction>,
}

let signature_request = SignatureRequestBuilder::new(inbox_id)
    .create_inbox(signer_identity, nonce)
    .build();

// Add wallet signature
signature_request.add_signature(wallet_signature, scw_verifier).await?;

// Build and publish
let identity_update = signature_request.build_identity_update()?;
api_client.publish_identity_update(identity_update).await?;

let signature_request = SignatureRequestBuilder::new(inbox_id)
    .add_association(
        new_member_identifier,
        existing_member_identifier,
    )
    .build();

// Both members must sign
signature_request.add_signature(existing_member_sig, scw_verifier).await?;
signature_request.add_signature(new_member_sig, scw_verifier).await?;

let signature_request = SignatureRequestBuilder::new(inbox_id)
    .revoke_association(
        recovery_address_signer,
        revoked_member,
    )
    .build();

// Only recovery address needs to sign
signature_request.add_signature(recovery_signature, scw_verifier).await?;

let signature_request = SignatureRequestBuilder::new(inbox_id)
    .change_recovery_address(
        recovery_address_signer,
        new_recovery_identifier,
    )
    .build();

// Current recovery address must sign
signature_request.add_signature(recovery_signature, scw_verifier).await?;

let signature_request = SignatureRequestBuilder::new(inbox_id)
    .create_inbox(wallet_ident, 0)
    .add_association(
        MemberIdentifier::installation(installation_key),
        wallet_ident.into(),
    )
    .build();

// All required signatures must be added

pub struct SignatureRequest {
    pending_actions: Vec<PendingIdentityAction>,
    signature_text: String,
    signatures: HashMap<MemberIdentifier, UnverifiedSignature>,
    client_timestamp_ns: u64,
    inbox_id: String,
}

impl SignatureRequest {
    /// Get list of missing signatures
    pub fn missing_signatures(&self) -> Vec<&MemberIdentifier>;

    /// Get missing address signatures (excludes installations)
    pub fn missing_address_signatures(&self) -> Vec<&MemberIdentifier>;

    /// Add a signature
    pub async fn add_signature(
        &mut self,
        signature: UnverifiedSignature,
        scw_verifier: impl SmartContractSignatureVerifier,
    ) -> Result<(), SignatureRequestError>;

    /// Add smart contract signature with automatic block number
    pub async fn add_new_unverified_smart_contract_signature(
        &mut self,
        signature: NewUnverifiedSmartContractWalletSignature,
        scw_verifier: impl SmartContractSignatureVerifier,
    ) -> Result<(), SignatureRequestError>;

    /// Check if all signatures are collected
    pub fn is_ready(&self) -> bool;

    /// Get the text that should be signed
    pub fn signature_text(&self) -> String;

    /// Build the final identity update
    pub fn build_identity_update(self) -> Result<UnverifiedIdentityUpdate, SignatureRequestError>;

    /// Get the inbox ID
    pub fn inbox_id(&self) -> crate::InboxIdRef<'_>;
}

// 1. Build request
let mut signature_request = SignatureRequestBuilder::new(inbox_id)
    .add_association(new_member, existing_member)
    .build();

// 2. Get signature text
let text = signature_request.signature_text();

// 3. Sign with wallet (external to LibXMTP)
let wallet_sig = wallet.sign_message(text.as_bytes()).await?;

// 4. Add signature to request
signature_request.add_signature(
    UnverifiedSignature::RecoverableEcdsa(
        UnverifiedRecoverableEcdsaSignature::new(wallet_sig.into())
    ),
    scw_verifier,
).await?;

// 5. Check if ready
if signature_request.is_ready() {
    // 6. Build and publish
    let identity_update = signature_request.build_identity_update()?;
    api_client.publish_identity_update(identity_update).await?;
}

pub struct CreateInbox {
    pub nonce: u64,
    pub account_identifier: Identifier,
    pub initial_identifier_signature: VerifiedSignature,
}

pub struct AddAssociation {
    pub new_member_signature: VerifiedSignature,
    pub new_member_identifier: MemberIdentifier,
    pub existing_member_signature: VerifiedSignature,
}

pub struct RevokeAssociation {
    pub recovery_identifier_signature: VerifiedSignature,
    pub revoked_member: MemberIdentifier,
}

pub struct ChangeRecoveryIdentity {
    pub recovery_identifier_signature: VerifiedSignature,
    pub new_recovery_identifier: Identifier,
}

use xmtp_id::associations::{apply_update, get_state};

// Apply single update
let new_state = apply_update(initial_state, update)?;

// Apply multiple updates
let updates: Vec<IdentityUpdate> = /* ... */;
let final_state = get_state(updates)?;

pub struct IdentityUpdate {
    pub inbox_id: String,
    pub client_timestamp_ns: u64,
    pub actions: Vec<Action>,
}

pub enum Action {
    CreateInbox(CreateInbox),
    AddAssociation(AddAssociation),
    RevokeAssociation(RevokeAssociation),
    ChangeRecoveryIdentity(ChangeRecoveryIdentity),
}

pub struct AssociationStateDiff {
    pub new_members: Vec<MemberIdentifier>,
    pub removed_members: Vec<MemberIdentifier>,
}

impl AssociationStateDiff {
    /// Get newly added installation IDs
    pub fn new_installations(&self) -> Vec<Vec<u8>>;

    /// Get removed installation IDs
    pub fn removed_installations(&self) -> Vec<Vec<u8>>;
}

let old_state = /* ... */;
let new_state = /* ... */;

// Compute diff
let diff = old_state.diff(&new_state);

for member in diff.new_members {
    println!("Added: {:?}", member);
}

for member in diff.removed_members {
    println!("Removed: {:?}", member);
}

// Get just installations
let added_installations = diff.new_installations();
let removed_installations = diff.removed_installations();

// Get all members as a diff (useful for initial state)
let diff = state.as_diff();
// new_members contains all current members
// removed_members is empty

impl AssociationState {
    /// Check if signature has been seen
    pub fn has_seen(&self, signature: &Vec<u8>) -> bool;

    /// Add signatures to seen set
    pub fn add_seen_signatures(&self, signatures: Vec<Vec<u8>>) -> Self;
}

let signature = VerifiedSignature::new(
    signer,
    SignatureKind::Erc1271,
    signature_bytes,
    Some(chain_id),  // Chain ID required for SCW
);

let mut signature = NewUnverifiedSmartContractWalletSignature {
    account_id: wallet_address,
    signature_bytes,
    block_number: None,  // Will be auto-filled
};

signature_request
    .add_new_unverified_smart_contract_signature(
        signature,
        scw_verifier,
    )
    .await?;

pub enum AssociationError {
    /// Multiple CreateInbox actions
    MultipleCreate,
    
    /// XID not yet created
    NotCreated,
    
    /// Signature validation failed
    Signature(SignatureError),
    
    /// Member type not allowed to add another type
    MemberNotAllowed(MemberKind, MemberKind),
    
    /// Signer not in current state
    MissingExistingMember,
    
    /// New member signature doesn't match identifier
    NewMemberIdSignatureMismatch,
    
    /// Signature already used
    Replay,
    
    /// Smart contract chain ID mismatch
    ChainIdMismatch(u64, u64),
    
    // ... other variants
}