TLSNotary API Reference

TLSNotaryService Class

The TLSNotaryService class manages attestation tokens and proof storage. It provides methods for both direct execution and wallet-confirmation flows.

import { TLSNotaryService } from '@kynesyslabs/demosdk/tlsnotary';

const service = new TLSNotaryService(demos);

Methods

requestAttestation()

Requests an attestation token for a target URL. Burns 1 DEM and returns a proxy URL.

const { proxyUrl, tokenId, expiresAt } = await service.requestAttestation({
    targetUrl: 'https://api.example.com/data'
});

requestAttestationWithConfirmation()

Same as requestAttestation() but allows user confirmation before broadcasting. Recommended for wallet extension apps.

const response = await service.requestAttestationWithConfirmation(
    { targetUrl: 'https://api.example.com/data' },
    {
        onConfirm: async (details) => {
            // Show transaction to user for approval
            // details.txHash, details.amount, details.description
            return await showUserConfirmDialog(details);
        }
    }
);

createTLSNotary()

Convenience method that handles the full setup: request token → get proxy → create TLSNotary instance → initialize WASM.

const { tlsn, tokenId, proxyUrl } = await service.createTLSNotary({
    targetUrl: 'https://api.example.com/data'
});

// Ready to attest immediately!
const result = await tlsn.attest({ url: 'https://api.example.com/data' });

createTLSNotaryWithConfirmation()

Same as createTLSNotary() but with user confirmation. Recommended for wallet extension apps.

const { tlsn, tokenId } = await service.createTLSNotaryWithConfirmation(
    { targetUrl: 'https://api.example.com/data' },
    {
        onConfirm: async (details) => {
            return await showUserConfirmDialog(details);
        }
    }
);

storeProof()

Stores an attestation proof on-chain or IPFS.

const { txHash, storageFee } = await service.storeProof(
    tokenId,
    JSON.stringify(presentation),
    { storage: 'onchain' } // or 'ipfs'
);

storeProofWithConfirmation()

Same as storeProof() but with user confirmation. Recommended for wallet extension apps.

const { txHash, storageFee } = await service.storeProofWithConfirmation(
    tokenId,
    JSON.stringify(presentation),
    { storage: 'onchain' },
    {
        onConfirm: async (details) => {
            return await showUserConfirmDialog(details);
        }
    }
);

calculateStorageFee()

Calculate the fee for storing a proof.

// Returns a bigint in OS (smallest units): 6 DEM for a 5KB proof (1 base + 1 per KB).
// Convert for display with denomination.osToDem(fee).
const fee = service.calculateStorageFee(5);

Response Types

AttestationTokenResponse

interface AttestationTokenResponse {
    proxyUrl: string;      // WebSocket proxy URL for attestation
    tokenId: string;       // Unique token ID
    expiresAt: number;     // Unix timestamp when token expires
    retriesLeft: number;   // Number of retry attempts remaining
    txHash: string;        // Transaction hash of the attestation request
}

StoreProofResponse

interface StoreProofResponse {
    txHash: string;          // Transaction hash
    storageFee: bigint;      // Total fee burned, as a bigint in OS (smallest units)
    broadcastStatus: number; // HTTP status (200 = success)
    broadcastMessage?: string;
}

TransactionDetails (for confirmation callbacks)

interface TransactionDetails {
    transaction: any;      // The signed transaction object
    txHash: string;        // Transaction hash
    amount: bigint;        // Amount being burned, as a bigint in OS (smallest units)
    description: string;   // Human-readable description
    targetUrl?: string;    // For attestation requests
    tokenId?: string;      // For store transactions
}

Native Transaction Types

TLSNotary uses two native transaction types:

tlsn_request

Requests a TLSNotary attestation. Creates an access token for the proxy.

// SDK handles this internally
const tx = await demos.createTransaction({
    type: "native",
    data: ["native", {
        nativeOperation: "tlsn_request",
        args: [targetUrl]
    }]
})

Cost: 1 DEM (burned as fee)

tlsn_store

Stores the proof on-chain after notarization completes.

// SDK handles this internally
const tx = await demos.createTransaction({
    type: "native",
    data: ["native", {
        nativeOperation: "tlsn_store",
        args: [proofId, proofData]
    }]
})

Cost: 1 DEM base + 1 DEM per KB (burned as storage fee)

Cost Structure

Operation	Base Cost	Variable Cost	Notes
`tlsn_request`	1 DEM	-	Initial request fee
`tlsn_store`	1 DEM	+1 DEM/KB	Storage fee based on proof size
Gas	Standard	-	Network transaction gas

Example costs:

Small proof (1KB): 1 + 1 + 1 = 3 DEM + gas
Medium proof (5KB): 1 + 1 + 5 = 7 DEM + gas
Large proof (20KB): 1 + 1 + 20 = 22 DEM + gas

Error Codes

Code	Description	Resolution
`TLSN_INVALID_URL`	URL is not accessible or malformed	Verify URL format and accessibility
`TLSN_TIMEOUT`	Notarization timed out	Retry or check target server
`TLSN_INSUFFICIENT_BALANCE`	Not enough DEM for fees	Top up DEM balance
`TLSN_PROOF_TOO_LARGE`	Proof exceeds maximum size	Reduce response size or use redactions
`TLSN_TOKEN_EXPIRED`	Access token expired	Request will auto-retry
`TLSN_PROXY_UNAVAILABLE`	No proxy available for domain	Wait and retry

TLSNotary Class

