Albatross SDK

2026-07-23 13:41:20 +00:00
commit 1d8788dec7
6 changed files with 2048 additions and 0 deletions
@@ -0,0 +1,116 @@
+# @usealbatross/sdk
+
+Official SDK for [Albatross](https://albatrossprotocol.com), the privacy protocol on Solana.
+
+Move SOL privately with the bridge, or send SOL to anyone with a single unlinkable
+Ghost Link. No wallet connection, no signup, noncustodial.
+
+```bash
+npm install @usealbatross/sdk
+```
+
+## Quick start
+
+```ts
+import { Albatross } from '@usealbatross/sdk'
+
+const albatross = new Albatross()
+
+// 1. Create a private bridge
+const bridge = await albatross.createBridge({
+  amount: 1,                 // SOL the recipient receives (0.1, 0.5, 1 or 5)
+  destination: 'YourCleanWallet…',
+})
+
+console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)
+
+// 2. Wait until the payout lands
+const result = await albatross.waitForBridge(bridge.id, {
+  onUpdate: (s) => console.log(s.status),
+})
+
+console.log('Done:', result.payoutSignature)
+```
+
+Even shorter, with the one shot helper:
+
+```ts
+const { bridge, wait } = await albatross.bridge({ amount: 1, destination })
+console.log(`Send ${bridge.depositSol} SOL to ${bridge.depositAddress}`)
+const done = await wait()
+```
+
+## Ghost Links
+
+Send SOL to anyone with just a link. No address, no wallet connect, no onchain trail
+between sender and receiver. The claim secret lives only in the URL fragment and is
+never sent to or stored by the server.
+
+```ts
+import { Albatross } from '@usealbatross/sdk'
+
+const albatross = new Albatross()
+
+// 1. Create a Ghost Link (secret + claim URL are generated locally)
+const { link, claimUrl } = await albatross.createGhostLink({
+  amount: 0.5,                     // SOL the receiver claims (0.1, 0.5, 1 or 5)
+  refundAddress: 'YourWallet…',    // where funds return if never claimed
+  note: 'gm 👻',                    // optional, shown to the receiver
+})
+
+console.log(`Fund it: send ${link.depositSol} SOL to ${link.depositAddress}`)
+console.log(`Then share: ${claimUrl}`)   // keep this safe — it can never be recovered
+
+// 2. The receiver claims to any wallet
+await albatross.claimFromUrl(claimUrl, 'ReceiverWallet…')
+```
+
+⚠️ The `secret` and `claimUrl` are never stored server side and cannot be recovered.
+Persist or share them the moment you create the link.
+
+## How the bridge works
+
+You send SOL to the fresh `depositAddress`. Albatross detects it and pays the same
+amount to your `destination` from an unrelated wallet. The two transfers are never
+linked onchain. The fee is 0.5%, added on top of the amount. Ghost Links work the
+same way, but the payout goes to whoever claims the link.
+
+## API
+
+### `new Albatross(options?)`
+
+| Option | Type | Default |
+|---|---|---|
+| `baseUrl` | `string` | `https://backend.albatrossprotocol.com/api` |
+| `appUrl` | `string` | `https://albatrossprotocol.com` |
+| `fetch` | `typeof fetch` | global `fetch` |
+
+### Bridge methods
+
+- `createBridge({ amount, destination })` → `Bridge` — create a bridge, returns the deposit address.
+- `getBridge(id)` → `BridgeState` — fetch current status.
+- `waitForBridge(id, opts?)` → `BridgeState` — poll until terminal (`completed`, `refunded`, `failed`, `expired`).
+- `bridge({ amount, destination })` → `{ bridge, wait() }` — create and get a ready `wait()` helper.
+- `getAmounts()` → `{ amounts, feeBps }` — selectable amounts and fee.
+- `getStats()` → `{ bridges, volumeSol, fundingWallets, feeBps }` — network stats.
+
+### Ghost Link methods
+
+- `createGhostLink({ amount, refundAddress, note? })` → `{ link, secret, claimUrl }` — create a link locally hashing the secret.
+- `getGhostLink(id)` → `GhostLinkState` — fetch current status.
+- `claimGhostLink({ id, secret, destination })` → claim to a wallet.
+- `claimFromUrl(claimUrl, destination)` → parse a claim URL and claim it.
+- `waitForGhostLink(id, opts?)` → poll until terminal (`claimed`, `refunded`, `failed`, `expired`).
+- `getGhostAmounts()` → `{ amounts, feeBps, claimExpiryDays }`.
+- `buildClaimUrl(id, secret)` → build a shareable claim URL.
+- `generateClaimSecret()` (named export) → `{ secret, secretHash }` low level helper.
+
+### Statuses
+
+Bridge: `awaiting_deposit` → `paying_out` → `completed`, or `refunded` / `failed` / `expired`.
+
+Ghost Link: `awaiting_deposit` → `funded` → `claiming` → `claimed`, or `refunded` / `failed` / `expired`.
+
+## License
+
+MIT