@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

pnpm add @swarmnetwork/vault-sdk

The Sui SDK is a peer dependency:

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:

# 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