Account Reference

This page documents the whole Account surface shared by both kinds. The kind-specific methods — deriveWallets / sliceWallets / dumpMnemonic (HD) and importPrivateKey (PK) — are covered in HD Accounts and PK Accounts.

Properties

Sessions and passwords

Passwords: per-account vs shared

Each account carries its own encryption password by default (hasOwnPassword: true, the default in accounts.create). Set hasOwnPassword: false at creation to share the workspace password instead.

tryUnlock

tryUnlock(password?: string): Promise<this>

Unlocks the account and returns it. A wrong password rejects with BAD_PASSWORD. For a shared-password account, calling tryUnlock() with no argument uses the workspace password. Concurrent calls with the same password share one derivation.

sub.lock();
sub.locked; // true

await sub.tryUnlock("wrong");   // → WativeError { code: "BAD_PASSWORD" }
await sub.tryUnlock("sub-pwd"); // resolves; sub.locked === false

checkPassword

checkPassword(password: string): Promise<boolean>

Verifies a password without changing the lock state. Returns false for a wrong password (rather than throwing).

resetPassword

resetPassword(oldPassword: string, newPassword: string): Promise<this>

Re-seals the mnemonic and every address ciphertext under a new password. After it resolves, the old password no longer opens the account.

Rotating a shared-password account (hasOwnPassword: false) also converts it to its own password: afterward hasOwnPassword is true and the account unlocks only with the new password — a no-argument tryUnlock() (which uses the workspace password) no longer opens it.

await sub.resetPassword("sub-pwd", "new-sub-pwd");
sub.lock();

await sub.tryUnlock("sub-pwd");     // → WativeError { code: "BAD_PASSWORD" }
await sub.tryUnlock("new-sub-pwd"); // resolves

lock

lock(): void

Synchronous. Wipes in-memory secrets immediately. After lock(), account.locked is true. Locking the whole workspace with ws.lock() locks every account it holds.

Default network

setDefaultNetwork(value: NetworkLike): Promise<void>

NetworkLike accepts several forms, all resolved to the network's slug:

import { Network } from "wative-core";

await acc.setDefaultNetwork("base");        acc.defaultNetwork; // "base"
await acc.setDefaultNetwork(8453);          acc.defaultNetwork; // "base"
await acc.setDefaultNetwork("0xa");         acc.defaultNetwork; // "optimism"
await acc.setDefaultNetwork(Network.Solana); acc.defaultNetwork; // "solana"

An unknown network — a slug not registered with the workspace, or an unknown chain id — rejects with UNSUPPORTED_NETWORK. The choice persists across lock and reopen. See Networks for the resolver and built-in networks.

Renaming and dropping

HD-only disabled slots

Disabling a wallet slot is a soft, reversible marker on a BIP-32 derivation index. It does not change which indices deriveWallets produces and does not touch keys — it hides the wallet from getWalletList() (unless you ask for all) and blocks that wallet's use for signing, sending, and dumping its private key (they throw WALLET_DISABLED). All of these are HD-only and throw UNSUPPORTED_OP on a PK account.

await acc.disableSlots([{ from: 14, to: 50 }]);
await acc.disableAddressNos([2, 10, 80]);
acc.getDisabledSlots();
// [{ from: 2, to: 2 }, { from: 10, to: 10 }, { from: 14, to: 50 }, { from: 80, to: 80 }]

await acc.enableSlots([{ from: 20, to: 30 }]);
acc.getDisabledSlots();
// [{ from: 2, to: 2 }, { from: 10, to: 10 }, { from: 14, to: 19 }, { from: 31, to: 50 }, { from: 80, to: 80 }]

Listing wallets

getWalletList(force?: boolean): Wallet[]

Returns the account's wallets. By default only the enabled ones, each keeping its natural id — a disabled id is skipped, never renumbered, so disabling id 3 leaves the list as …, 2, 4, …. Pass force: true to include disabled wallets too, each carrying its wallet.disabled flag. account.wallets remains the raw, unfiltered collection.

await acc.disableAddressNos([2, 4]);
acc.getWalletList().map((w) => w.id);            // [0, 1, 3, 5]  — enabled only, natural ids
acc.getWalletList(true).map((w) => w.disabled);  // [false, false, true, false, true, false]
acc.wallets.length;                              // 6 — raw, unaffected by the markers

Types

AccountOrgType

type AccountOrgType = "HD" | "PK";

AccountCollection

ws.accounts is an AccountCollection — a read-only array of Account with extra methods.

interface AccountCollection extends ReadonlyArray<Account> {
  create(
    displayName: string,
    password: string,
    secret: string,
    defaultNetwork?: NetworkLike,
    opts?: { kind?: AccountOrgType; hasOwnPassword?: boolean },
  ): Promise<Account>;
  add(account: Account): Promise<Account>;
  drop(account: Account): Promise<void>;
  bySlug(slug: Slug): Account | null;
}

• add adopts an existing Account into this workspace (a copy-in); the account's networks must exist here, and a shared-password account's secrets must open with this workspace's password.
• drop removes an account this workspace holds and wipes its keys.
• bySlug returns the live account for a slug, or null.

WalletCollection

account.wallets is a WalletCollection.

interface WalletCollection extends ReadonlyArray<Wallet> {
  add(wallet: Wallet): Promise<Wallet>;
  drop(wallet: Wallet): Promise<void>;
  byId(id: number): Wallet | null;
}

drop is private-key-only: on an HD account it throws UNSUPPORTED_OP (shorten the account with sliceWallets, or hide an index with disableSlots), and on a PK account it refuses the account's last wallet with UNSUPPORTED_OP. See Wallets & Addresses for the Wallet and Address surface.

Damaged records

A record that is on disk but cannot be read — it cannot be decrypted, or its stored name is no longer valid (for example a name from an older version that exceeds the 32-character limit) — is withheld from ws.accounts so one unreadable file cannot deny access to every other account. Those names are still reported — as a read-only list on the workspace, not the account:

ws.damagedAccountSlugs; // ReadonlyArray<string>

Errors thrown across this surface use WativeError with a .code — see Errors.