altude-js

TypeScript SDK for Altude — gasless Solana infrastructure with an OWS-conformant vault.

Packages

Package	Description
@altude/core	Shared types, BIP-39/BIP-44 key derivation, RPC client, error taxonomy
@altude/vault	OWS vault — encrypted key storage, API key management, policy engine
@altude/solana-adapter	Bridge: OWS vault → Gill / @solana/web3.js signer
@altude/gasstation	Gasless transaction relay via the Altude API
@altude/nft	Gasless NFT ops — Metaplex Core, compressed NFTs (cNFTs)

Quick Start

pnpm add @altude/vault @altude/gasstation @altude/solana-adapter

import { AltudeVault } from '@altude/vault'
import { AltudeGasStation } from '@altude/gasstation'
import { createOWSGillSigner } from '@altude/solana-adapter'

// 1. Initialize the OWS vault (uses ~/.ows by default)
const vault = new AltudeVault()

// 2. Create a wallet
const wallet = await vault.createWallet({
  name: 'my-wallet',
  passphrase: 'your-strong-passphrase',
})
console.log('Solana address:', wallet.accounts[0].address)

// 3. Create an API key for agent use (no passphrase required at sign time)
const { token } = await vault.createApiKey({
  name: 'my-agent',
  walletId: wallet.id,
  passphrase: 'your-strong-passphrase',
})
console.log('Agent token (store securely):', token)

// 4. Sign with the agent token (policies enforced)
const sig = await vault.signMessage(wallet.id, 'Hello Altude', token)
console.log('Signature:', sig.signature)

// 5. Gasless transaction relay
const gasStation = new AltudeGasStation({
  apiKey: process.env.ALTUDE_API_KEY,
  network: 'devnet',
})
const blockhash = await gasStation.getBlockhash()
const balance = await gasStation.getBalance({ address: wallet.accounts[0].address })
console.log('Balance:', balance.uiAmount, 'SOL')

OWS Vault

@altude/vault is a TypeScript implementation of the Open Wallet Standard (OWS) vault component.

What it implements

• Storage format v2 — ~/.ows/wallets/, ~/.ows/keys/, ~/.ows/policies/, ~/.ows/logs/ with OWS-mandated filesystem permissions (chmod 700/600)
• AES-256-GCM + scrypt — passphrase-derived wallet encryption (N=65536, r=8, p=1)
• HKDF-SHA256 — API key token encryption (info = "ows-api-key-v1")
• Policy engine — allowed_chains, expires_at, allowed_typed_data_contracts declarative rules; custom executable policies (Node.js)
• Audit log — append-only JSONL at ~/.ows/logs/audit.jsonl
• Backup/restore — AES-256-GCM encrypted tar archive
• Signing interface — sign(), signMessage() (Ed25519)

Vault file compatibility

Wallet files created by @altude/vault are byte-for-byte compatible with those produced by the ows CLI and @open-wallet-standard/core Node.js bindings.

Access model

Mode	Credential	Policies enforced
Owner	Passphrase	❌ No — full access
Agent	OWS API token (ows_key_*)	✅ Yes

API key creation protocol

Follows the 9-step OWS protocol:

1. Owner enters passphrase → vault decrypts wallet secret
2. Generates random token: ows_key_<256 random bits>
3. HKDF-SHA256(salt, token, "ows-api-key-v1") → 32-byte key
4. Re-encrypts wallet secret with derived key (AES-256-GCM)
5. Writes key file with token_hash: SHA256(token) and encrypted copy
6. Returns token once — never stored in plaintext

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run all tests
pnpm test

# Typecheck
pnpm typecheck

Requirements

• Node.js ≥ 18
• pnpm ≥ 9

Releases

Publish manifest

release-manifest.json at the repo root is the single source of truth for which packages are published to npm:

{ "publish": ["@altude/core", "@altude/gasstation"] }

Everything else in packages/* is treated as work-in-progress: it is marked "private": true and added to the Changesets ignore list, so it is never published — while still being built and tested locally and in CI.

To promote a package, add its name to publish and run:

pnpm manifest:sync   # applies the manifest to package.json + .changeset/config.json
pnpm manifest:check  # verifies everything is in sync (run in CI)

The release workflow builds, lints, typechecks and tests only the packages listed in the manifest.

Workflow

• CI runs on every PR and push via .github/workflows/ci.yml.
• PRs that change publishable packages must include a Changeset; CI verifies this before merge.
• Publishing is automated by .github/workflows/release.yml on every merge to main, and the workflow can also be re-run manually with workflow_dispatch.
• Configure npm credentials in a repository secret named NPM_TOKEN; the release job exposes it to pnpm/npm as NODE_AUTH_TOKEN.
• Version bumps are handled with Changesets. Add a changeset in feature PRs (pnpm changeset) and the release workflow will:
  • open/update a release PR with incremented versions and changelogs
  • publish to npm and create release tags when that release PR is merged to main

Architecture

Built on:

• Gill — ergonomic Solana client (built on @solana/kit)
• @scure/bip39 + @scure/bip32 — audited BIP-39/BIP-44
• @noble/ed25519 — audited Ed25519

License

MIT