> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctrlarcz.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# The Android client

> A separate native Kotlin port, held to this repository by byte-identical parity vectors rather than by shared code.

The Android client is a separate native Kotlin application. It does not consume
`@ctrl-arcz/sdk`; it is a hand-written port of the same protocol, and its source is
not published here.

<div
  style={{
display: 'grid',
gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))',
gap: '2rem',
alignItems: 'start',
margin: '2rem 0',
}}
>
  <Frame caption="Confirming a send">
    <img src="https://mintcdn.com/ctrlarcz/pKCJPq_LT-Wjc1hI/android/send-confirm.png?fit=max&auto=format&n=pKCJPq_LT-Wjc1hI&q=85&s=b1e53bf6802934dc90cb645e08bf5c04" alt="Confirming a send on Android" width="1080" height="2400" data-path="android/send-confirm.png" />
  </Frame>

  <Frame caption="Picking a merchant">
    <img src="https://mintcdn.com/ctrlarcz/pKCJPq_LT-Wjc1hI/android/merchant-picker.png?fit=max&auto=format&n=pKCJPq_LT-Wjc1hI&q=85&s=36858deb8e460e27819889dfd0ac6a7a" alt="Picking a merchant on Android" width="1080" height="2400" data-path="android/merchant-picker.png" />
  </Frame>

  <Frame caption="A bridge transfer returned">
    <img src="https://mintcdn.com/ctrlarcz/pKCJPq_LT-Wjc1hI/android/bridge-returned.png?fit=max&auto=format&n=pKCJPq_LT-Wjc1hI&q=85&s=5a5bb82a1cb8d05f01f301e4a5c58f44" alt="A bridge transfer returned on Android" width="1080" height="2400" data-path="android/bridge-returned.png" />
  </Frame>
</div>

What is published is the file that holds it to this repository:
[`ParityVectorsTest.kt`](https://github.com/Farukest/Ctrl-ArcZ/blob/main/docs/android/ParityVectorsTest.kt),
a byte-identical copy of the test
that runs in the Android project's own suite. It contains no application code, no
keys and no endpoints. It is the whole of what the two implementations promise each
other, written as assertions rather than as a claim in a README.

## What it actually asserts

| Area | Held identical |
| - | - |
| Chain | Chain id, USDC decimals, log range, deploy blocks, and all twelve contract addresses, EIP-55 case included |
| Claim | Secret entropy, derivation from a secret, normalisation of what a user types, what is rejected, grouping, salts and commitments |
| Stealth | Scheme id, the exact signing message, key derivation, generated stealth addresses, view tags, recognition and the spending key |

The two that matter most are the least obvious. Addresses are compared with their
checksum case intact, because that is where the two sides drifted the first time.
And the stealth signing message is compared character for character, because one
character apart derives different keys from the same wallet signature, which loses
every box the other platform created.

## Why this is checkable and not just stated

The vectors are never generated on the Android side. They come from this repository,
and three things link the chain end to end:

1. `packages/sdk/scripts/gen-parity-vectors.ts` derives every vector from the SDK's
   own code. Nothing in it reaches a CSPRNG, so the output is the same on every run.
2. `packages/sdk/test/parityVectors.test.ts` fails if the committed
   `packages/sdk/parity-vectors.json` is not what the code produces right now. Change
   `claimCode.ts` or `stealth.ts` without regenerating and this repository goes red
   before anything reaches the other implementation.
3. The Android project's `app/src/test/resources/parity-vectors.json` is a copy of
   that same file. At the time this was written both were
   `md5 0c46c0edc9bb77d40f34d0663c318189`, so the assertions above ran against these
   exact values.

So the part you cannot read is pinned to the part you can. A port that drifts fails a
test rather than a payment.

## Refreshing it

On the Android side the vectors are a file copy:

```bash theme={null}
cp <monorepo>/packages/sdk/parity-vectors.json app/src/test/resources/
```

The copy of the test in this directory is refreshed the same way, from
`app/src/test/java/xyz/ctrlarcz/domain/crypto/ParityVectorsTest.kt`. It is kept
byte-identical on purpose: an edited copy would prove nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.