@cardanotech/sdk provides typed, transport-neutral clients for cardano.tech gateway products. Version 1 exposes the hosted Wallet Proof create, complete, and receipt methods without inventing a workload credential format or taking custody of wallet keys.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

pnpm add @cardanotech/sdk @api.global/typedrequest

Browser wallet signing is provided separately by the non-custodial Wallet Proof library:

pnpm add @cardanotech/walletproof

Gateway client

The client accepts a TypedTarget, the supported custom transport boundary from @api.global/typedrequest. The target receives and returns complete TypedRequest envelopes and owns endpoint selection, workload authentication, retries, and any connection lifecycle.

The target owns transport-level retries. TypedRequest 3.4 also honors protocol-level retry envelopes; those retries currently have no caller-provided attempt limit or cancellation control.

import {
  TypedTarget,
  type IPostMethod,
} from '@api.global/typedrequest';
import {
  CardanoGatewayClient,
  cardanoInterfaces,
} from '@cardanotech/sdk';

declare const sendAuthenticatedEnvelope: IPostMethod;

const target = new TypedTarget({
  postMethod: sendAuthenticatedEnvelope,
});
const gateway = new CardanoGatewayClient({ target });

const response = await gateway.createWalletProofChallenge({
  subjectRef: 'subject-internal-0001',
  origin: 'https://app.example',
  network: 'testnet',
  purpose: 'link-wallet',
  idempotencyKey: 'wallet-link-create-0001',
});

const challenge: cardanoInterfaces.data.IWalletProofChallenge = response.challenge;

The SDK deliberately has no unauthenticated URL constructor, token field, authorization header, or Cardano-specific TypedSocket tag. The gateway's workload authentication contract must be explicit before a built-in network transport is added. Tenant, workload, permissions, issuer, and audience remain trusted server-side context and are never accepted from the Wallet Proof request DTOs.

Wallet signing flow

The consumer backend creates a challenge through CardanoGatewayClient and sends that challenge to its browser. The browser uses the released non-custodial proof client; wallet discovery and user consent remain application responsibilities.

import { WalletProofBrowserClient } from '@cardanotech/walletproof/browser';
import type { IWalletProofChallenge } from '@cardanotech/walletproof';

declare const challenge: IWalletProofChallenge;
declare const walletApi: Parameters<WalletProofBrowserClient['createSubmission']>[0];

const proofClient = new WalletProofBrowserClient();
const submission = await proofClient.createSubmission(walletApi, challenge);

The browser returns the submission to its trusted consumer backend. That backend uses completeWalletProofChallenge() with a new idempotency key. Neither package generates, receives, stores, or logs a wallet seed phrase or private key.

Public methods

Client method	Hosted contract
`createWalletProofChallenge({ subjectRef, origin, network, purpose, idempotencyKey })`	`{ challenge }`
`completeWalletProofChallenge({ submission, idempotencyKey })`	`{ receipt }`
`getWalletProofReceipt({ receiptId })`	`{ receipt }`

The client uses the method constants exported by @cardanotech/interfaces and does not expose an arbitrary-method escape hatch. It also suppresses TypedRequest global payload hooks for these methods so proof submissions are not exposed to process-wide observability callbacks.

ICardanoGatewayClientOptions exposes only the required target. cardanoInterfaces re-exports the published data and request namespaces for consumer annotations. Gateway failures reject with TypedResponseError; its errorData matches ICardanoGatewayErrorData (code, requestId, retryable, and optional retryAfterMs).

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@cardanotech/sdk