Class Salt

Creates an instance of the Salt SDK

The authenticated user's secp256k1 public key, recovered server-side from the SIWE signature during authenticate. Distinct from the wallet's EVM address (a hash of this key) — needed wherever a caller must encrypt something to the user, e.g. the publicKey param of RoboHost.generateSetupScript and RoboHost.generateCloudFormationUrl. Undefined until authenticate completes, and cleared again on logout or an unrecoverable token refresh.

Disconnect the websocket connection. Call this when you are done using a long-lived socket (e.g. after stopping a NudgeListener) to allow the Node.js process to exit cleanly.

Subscribe to the session becoming unauthenticated — an explicit logout, or a refresh that could not recover it (the refresh token is missing, expired, or was revoked). Fires even when nothing in your own code is currently awaiting a rejection (e.g. a background socket reconnect that failed to refresh).

This doesn't force any particular response — it's just the signal that the session is done, so you can chain whatever makes sense for your app: re-authenticate immediately, redirect to a login screen, log and exit, etc.

Subscribe directly to the relay's nudge event on the underlying socket. This is the same wire-level event NudgeListener subscribes to internally; exposing it here lets consumers observe nudges without going through NudgeListener's validation, dedup, and nudgeReceived event chain — useful for diagnostics, custom routing, or applications that don't want the auto-join machinery.

Must be called after authenticate (which initialises the socket).

Subscribe to the underlying socket's lifecycle: connect, disconnect, reconnect attempts, reconnect-failed terminal state, and auth errors from the relay. Useful for long-running consumers (notably robo daemons) that need to log, alert, or trigger re-auth on relay availability changes.

Must be called after authenticate (which initialises the socket).

The handler does not replay the current connection state on subscribe — it only fires on subsequent transitions. Seed your initial state from a separate check; do not assume the first event reflects the state at subscribe time.

Subscribe to any application-level event pushed to this user by the relay (e.g. server-side status updates forwarded via POST /user). No-op before connect or authenticate has been called.

The event name and payload type T are the caller's responsibility — salt-sdk does not define or validate application-specific event shapes.

Creates a new account within an Organisation. Registers the account, nudges co-signers to join the MPC keygen ceremony, and returns before the ceremony completes.

Returns an AccountCeremony. Call wait() to drive the keygen ceremony and finalise the account (derives the public key and EVM address). If you skip wait().

The SDK automatically determines the required robo signers based on the number of human signers provided: an account is always N humans + (N-1) robos, so signers must contain exactly 2, 3, or 4 human addresses (yielding 2+1, 3+2, or 4+3 signer configurations).

Account creation is off-chain for the human and robo signers — no gas is required from any of them. The on-chain shard-registry write is performed and paid for server-side.

The organisation must have a provisioned, online robo host (see createRoboHost). The SDK resolves the robo signers via the API and fails with RoboStatusError if too few robo signers are online.

Gets the details of a specific account. The user must have adequate permissions to view the account.

Lists an account's signers in signer order, each tagged with its role (human or robo). Robo identity is not encoded in the signer list itself, so this resolves it from the organisation's robo set.

Use this to label a "who's joining" presence list: the AccountCeremony presence/ready events carry only address and isOnline, so build a lookup from this method and join by address. Reading the robo set requires permission only human users hold (a robo guardian does not), which is why presence stays role-free.

Gets the transactions of a specific account. The user must have adequate permissions to view the account's transactions.

Join an existing keygen ceremony from a received nudge payload. Use this when the nudge was received and stored before the signer was available (e.g. before the wallet was connected), so the join() closure can be constructed lazily at the point the user consents.

Opens a websocket connection to receive account setup nudges and automatically joins the MPC keygen ceremony for each one.

The caller's signer is used to save the keyshare once the ceremony completes. Listen to the setupComplete event on the returned NudgeListener to be notified when a new account has been set up.

Hosts an MPC threshold signing ceremony over a plain-text message, hashed per EIP-191 — the personal_sign scheme, where the message is prefixed with "\x19Ethereum Signed Message:\n<length>" before hashing. Use it for login challenges, off-chain proofs of account control, and anything else a wallet's personal_sign would cover. To sign EIP-712 structured data instead, use signTypedData.

