Credentials SDK

Overview

Production package: `@acta-team/credentials` (install with npm / pnpm / yarn). Older references to `@acta-team/acta-sdk` point at the same surface: React `ActaConfig` mounts an `ActaClient` in context, exposed through `useActaClient()`, plus hooks for vault reads/writes and credential issuance/revocation. The network comes from `baseURL` (mainNet vs testNet).

Install

npm install @acta-team/credentials

Architecture

Vaults are single-tenant: each owner has their own vc-vault contract, deployed deterministically by a single vc-vault-factory per network. The API/SDK derive an owner's vault address from (factory, owner, userSalt); the default userSalt is 32 zero bytes, giving one canonical vault per owner. Pass a non-default userSalt on create/read/issue calls to select an additional vault for the same owner.

Issuance is open by default (deny-by-exception): owners block issuers with denyIssuer and unblock them with allowIssuer. The issuer must be a registered, resolvable did:stellar; bare wallet addresses and did:pkh are no longer accepted as issuer DID.

Exports

  • `ActaConfig`: Provider - required baseURL; optional explicit apiKey.
  • `useActaClient`: Returns the contextual ActaClient (must be rendered under ActaConfig).
  • Hooks: useVault, useCredential, useVaultRead.
  • `ActaClient`: direct client methods, including getHealth, getConfig (cached ~5 min, clearConfigCache() to reset), vaultSetDid, vaultSetNewOwner, vaultPush, and sponsoredVaultCreate (see sponsoredVault).
  • Errors: ActaApiError and normalizeError (see Error handling).
  • Identity: getOrCreateIssuerIdentity / getIssuerIdentity on the client, plus storage helpers (IndexedDbIssuerIdentityStorage, InMemoryIssuerIdentityStorage, autoSelectStorage).
  • URLs: mainNet, testNet (string constants for the two API hosts; any custom string baseURL is also accepted, e.g. staging or localhost).
  • Subpath exports: @acta-team/credentials/types and @acta-team/credentials/hooks. The package ships both ESM and CJS with TypeScript declarations; ActaConfig is a client component ("use client"), compatible with the Next.js App Router.

Provider (`ActaConfig`)

tsx
import { ActaConfig, mainNet } from "@acta-team/credentials";

export function App() {
  return (
    <ActaConfig baseURL={mainNet}>
      {/* your app */}
    </ActaConfig>
  );
}

Pass `apiKey` to the provider if you do not want to rely on env-based resolution.

Environment variables

The library resolves an API key in this order unless you pass apiKey on ActaConfig:

  • Network-specific: ACTA_API_KEY_MAINNET, ACTA_API_KEY_TESTNET
  • Fallback for either network: ACTA_API_KEY

The key is attached as header `X-ACTA-Key` on outbound requests.

Accessing the client

ts
import { useActaClient } from "@acta-team/credentials";

const client = useActaClient();
const config = await client.getConfig();
// config: { rpcUrl, networkPassphrase, networkType, factoryContractId, vaultWasmHash, didStellarRegistryId, actaContractId }
// actaContractId is a back-compat alias of factoryContractId

Hooks summary

  • `useVault` - createVault, denyIssuer, allowIssuer (plus back-compat aliases: authorizeIssuer ≙ allow, revokeIssuer ≙ deny).
  • `useCredential` - issue, revoke.
  • `useVaultRead` - listVcIds, getVc, verifyVc.

userSalt is an optional argument on the vault-write and issue calls (createVault, denyIssuer, allowIssuer, issue, revoke); omit it to use the owner's canonical vault. The useVaultRead hooks always target the canonical vault.

Issuer identity (auto-onboarding)

The SDK owns issuer DID onboarding: when issue is called without issuerDid, the client transparently calls getOrCreateIssuerIdentity({ controller, signTransaction }) - it generates an Ed25519 key, mints a did:stellar, registers it on-chain (one wallet signature, first time only), and persists the identity.

  • Browser: identities persist in IndexedDB, with the private key encrypted at rest.
  • Node / server: the default storage is in-memory - a new DID would be minted on every restart. Server-side integrators must supply a persistent IssuerIdentityStorage via ActaClientIdentityOptions.

Error handling

Every client request that fails rejects with an `ActaApiError` (status, code, requestId?, isTimeout, isNetworkError, details?). Requests time out after 30 seconds by default. Use the exported normalizeError(err) to convert unknown errors into ActaApiError.

sponsoredVault

ActaClient.sponsoredVaultCreate prepares/submits the factory's deploy_sponsored when a sponsor pays or signs vault creation for an owner. The API route requires an admin-role API key. See sponsoredVault for signatures and payloads.

Owners can be ordinary Stellar accounts (G...) or smart-wallet contract IDs (C...): when signing is delegated to ACTA infra, omit or follow the signatures described on each hook page.

Deprecated methods

createCredential, getDefaults, prepareStoreTx, prepareListVcIdsTx, prepareGetVcTx, and vaultStore are deprecated stubs scheduled for removal in 2.0.0. Migrate to vcIssue, getConfig, vaultListVcIdsDirect, and vaultGetVcDirect (or the hooks).