dxs-stas-sdk 2.0.4 → 2.0.5

package/AGENTS.md

@@ -0,0 +1,52 @@
+# AGENTS
+
+This file is a fast onboarding entrypoint for AI coding agents working on this repository.
+
+## Read order
+
+1. `/Users/imighty/Code/dxs-stas-sdk/README.md` (public API and examples)
+2. `/Users/imighty/Code/dxs-stas-sdk/docs/AGENT_RUNBOOK.md` (task-oriented execution flow)
+3. `/Users/imighty/Code/dxs-stas-sdk/docs/DSTAS_0_0_8_SDK_SPEC.md` (normative protocol rules)
+4. `/Users/imighty/Code/dxs-stas-sdk/docs/DSTAS_SCRIPT_INVARIANTS.md` (script-level invariants)
+5. `/Users/imighty/Code/dxs-stas-sdk/docs/DSTAS_CONFORMANCE_MATRIX.md` (test mapping)
+
+## Preferred implementation path
+
+- Prefer high-level DSTAS APIs first:
+  - `DstasBundleFactory` for multi-step payout/split/merge planning.
+  - `BuildDstas*` helpers for single-flow transactions.
+- Use legacy `stas*` APIs only for compatibility maintenance.
+
+## Mandatory validation rule
+
+For every protocol change or new flow, validate built tx hex with script evaluation:
+
+- Use `evaluateTransactionHex(...)` from `/Users/imighty/Code/dxs-stas-sdk/src/script/eval/script-evaluator.ts`.
+- Provide an explicit prevout resolver from known `OutPoint`/transaction fixtures.
+- Never mark a DSTAS flow complete without script-level evaluation coverage.
+
+## Testing expectations
+
+- Put deterministic fixtures under `/Users/imighty/Code/dxs-stas-sdk/tests/fixtures/`.
+- Keep debug/probe helpers under `/Users/imighty/Code/dxs-stas-sdk/tests/debug/`.
+- Do not depend on local `.temp` files in CI-facing tests.
+- Update conformance vectors when behavior intentionally changes:
+  - `/Users/imighty/Code/dxs-stas-sdk/tests/fixtures/dstas-conformance-vectors.json`
+
+## Safety and constraints
+
+- Keep strict parsing enabled by default (`strictTxParse=true`).
+- Preserve flags/service-field ordering and optional-data continuity invariants.
+- Keep multisig bounds enforced (`m <= n`, `n <= 5`) unless protocol spec changes.
+- Avoid silent behavior changes in unlock/signing semantics; cover with negative tests.
+
+## Standard local commands
+
+```bash
+npm install
+npm run build
+npm run lint
+npm test
+```
+
+For targeted runs, prefer file-scoped Jest execution over full-suite reruns while iterating.

package/README.md

