@loopprotocol/sdk-byoaa 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @loopprotocol/sdk-byoaa changelog
+
+## 0.1.0-alpha.0 (2026-05-05) — unreleased
+
+First alpha. Functionally complete spec-08 surface; on-chain rails are
+devnet-live but not yet on mainnet (pending Bundle 2 deploy + the mainnet
+ShoppingState bump repair).
+
+### Added
+
+- `BankReceipt`, `deriveBankTxnId`, `normalizeMerchantName`,
+  `validateReceipt` — receipt construction primitives.
+- `Network`, `LoopByoaaConfig`, `resolveConfig`, `getProgramIds`,
+  `defaultRpcUrl`, `isMainnet` — network-switchable config layer
+  (devnet ↔ mainnet via single field; sandbox fork support via
+  `shoppingProgramId` / `vaultProgramId` overrides).
+- `deriveBankAttestedReceiptPda`, `deriveAgentSessionPda` — PDA helpers
+  matching the on-chain seed patterns.
+- `instructionDiscriminator`, `encodeAttestedReceiptArgs`,
+  `encodeSubmitAttestedReceiptIxData` — hand-rolled Anchor wire encoding
+  (no IDL dep so the SDK ships independently of anchor-build cycles).
+- `AttestedReceiptSubmitter`, `EnclaveSigner`, `PolicyInputs`,
+  `SubmitResult` — end-to-end submit flow: validate → derive PDA →
+  assemble ix → fetch blockhash → enclave-sign → verify → send → confirm.
+  Failures returned as discriminated unions; submit batch with
+  bounded concurrency + rate limit + per-receipt progress callback.
+- `AttestedReceiptVerifier`, `VerifiedReceipt`, `decodeBankAttestedReceipt`,
+  `decodeRegistryPcr0Set` — fetch + decode + EnclaveImageRegistry
+  cross-check (caches the registry decode for 60s by default).
+- `scripts/devnet-smoke.ts` — end-to-end submit + verify against the live
+  devnet `loop-shopping` program. Run via `tsx` with the documented env
+  vars (PAYER_KEYPAIR, VAULT_PUBKEY, SESSION_PUBKEY, SESSION_SECRET_KEY).
+
+### Tests
+
+71 tests across 6 vitest files covering: type validation; normalization
+idempotence; hash determinism; PDA derivation across vault / txn /
+program; full Anchor codec round-trip; submitter happy path with a
+fake enclave (tweetnacl-backed) + RPC stubs; verifier decode + audit
+both pass and fail paths; RPC failure → typed error; batch
+fail-isolation + rate limiting.
+
+### Known limitations
+
+- Mainnet `SHOPPING` program id in `MAINNET_PROGRAM_IDS` is a placeholder
+  (`11111…`). When Bundle 2 deploys, edit `src/config.ts` to flip to the
+  live id.
+- The `EnclaveSigner` contract is duck-typed against the parent SDK's
+  `EnclaveClient` — both sides ship without a hard import to avoid a
+  circular package dependency.
+- `forMerchant()` fetches every program account and filters client-side
+  because `merchant_name_raw` lives at variable offset on-chain. Use
+  the off-chain `attested_receipt_index` Supabase mirror
+  (loop-site-v2 PR #27) for production-scale merchant queries.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OAR Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# @loopprotocol/sdk-byoaa
+
+**Bring Your Own Attested Agent** — TypeScript SDK for submitting bank-attested receipts to Loop Protocol from inside an attested enclave.
+
+> **Status:** alpha (`0.1.0-alpha.0`). On-chain primitives are deployed on devnet (loop-shopping `submit_attested_receipt` + `BankAttestedReceipt` PDA). Mainnet deploy gated on Bundle 2 (loop-protocol PR #27 + #28 + #29) + the mainnet ShoppingState bump repair.
+
+## What this is
+
+Loop Protocol's bank-data layer is built on the **BYOAA model**: users (or their hosted-agent provider — Anthropic Claude with Computer Use, OpenAI Operator, self-hosted Nitro Enclaves, etc.) run an agent inside an attested enclave that:
+
+1. Logs into a bank (the agent has the credentials; **Loop never touches them**).
+2. Reads transactions.
+3. Constructs a `BankReceipt` and signs it with the enclave-bound session key.
+4. Submits the receipt to the on-chain `submit_attested_receipt` instruction.
+
+This package provides the TypeScript primitives for steps 3 and 4. The enclave + bank scraping is the user's responsibility (see the reference implementation at `loop-byoaa-reference-agent`).
+
+Spec: [`docs/roadmap/08-byoaa-sdk.md`](../docs/roadmap/08-byoaa-sdk.md).
+
+## Install
+
+```bash
+npm install @loopprotocol/sdk-byoaa @loopprotocol/sdk
+# or
+pnpm add @loopprotocol/sdk-byoaa @loopprotocol/sdk
+```
+
+`@loopprotocol/sdk` is a peer-style dep — the BYOAA SDK relies on its `EnclaveClient` (from spec 07a) for vsock-relayed signing.
+
+## Quick start
+
+### Construct + validate a receipt (no on-chain interaction)
+
+```typescript
+import {
+  deriveBankTxnId,
+  normalizeMerchantName,
+  validateReceipt,
+  type BankReceipt,
+} from "@loopprotocol/sdk-byoaa";
+
+const merchantNameRaw = normalizeMerchantName(
+  "  starbucks #12345  SEATTLE WA  "
+); // → "STARBUCKS #12345 SEATTLE WA"
+
+const bankTxnId = deriveBankTxnId({
+  merchantNameRaw,
+  amountCents: 875n,
+  postedAt: 1714521600n, // 2024-05-01 00:00:00 UTC
+  accountLast4: 4242,
+});
+
+const receipt: BankReceipt = {
+  bankTxnId,
+  merchantNameRaw,
+  mcc: 5814,
+  amountCents: 875n,
+  postedAt: 1714521600n,
+  accountLast4: 4242,
+};
+
+const validation = validateReceipt(receipt);
+if (!validation.ok) {
+  throw new Error(`Bad receipt: ${validation.error}`);
+}
+```
+
+### Submit from inside an attested enclave
+
+`AttestedReceiptSubmitter` signs and submits one or more `AttestedReceipt` payloads from an enclave-bound session signer. It validates receipt bounds client-side, derives the receipt PDA, builds the `submit_attested_receipt` instruction, and sends it through the configured Solana connection.
+
+`AttestedReceiptVerifier` fetches recorded receipt PDAs and verifies the on-chain fields against the expected bank transaction id, merchant, amount, timestamp, and PCR/session metadata. It is a read/verify helper; it does not trust off-chain scraper output by itself.
+
+## Package surface
+
+| Export | Purpose |
+|---|---|
+| `BankReceipt` | In-memory shape of one bank transaction |
+| `deriveBankTxnId(input)` | Stable 32-byte sha256 over normalized fields. Re-fetches collide on the same on-chain PDA. |
+| `normalizeMerchantName(raw)` | Canonical form: trim → collapse whitespace → uppercase → strip non-ASCII |
+| `validateReceipt(receipt, nowSeconds?)` | Front-runs the on-chain handler's bounds checks; cheap, no I/O |
+| `MAX_RECEIPT_CENTS` | $100M cap (mirrors on-chain) |
+| `MAX_MERCHANT_NAME_RAW_LEN` | 64 bytes (mirrors on-chain) |
+| `MAX_RECEIPT_AGE_SECONDS` | 365 days (mirrors on-chain) |
+| `AttestedReceiptSubmitter` | Builds/signs/sends `submit_attested_receipt` transactions for enclave-bound sessions |
+| `AttestedReceiptVerifier` | Fetches and verifies recorded attested receipt PDAs against expected receipt/session fields |
+
+## What this does NOT do
+
+- **Hold bank credentials** — that's the user's enclave's job.
+- **Run the bank scraper** — that's the user's agent code.
+- **Manage the enclave attestation** — see `@loopprotocol/sdk` `EnclaveClient` (spec 07a).
+- **Pay receipt rent** — the session signer (the enclave) pays SOL fees + ~0.0018 SOL rent per receipt.
+- **Honor receipts as merchant payouts** — that's spec 08a (`merchant_claim_attested_receipt`), shipped as a separate flow.
+
+## Trust model
+
+The receipt's on-chain `pcr0` field is copied at submit time from the registered session, which was bound to the enclave's image at registration. To submit a forged receipt, an attacker would need an enclave whose PCRs match an audited image AND would be admin-approved in `EnclaveImageRegistry` — same trust assumption as the entire spec 07a system. See spec 08 § "Threat model".
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
+
+Tests are vitest, no on-chain dependency. End-to-end devnet rehearsal lives in `loop-protocol/scripts/devnet-rehearsal/test-spec08-09-flow-devnet.ts`.
+
+## License
+
+MIT