The TLSNotary class performs the actual WASM-based attestation. Use it after getting a proxy URL from TLSNotaryService.

import { TLSNotary } from '@kynesyslabs/demosdk/tlsnotary';

const tlsn = new TLSNotary({
    notaryUrl: 'http://notary.example.com:7047',
    websocketProxyUrl: proxyUrl, // From TLSNotaryService
});

await tlsn.initialize(); // Load WASM

const result = await tlsn.attest({
    url: 'https://api.example.com/data',
    method: 'GET',
    headers: { 'Accept': 'application/json' },
});

attest() Signature

attest(
    request: AttestRequest,
    commit?: CommitRanges,
    onStatus?: StatusCallback,
): Promise<AttestResult>

The commit ranges and onStatus callback are passed as separate positional arguments, not as fields of the request object. The request (AttestRequest) fields are:

Parameter	Type	Required	Description
`url`	string	Yes	The target HTTPS URL to attest
`method`	`"GET" \| "POST" \| "PUT" \| "DELETE" \| "PATCH"`	No	HTTP method (default: “GET”)
`headers`	`Record<string, string>`	No	Custom headers to include
`body`	`string \| object`	No	Request body for POST/PUT/PATCH requests
`maxSentData`	number	No	Max sent data in bytes (default: 16384)
`maxRecvData`	number	No	Max receive data in bytes (default: 16384)

attest() Response

interface AttestResult {
    presentation: PresentationJSON;     // The proof data
    verification: VerificationResult;   // Verification result (time, serverName, sent, recv, notaryKey, verifyingKey)
}

verify()

Verify an attestation proof:

const result = await tlsn.verify(presentationJSON);
// result: { time, serverName, sent, recv, notaryKey, verifyingKey }

Wallet Extension Integration

For production dApps, users connect via wallet extensions which handle key management. The SDK supports a 3-step flow for wallet extensions:

The 3-Step Wallet Flow

Generate Transaction: Create the unsigned transaction
Sign & Confirm: Send to wallet extension for user approval and signing
Broadcast: Send the signed transaction to the network

The WithConfirmation methods implement this pattern:

// Example: Full attestation with wallet extension flow
const service = new TLSNotaryService(demos);

// Step 1 & 2: Generate and get user confirmation
const { tlsn, tokenId } = await service.createTLSNotaryWithConfirmation(
    { targetUrl: 'https://api.example.com/data' },
    {
        onConfirm: async (details) => {
            // In a dApp, this would show a modal to the user:
            // "Confirm burning 1 DEM for attestation?"
            // The wallet extension signs when user approves
            return await walletExtension.requestApproval(details.transaction);
        }
    }
);

// Step 3: Perform attestation (no blockchain interaction)
const result = await tlsn.attest({ url: 'https://api.example.com/data' });

// Step 1 & 2 again: Store proof with confirmation
await service.storeProofWithConfirmation(
    tokenId,
    JSON.stringify(result.presentation),
    { storage: 'onchain' },
    {
        onConfirm: async (details) => {
            // "Confirm burning 6 DEM to store proof?"
            return await walletExtension.requestApproval(details.transaction);
        }
    }
);

Custom Headers

const result = await tlsn.attest({
    url: "https://api.example.com/data",
    headers: {
        "Authorization": "Bearer your-token",
        "X-Custom-Header": "value"
    }
});

POST Requests

const result = await tlsn.attest({
    url: "https://api.example.com/submit",
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({ key: "value" })
});

Commit Ranges (Selective Disclosure)

Control which parts of the request/response to include in the proof:

const result = await tlsn.attest(
    { url: "https://api.example.com/data" },
    {
        sent: [{ start: 0, end: 100 }],  // Include first 100 bytes of request
        recv: [{ start: 0, end: 500 }],  // Include first 500 bytes of response
    }
);

The attestQuick() method accepts an AttestOptions object where commit and onStatus are fields:

const result = await tlsn.attestQuick({
    url: "https://api.example.com/data",
    commit: {
        sent: [{ start: 0, end: 100 }],
        recv: [{ start: 0, end: 500 }],
    },
});

Larger commit ranges result in larger proofs, which increase storage costs. Only include the data you need to prove.

​TLSNotary API Reference

​TLSNotaryService Class

​Methods

​requestAttestation()

​requestAttestationWithConfirmation()

​createTLSNotary()

​createTLSNotaryWithConfirmation()

​storeProof()

​storeProofWithConfirmation()

​calculateStorageFee()

​Response Types

​AttestationTokenResponse

​StoreProofResponse

​TransactionDetails (for confirmation callbacks)

​Native Transaction Types

​tlsn_request

​tlsn_store

​Cost Structure

​Error Codes

​TLSNotary Class

​attest() Signature

​attest() Response

​verify()

​Wallet Extension Integration

​The 3-Step Wallet Flow

​Custom Headers

​POST Requests

​Commit Ranges (Selective Disclosure)

TLSNotary API Reference

TLSNotaryService Class

Methods

requestAttestation()

requestAttestationWithConfirmation()

createTLSNotary()

createTLSNotaryWithConfirmation()

storeProof()

storeProofWithConfirmation()

calculateStorageFee()

Response Types

AttestationTokenResponse

StoreProofResponse

TransactionDetails (for confirmation callbacks)

Native Transaction Types

tlsn_request

tlsn_store

Cost Structure

Error Codes

TLSNotary Class

attest() Signature

attest() Response

verify()

Wallet Extension Integration

The 3-Step Wallet Flow

Custom Headers

POST Requests

Commit Ranges (Selective Disclosure)