message is always treated as UTF-8 text: a 0x-prefixed string is hashed as those literal characters, never decoded to bytes. This method signs no other form — it is not the (deprecated, unprefixed) eth_sign, and it never accepts a pre-computed digest, so what it signs can always be reconstructed from the text you passed in.

Mirrors submitTx: it returns the SignMessageHostCeremony rather than the signature, so you can subscribe to progress events before driving it. Call wait() to run the ceremony and obtain the assembled signature.

All account signers must have an active NudgeListener so they can join the ceremony automatically. This method drives the host side; co-signers are nudged and handled transparently.

Hosts an MPC threshold signing ceremony over EIP-712 typed structured data — the eth_signTypedData_v4 scheme, where the digest is built from the domain separator and the hashed struct rather than from free text. Use it wherever a contract or protocol expects a typed-data signature. For plain-text messages use signPersonalMessage.

The caller's signer plus the account's robo guardians co-sign, producing a single EVM signature that recovers to the account's public key — the same human + robo path as signPersonalMessage and submitTx, differing only in how the signed digest is derived.

As with signPersonalMessage, no pre-computed digest is ever accepted: the typed data is distributed to the co-signers, and each derives the digest itself, so what was signed is always reconstructible from the typedData you passed in.

Verifies the integrity of all keyshares for a Salt account by exercising two independent signing flows against a fixed challenge:

1. Recovery flow — nudges every non-robo (human) signer. Proves that the human keyshares alone can produce a valid threshold signature, validating the account's recovery path.

2. Regular flow — nudges every robo signer (the calling human is the host). Proves that the standard transaction signing path — one human plus the robo guardians — is operational.

Both ceremonies must complete successfully for the account's keyshares to be considered verified. A failure in either indicates a corrupted or missing keyshare backup.

All account signers (human and robo) must have an active NudgeListener so they can join each ceremony automatically.

Initiate the SIWE authentication flow to get an authentication token from the Salt API. Signs a SIWE message + nonce with the supplied viem WalletClient; the server verifies and returns an access token plus a companion refresh token.

If you already have a token, set it via setAuthToken or in the constructor.

Connect the underlying relay socket using the current auth token. Idempotent — safe to call repeatedly; a live connected socket is left untouched. Call this immediately after setAuthToken to ensure the socket is ready before any nudges or server-push events are emitted, without waiting for a ceremony entry point.

Returns the current refresh token, if any. Persist this (e.g. to secure storage) and pass it back via ConstructorParams.refreshToken to resume a session after a restart without re-running the SIWE flow.

Note the refresh token rotates on every use, so always read the latest value (e.g. after each call) rather than caching the first one.

Logs out the current session: revokes the refresh token server-side, clears the in-memory tokens, and disconnects the websocket. After this the instance is unauthenticated — call authenticate to use it again.

Resolves even if the network call fails; local state is always cleared.

Sets the authentication token for the Salt SDK. This is useful if you have previously logged in and stored the token. You can also provide the token to the constructor If you do not have a token already, you can use the authenticate method to obtain one.

Accepts an Invitation to an Organisation. The list of transactions for the current user can be retrieved with getOrganisationsInvitations.

Creates a new Organisation. The authenticated user will be the owner. Collaborators can optionally be invited at creation time — they will receive invitations that can be accepted via acceptOrganisationInvitation.

This operation is off chain, so it does not require any gas.

Declines a pending Invitation to an Organisation. The counterpart to acceptOrganisationInvitation; pending invitations are listed with getOrganisationsInvitations.

Gets the list of Accounts that belong to a Organisation.

Gets a single Organisation by its ID. The user must be a collaborator on the organisation.

Gets the list of Organisations that the current user is a collaborator on. Requires authentication.

Returns pending Invitation to an Organisation for the current user. They can be accepted using acceptOrganisationInvitation.

Invites a new collaborator into an existing Organisation. The invitee is added with status "Invited" and can join by accepting the invitation via acceptOrganisationInvitation. Only owners of the organisation may invite collaborators.

