Documentation Index
Fetch the complete documentation index at: https://docs.kynesys.xyz/llms.txt
Use this file to discover all available pages before exploring further.
TLSNotary Use Cases
TLSNotary enables powerful use cases where you need to prove web content without revealing everything. Here are common scenarios:
Financial Data Attestation
Prove your account balance or financial status without revealing sensitive details:
import { TLSNotaryService } from '@kynesyslabs/demosdk/tlsnotary';
const service = new TLSNotaryService(demos);
// Request token and get TLSNotary instance
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.bank.com/v1/accounts/balance"
});
// Perform attestation with selective disclosure
const result = await tlsn.attest({
url: "https://api.bank.com/v1/accounts/balance",
headers: {
"Authorization": `Bearer ${bankToken}`
},
// Only include the balance portion in the proof
commit: {
sent: [{ start: 0, end: 100 }],
recv: [{ start: 0, end: 200 }] // Just the balance field
}
});
// Store proof on-chain
await service.storeProof(tokenId, JSON.stringify(result.presentation), { storage: 'onchain' });
// The proof shows: { balance: 15000.00, currency: "USD" }
// Hidden: Account number, routing number, transaction details
Real-world applications:
- Proof of funds for loan applications
- Balance verification for rental applications
- Asset attestation for DeFi protocols
Identity Verification
Prove account ownership on web services without sharing credentials:
const service = new TLSNotaryService(demos);
// Request attestation token and TLSNotary instance
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.twitter.com/2/users/me"
});
// Perform attestation
const result = await tlsn.attest({
url: "https://api.twitter.com/2/users/me",
headers: {
"Authorization": `Bearer ${twitterToken}`
}
});
// Proves: You control @username with id 123456
// Verifiable: Anyone can verify the proof
Real-world applications:
- Social media verification for Web3 profiles
- Sybil resistance in DAOs
- Cross-platform identity bridging
API Response Attestation
Create verifiable proofs of API responses for smart contracts or off-chain verification:
const service = new TLSNotaryService(demos);
// Request token
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd"
});
// Attest cryptocurrency price at a specific moment
const result = await tlsn.attest({
url: "https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd"
});
// Proves: BTC = $67,543.21 at timestamp 1704067200
// Use: Oracle data, price verification, historical proof
Real-world applications:
- Decentralized oracle data
- Price feed verification
- Market data attestation
Employment & Income Verification
Prove employment status or income without revealing full details:
const service = new TLSNotaryService(demos);
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.hr-platform.com/v1/employee/status"
});
// Prove employment at a company
const result = await tlsn.attest({
url: "https://api.hr-platform.com/v1/employee/status",
headers: {
"Authorization": `Bearer ${employeeToken}`
},
// Only commit the employment status portion, not salary or SSN
commit: {
sent: [{ start: 0, end: 100 }],
recv: [{ start: 0, end: 150 }] // Just employment status fields
}
});
// Proves: Employed at Company X, Role: Engineer, Since: 2022
// Hidden: Salary, SSN, performance data
Gaming & Achievement Verification
Prove gaming achievements or statistics:
const service = new TLSNotaryService(demos);
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v1"
});
// Prove Steam achievements
const result = await tlsn.attest({
url: "https://api.steampowered.com/ISteamUserStats/GetPlayerAchievements/v1",
headers: { "key": steamApiKey }
});
// Proves: Player has achievement X in game Y
// Use: NFT minting, tournament eligibility, rewards
Comparison: When to Use What
// DAHR - Fast, for general use, non-sensitive data
const dahrResult = await dahr.startProxy({
url: "https://api.example.com/public-data",
method: "GET"
});
// Speed: ~500ms
// On-chain: Hash of response
// Privacy: Full response visible to proxy
// Cost: Gas only
// TLSNotary - Cryptographic proof, sensitive data
const service = new TLSNotaryService(demos);
const { tlsn, tokenId } = await service.createTLSNotary({
targetUrl: "https://api.example.com/private-data"
});
const result = await tlsn.attest({
url: "https://api.example.com/private-data",
commit: { recv: [{ start: 0, end: 100 }] } // Selective disclosure
});
// Speed: 2-5s
// On-chain: Proof metadata only
// Privacy: Selective disclosure via commit ranges
// Cost: 1+ DEM + gas
Decision Matrix
| Scenario | Recommended | Reason |
|---|
| Public API data | DAHR | Speed, lower cost |
| Price feeds | DAHR | Frequent updates, speed |
| Bank account proof | TLSNotary | Confidential data |
| Identity verification | TLSNotary | Selective disclosure |
| Gaming stats | Either | Depends on sensitivity |
| OAuth token exchange | DAHR | Speed critical |
| Proof of reserves | TLSNotary | Cryptographic verification |
Integration with Smart Contracts
TLSNotary proofs can be verified on-chain:
// Example Solidity interface (conceptual)
interface ITlsnVerifier {
function verifyProof(
bytes calldata proof,
bytes32 expectedHash
) external view returns (bool);
function extractClaim(
bytes calldata proof,
string calldata jsonPath
) external view returns (bytes memory);
}
// Usage in contract
function claimReward(bytes calldata tlsnProof) external {
require(
verifier.verifyProof(tlsnProof, expectedProofHash),
"Invalid proof"
);
bytes memory balance = verifier.extractClaim(
tlsnProof,
"$.balance"
);
// Process based on verified balance
}
Best Practices
- Minimize proof size: Only request the data you need
- Use redactions: Hide sensitive fields you don’t need to prove
- Cache results: TLSNotary proofs are reusable once created
- Handle timeouts: Large responses may take longer to notarize
- Check costs: Estimate storage costs before requesting large proofs