npm package: @swarmnetwork/vault-sdk
Description: TypeScript SDK for interacting with Swarm Vault on Sui
Latest version: 1.0.4

# @swarmnetwork/vault-sdk

TypeScript SDK for interacting with Swarm Vault on the Sui blockchain. Create encrypted, user-owned vaults and manage secrets with fine-grained access control.

## Installation

```bash
pnpm add @swarmnetwork/vault-sdk
```

The Sui SDK is a peer dependency:

```bash
pnpm add @mysten/sui
```

## Package Exports

| Export Path                                 | Description                                             |
| ------------------------------------------- | ------------------------------------------------------- |
| `@swarmnetwork/vault-sdk`                   | Main entry — re-exports all modules                     |
| `@swarmnetwork/vault-sdk/crypto`            | ECDH encryption, key derivation, secret encrypt/decrypt |
| `@swarmnetwork/vault-sdk/sui/vault`         | Vault transaction builders and query helpers            |
| `@swarmnetwork/vault-sdk/sui/user-registry` | User registration and public key lookup                 |
| `@swarmnetwork/vault-sdk/indexer`           | HTTP client for the Vault Indexer API                   |

## Environment Variables

| Variable                   | Description                                                   |
| -------------------------- | ------------------------------------------------------------- |
| `SUI_NETWORK`              | Target network: `devnet`, `testnet`, `mainnet`, or `localnet` |
| `SWARM_VAULT_PACKAGE_ID`   | Deployed Vault Move package ID                                |
| `GLOBAL_CONFIG_ID`         | Global config object ID                                       |
| `USER_REGISTRY_PACKAGE_ID` | Deployed User Registry package ID                             |
| `USER_REGISTRY_OBJECT_ID`  | User Registry shared object ID                                |
| `PRIVATE_KEY`              | Sui private key (CLI only)                                    |
| `VAULT_INDEXER_URL`        | Optional override for the indexer base URL                    |

See `.env.example` for a starter template.

## Library Overview

### Vault (`lib/sui/vault`)

Transaction builders for creating vaults, adding/removing members, and managing secrets. Includes query helpers to fetch vault details, list vaults by owner, and read global config.

### User Registry (`lib/sui/user-registry`)

Register users, look up public keys, and fetch profiles. Required for encrypting secrets to specific vault members.

### Crypto (`lib/crypto`)

ECDH (P-256) + AES-GCM encryption layer. Derives encryption keypairs from Sui signers and provides `encryptSecret` / `decryptSecret` utilities.

### Indexer (`lib/indexer`)

`VaultIndexerClient` for querying indexed on-chain events — vault creation, secret changes, member updates, invites, and activity logs.

## CLI

Two CLI entry points are included for local development and administration:

```bash
# Vault operations
pnpm cli:vault <command> [options]

# User registry operations
pnpm cli:user-registry <command> [options]
```

### Vault CLI Commands

| Category | Commands                                                                                                               |
| -------- | ---------------------------------------------------------------------------------------------------------------------- |
| Vaults   | `create-vault`, `buy-package`, `fetch-vault`, `list-vaults`, `check-vault-validity`                                    |
| Secrets  | `add-secret`, `update-secret`, `remove-secret`, `list-secrets`, `get-secrets`, `load-secret`                           |
| Members  | `add-member`, `remove-member`, `is-authorized`, `is-admin`                                                             |
| Admin    | `update-fees`, `add-package`, `remove-package`, `grant-credits`, `set-treasury`, `withdraw`, `add-tier`, `remove-tier` |
| Indexer  | `indexer-vaults-by-owner`, `indexer-secrets-by-vault`, `indexer-members-by-vault`, `indexer-vault-activity`, and more  |

### User Registry CLI Commands

`register`, `has-registered`, `get-public-key`, `get-profile`, `fetch-registry`, `fetch-profiles`

## Scripts

| Script                   | Description                   |
| ------------------------ | ----------------------------- |
| `pnpm build`             | Compile TypeScript to `dist/` |
| `pnpm lint`              | Run ESLint                    |
| `pnpm format`            | Run Prettier                  |
| `pnpm cli:vault`         | Run the Vault CLI             |
| `pnpm cli:user-registry` | Run the User Registry CLI     |

## License

MIT