117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# @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
|