Vault Reference

@dexterai/vault provides account readers, operation encoders, instruction builders, and signers for the Dexter Vault program. Use Connect for app sign-in and the x402 SDK for API payments.

npm install @dexterai/vault@0.43.4 @solana/web3.js@1

Version 0.43.4 includes V7 instruction contracts. Use the matching message builders and deployed program; older revoke and voucher encodings are incompatible with new issuance.

Imports

Read a Vault

The Vault PDA, Swig state address, and deposit address identify different accounts. Supply the Vault PDA to these readers.

import { Connection, PublicKey } from '@solana/web3.js';
import { readVaultFull } from '@dexterai/vault/reader';
import { fetchVaultSessionAccounts, isSessionLive } from '@dexterai/vault/session';

export async function inspectVault(rpcUrl: string, vaultAddress: string) {
  const connection = new Connection(rpcUrl, 'confirmed');
  const vaultPda = new PublicKey(vaultAddress);
  const vault = await readVaultFull(connection, vaultPda);
  if (!vault.exists) throw new Error('Vault account not found');

  const sessions = await fetchVaultSessionAccounts(connection, vaultPda);
  return {
    version: vault.version,
    swigAddress: vault.swigAddress,
    pendingVoucherCount: vault.pendingVoucherCount,
    outstandingLockedAmount: vault.outstandingLockedAmount,
    sessions: sessions.map((entry) => ({
      address: entry.address,
      active: isSessionLive(entry),
      registration: entry.session,
    })),
  };
}

This performs RPC reads without signing. Atomic amounts are decimal strings. A session is active when its version is 1 and it has not expired. fetchVaultSessionAccounts also returns expired sessions awaiting cleanup.

Register a Session

sessionRegisterMessage takes the program, Vault, session key, counterparty, cap, expiry, nonce, and revolving capacity. It encodes this 188-byte V2 layout:

New registrations use sessionVoucherV2Nonce with the current passkey authorization nonce. This binds the session generation to the approved operation.

The instruction also requires the payer, Swig state, token account, and current sibling sessions. Fetch siblings immediately before building. Include every other session with a nonzero version, including expired sessions awaiting cleanup; the builder orders them and excludes the target.

Use resolveVaultUsdcAta to probe the token account. A missing account is represented by null. Node-backed credit additionally requires the complete authenticated node chain in leaf-to-root order.

For creation or rotation, composeRevokeThenRegister assembles the required instructions. Despite its historical name, its V7 active-session path uses one signed replacement operation. An inactive target uses registration. The caller supplies the passkey ceremony and transaction transport.

Revoke or Replace

Revocation binds the current session state and the Vault's pending-voucher count. Fetch those values together before requesting approval. Changed state requires a new approval.

The revoke message contains the session PDA, session key, registered scope, spending counters, last locked sequence, and expectedPendingVoucherCount. Pass that same pending count to buildRevokeSessionKeyInstruction.

Replacement binds the retired session's scope and counters, the new registration, and the passkey authorization nonce. Reusing a prior signature after any bound value changes will fail verification.

Passkeys and Vouchers

DexterApiBrowserPasskeySigner.signOperation(message) returns the signature, clientDataJSON, and authenticatorData. Its server policy supplies an authorization envelope bound to the operation hash, Vault, program, and replay-guard nonce. Use the SDK's ceremony and precompile builders when assembling a transaction.

Ed25519 session keys sign vouchers. For new V2 vouchers, contextBoundVoucherV2Message returns the digest of a 208-byte context containing the program, Vault, session, seller, channel, registration nonce, amount, and sequence. voucherPayloadMessage and buildVoucherMessage retain the historical V1 encoding for recovery of existing records.

Grant Requests

requestSpendGrant and encodeSpendGrantRequest create a request for a consent screen. parseSpendGrantRequest validates incoming data; approveSpendGrant applies the owner's edits and requests the signature.

Resolve the Vault from the owner's identity. Treat app names and icons as display metadata. The signed counterparty and limits determine the authorization. Approval returns the signed operation and parameters; the sponsor still needs to build, submit, and confirm the registration transaction.