> ## 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

> Common use cases for TLSNotary cryptographic attestation

# 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:

```typescript theme={null}
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.
// Commit ranges are passed as the second argument, not inside the request.
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
    {
        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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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.
// Commit ranges are passed as the second argument, not inside the request.
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
    {
        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:

```typescript theme={null}
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

```typescript theme={null}
// 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" },
    { sent: [], recv: [{ start: 0, end: 100 }] }  // Selective disclosure (second arg)
);
// 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:

```solidity theme={null}
// 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

1. **Minimize proof size**: Only request the data you need
2. **Use redactions**: Hide sensitive fields you don't need to prove
3. **Cache results**: TLSNotary proofs are reusable once created
4. **Handle timeouts**: Large responses may take longer to notarize
5. **Check costs**: Estimate storage costs before requesting large proofs