@@ -12,6 +12,14 @@ All binary inputs/outputs are `Uint8Array` (no Node.js `Buffer` in the public AP
 npm install dxs-stas-sdk
 ```
 
+## AI Agent onboarding
+
+If you are integrating this SDK through an AI coding agent, start with:
+
+- `AGENTS.md` (fast onboarding and guardrails)
+- `docs/AGENT_RUNBOOK.md` (task execution workflow)
+- `docs/DSTAS_0_0_8_SDK_SPEC.md` (normative protocol behavior)
+
 ## Concepts
 
 An `OutPoint` represents a spendable UTXO: txid, vout, locking script, satoshis, and owner address.

package/docs/AGENT_RUNBOOK.md

@@ -0,0 +1,88 @@
+# Agent Runbook
+
+This runbook is the practical workflow for implementing or modifying DSTAS behavior in this SDK.
+
+## 1. Pick the right API level
+
+Use the highest-level API that satisfies the task:
+
+1. `DstasBundleFactory` (`src/dstas-bundle-factory.ts`)
+   For many recipients and automatic merge/split/service planning.
+2. `BuildDstas*` helpers (`src/dstas-factory.ts`)
+   For explicit issue/transfer/freeze/unfreeze/confiscate/swap/redeem flows.
+3. `TransactionBuilder` + script builders
+   Only when lower-level control is required.
+
+## 2. Keep protocol invariants intact
+
+Before code changes, verify expected behavior against:
+
+- `docs/DSTAS_0_0_8_SDK_SPEC.md`
+- `docs/DSTAS_SCRIPT_INVARIANTS.md`
+
+Critical invariant groups:
+
+- flags/service-field coupling and order;
+- action-data semantics (neutral/swap);
+- optional-data continuity;
+- issuer-only redeem rules;
+- freeze/confiscation layering;
+- multisig bounds (`n <= 5`, no duplicate keys).
+
+## 3. Add or update tests first-class
+
+Primary suites:
+
+- `tests/dstas-flow.test.ts` (end-to-end protocol flows + negative cases)
+- `tests/dstas-bundle-factory.test.ts` (high-level planning)
+- `tests/dstas-factory-guards.test.ts` (input guards)
+- `tests/dstas-conformance-vectors.test.ts` (vector conformance)
+
+Rules:
+
+- Use deterministic fixtures from `tests/fixtures/`.
+- Do not depend on local `.temp` files.
+- Keep debug-only probes in `tests/debug/`.
+
+## 4. Mandatory script-level validation
+
+For every flow-producing change, evaluate tx hex through script interpreter:
+
+- Use `evaluateTransactionHex` from `src/script/eval/script-evaluator.ts`.
+- Use a strict prevout resolver from known outputs.
+- Cover both positive and negative paths where applicable.
+
+Minimal expectation in tests:
+
+- `success === true` for valid flow;
+- explicit failure reason checks for invalid flow.
+
+## 5. Update docs when behavior changes
+
+When protocol behavior, API shape, or guarantees change, update:
+
+- `README.md` for user-facing API examples;
+- `docs/DSTAS_0_0_8_SDK_SPEC.md` for normative rules;
+- `docs/DSTAS_CONFORMANCE_MATRIX.md` for coverage mapping.
+
+If vectors changed intentionally, refresh fixtures and note it in PR summary.
+
+## 6. Pre-commit checks
+
+Run:
+
+```bash
+npm run build
+npm run lint
+npm test
+```
+
+If only one suite changed, run targeted tests first, then full-suite before merge.
+
+## 7. Common failure modes
+
+- Missing/mismatched prevout resolver entries during evaluation.
+- Action-data hash domain drift (`requestedScriptHash` scope regression).
+- Wrong service-field order when multiple policy bits are enabled.
+- Optional-data dropped on descendant outputs, causing merge/spend failures.
+- Treating debug artifacts as fixtures.

package/llms.txt

@@ -0,0 +1,28 @@
+# dxs-stas-sdk
+
+TypeScript SDK for building and validating Bitcoin SV transaction flows, including Divisible STAS (DSTAS) issue, transfer, split, merge, freeze/unfreeze, confiscation, swap, and redeem.
+
+## Primary docs
+
+- [README](README.md): public API, install, and usage examples.
+- [AGENTS](AGENTS.md): shortest practical onboarding path for coding agents.
+- [Agent Runbook](docs/AGENT_RUNBOOK.md): implementation and validation workflow.
+
+## Protocol references
+
+- [DSTAS 0.0.8 SDK Spec](docs/DSTAS_0_0_8_SDK_SPEC.md): normative behavior implemented by the SDK.
+- [DSTAS Script Invariants](docs/DSTAS_SCRIPT_INVARIANTS.md): script-level invariants and conservation rules.
+- [DSTAS Conformance Matrix](docs/DSTAS_CONFORMANCE_MATRIX.md): mapping of protocol rules to tests.
+
+## Additional references
+
+- [STAS3 Freeze/Multisig Notes](docs/STAS3_FREEZE_MULTISIG.md)
+- [Migration Notes](docs/MIGRATION.md)
+- [Agent Handbook (repo snapshot)](docs/AGENT_HANDBOOK.md)
+
+## Code entry points
+
+- `src/index.ts`
+- `src/dstas-factory.ts`
+- `src/dstas-bundle-factory.ts`
+- `src/script/eval/script-evaluator.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dxs-stas-sdk",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "TypeScript SDK for building and validating multiple Bitcoin SV transaction flows, including DSTAS token issue, transfer, split, merge, swap, freeze/unfreeze, and redeem.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",