# Contacts SDK

An Android SDK for reading device contacts with Ethereum (ETH) address and ENS name support. Built for the [ethOS](https://ethereumphone.org/) ecosystem.

ETH addresses are stored in the `DATA15` field of Android's `ContactsContract`, and ENS names are stored in `SharedPreferences` — the same convention used by the ethOS Contacts app.

[![](https://camo.githubusercontent.com/3eb6d4131b294adfb3eb923edd888a23f898db8c3529553b9afaf0aea359cd14/68747470733a2f2f6a69747061636b2e696f2f762f457468657265756d50686f6e652f436f6e746163747353444b2e737667)](https://jitpack.io/#EthereumPhone/ContactsSDK)

### Setup

#### 1. Add JitPack repository

In your root `settings.gradle.kts`:

```
dependencyResolutionManagement {
    repositories {
        // ...
        maven { setUrl("https://jitpack.io") }
    }
}
```

#### 2. Add the dependency

In your module `build.gradle.kts`:

```
dependencies {
    implementation("com.github.EthereumPhone:ContactsSDK:0.1.0")
}
```

#### 3. Add permissions

Add to your `AndroidManifest.xml`:

```
<uses-permission android:name="android.permission.READ_CONTACTS" />
<!-- Only needed if you want to write ETH addresses to contacts -->
<uses-permission android:name="android.permission.WRITE_CONTACTS" />
```

Make sure to request these permissions at runtime on Android 6.0+.

### Usage

#### Initialize

```
val contactsSDK = ContactsSDK(context)
```

#### Get all contacts

```
val contacts = contactsSDK.getContacts()

for (contact in contacts) {
    println("${contact.displayName}: ${contact.ethAddress ?: "no ETH address"}")
}
```

#### Get contacts with ETH addresses only

```
val ethContacts = contactsSDK.getContactsWithEthAddress()
```

#### Get contacts with ENS names only

```
val ensContacts = contactsSDK.getContactsWithEns()
```

#### Get contacts with any Ethereum data (ETH address or ENS)

```
val web3Contacts = contactsSDK.getContactsWithEthData()
```

#### Get a specific contact by ID

```
val contact = contactsSDK.getContactById("123")
contact?.let {
    println("Name: ${it.displayName}")
    println("ETH: ${it.ethAddress}")
    println("ENS: ${it.ensName}")
    println("Phone: ${it.phoneNumber}")
    println("Email: ${it.email}")
}
```

#### Write an ETH address to a contact

```
contactsSDK.setEthAddress(contactId = 123L, address = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
```

#### Write an ENS name to a contact

```
contactsSDK.setEnsName(contactId = 123L, ensName = "vitalik.eth")
```

#### Add a new contact with ETH data

```
val newContactId = contactsSDK.addContact(
    displayName = "Vitalik Buterin",
    phoneNumber = "+1234567890",
    email = "vitalik@ethereum.org",
    ethAddress = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    ensName = "vitalik.eth"
)
```

### Contact Model

```
data class Contact(
    val contactId: String,
    val displayName: String,
    val phoneNumber: String?,
    val email: String?,
    val photoUri: String?,
    val ethAddress: String?,
    val ensName: String?
)
```

Helper properties:

* `contact.hasEthAddress` — `true` if the contact has a valid ETH address
* `contact.hasEns` — `true` if the contact has an ENS name

### How ETH data is stored

This SDK uses the same storage convention as the ethOS Contacts app:

| Data        | Storage Location                                                           |
| ----------- | -------------------------------------------------------------------------- |
| ETH Address | `ContactsContract.Data.DATA15` under `StructuredName` MIME type            |
| ENS Name    | `SharedPreferences` with key `"ENS_{contactId}"` in `"contact_prefs"` file |

If `DATA15` contains a valid ETH address (`0x` + 40 hex chars), it's parsed as an ETH address. Otherwise, if it contains a dot (e.g., `vitalik.eth`), it's treated as an ENS name.

### Github Repo:

{% embed url="<https://github.com/EthereumPhone/ContactsSDK>" %}