Every existing collaborator is left untouched. To add collaborators at creation time instead, use the collaborators option of createOrganisation.

Leaves an Organisation as the authenticated user. Use this to remove yourself; to remove another collaborator as an owner, use removeCollaborator.

The collaborator is marked Inactive (the API retains collaborators for audit history) and any pending invitation for you is dropped. An organisation must always keep at least one active owner, so the last active owner cannot leave.

Removes a collaborator from an Organisation by revoking their access. The Salt API retains collaborators for audit history, so the collaborator is marked Inactive rather than deleted — they will still appear in getOrganisationById with status Inactive. Every other collaborator is left untouched. Only owners of the organisation may remove collaborators.

An organisation must always retain at least one active owner, so removing the last active owner is rejected.

Updates a single collaborator within an Organisation. Use this to change a collaborator's display name, their access level (the permission tier the API enforces), their free-text role label (cosmetic, no permission effect), or their status (to re-activate a removed collaborator or deactivate one). Only owners of the organisation may update collaborators.

Every other collaborator is left untouched. An organisation must always retain at least one active owner, so demoting the last owner or deactivating them is rejected. A collaborator's address is immutable and cannot be changed here.

Creates a new Policy on a Salt account. Policies control what transactions are allowed, denied, or require approval before being signed by the robo guardians.

Only one policy may exist per type + chain on an account; attempting to create a second of the same type for the same chain throws a DuplicatePolicyError. To express several constraints of one type, put them in that policy's params array.

nominated_approvers policies cannot be created: the policy type exists on the API but approval enforcement is not yet implemented, so creating one throws a ValidationError. For contract_param_restriction policies each restriction's solidityType is derived from its functionSignature/ paramIndex (so you need not supply it); this catches a few common mistakes early — malformed signatures, out-of-range indexes, or illegal operators — throwing a ValidationError before any request is made. It is not exhaustive validation.

Deletes an existing Policy by its ID.

Fetches an existing Policy by its ID.

Lists all policies attached to a Salt account.

Reads the policies embedded in the account record, so this is a convenience wrapper over getAccount — use it when you only need the policy list.

Runs a policy check for a Salt account.

Evaluates the account's policies that apply to the proposed transaction and returns which were validated, which were rejected (breach), and whether the account has policies that were not evaluated — see PolicyCheck. Run this before submitTx to surface policy violations early: if a breaching transaction is submitted anyway, the signing ceremony fails with a PolicyBreachError.

Updates an existing Policy by its ID. Replaces the policy's params with the new values provided.

When updating a contract_param_restriction policy, each restriction's solidityType is derived from its functionSignature/paramIndex (so you need not supply it). This catches a few common mistakes early — a malformed signature, an out-of-range paramIndex, or an operator that is illegal for the parameter type — throwing a ValidationError before any request is made. It is not exhaustive validation.

Completes 2FA activation for a robo host, flipping it from inactive to active. This is what makes a robo host usable. getRoboQuorum.

Authorised by the owner, not a privileged session. Like authenticate, this builds and signs a SIWE message itself — the caller passes the owner's walletClient and the host's setup OTP (the code shown during robo-guardian setup — see RoboHost.otp); this method embeds that OTP in the SIWE statement, has the wallet sign it, and submits it. That proves both control of the owner wallet and possession of the setup code. On success the server marks the robo active and consumes the OTP, so activation is single-use.

Registers robos for an Organisation and creates their host record. No robo is running after this call — it creates only the server-side record. The robo signers come online once you provision a host with RoboHost.generateSetupScript or RoboHost.generateCloudFormationUrl and its setup completes. Treat the setup OTP as a secret. Only organisation owners can create a robo host.

Fetches the existing robo host for an organisation — its public record only: name, signers, setup OTP (present until activation consumes it) and activation state. Everything needed to provision and activate a host is here; readable by any organisation collaborator with robos access, on any tenant.

The host's encrypted seed backup is not included — fetch it separately with getRoboHostSecrets, which is restricted to owners on privileged sessions.