# zkTLS Twitter/X Example \[Generate a TLSNotary proof for a Twitter/X follower count and submit it to Newton for policy evaluation.]

This guide mirrors the repository tutorial pack for the zkTLS Twitter/X follower-count example. It is intended for developers who want to see how a browser-generated TLSNotary proof becomes a Newton task input.

:::info
The package in this example is `@newton-protocol/zktls-twitter-example`. It is an example SDK/demo surface for the zkTLS Twitter flow, not the production Newton SDK package.
:::

## What you build

The example flow:

1. Opens a browser demo that talks to the TLSNotary extension.
2. Creates an attester WebSocket session through the Newton sidecar.
3. Generates a proof for a Twitter/X follower-count response from `api.x.com`.
4. Stores the proof and receives a CID.
5. Submits a Newton task with `proofCid`, `wasmArgs`, and a transaction `intent`.
6. Evaluates whether the account meets the configured follower threshold.

## Prerequisites

* Node.js 20+
* pnpm 9+
* A Newton API key
* A running Newton gateway and zkTLS attester sidecar
* A TLSNotary-compatible browser extension bridge
* A deployed policy client address for the Twitter/X follower policy

:::info
This example sub-package is `"private": true` in `package.json` and is not published to npm. To use it, clone the SDK repo and build locally. Production integrations should depend on `@newton-xyz/sdk` instead.
:::

## Run the example locally

Clone the SDK repository and build the example workspace:

```bash
git clone https://github.com/newt-foundation/newton-sdk.git
cd newton-sdk/examples/zktls-twitter/sdk
pnpm install
pnpm build
pnpm test

cd ../demo
pnpm install
pnpm build
pnpm dev
```

Configure the demo with environment variables:

```bash
VITE_GATEWAY_URL=http://localhost:8080
VITE_SIDECAR_URL=http://localhost:7047
VITE_NEWTON_API_KEY=your_newton_api_key
VITE_POLICY_CLIENT=0xYourPolicyClient
VITE_INTENT_FROM=0xYourFromAddress
VITE_INTENT_TO=0xYourToAddress
```

SDK requests authenticate with:

```http
Authorization: Bearer your_newton_api_key
```

## Task payload shape

The demo submits a task with a shallow camelCase client shape. The SDK converts top-level gateway params to snake\_case while preserving the nested `intent` object in camelCase because the gateway accepts it.

```typescript
import { createNewtonSDK, encodeWasmArgs } from "@newton-protocol/zktls-twitter-example";

const sdk = createNewtonSDK({
  gatewayUrl: "http://localhost:8080",
  attesterUrl: "http://localhost:7047",
  apiKey: process.env.NEWTON_API_KEY,
});

const result = await sdk.task.createTask({
  policyClient: "0x1111111111111111111111111111111111111111",
  intent: {
    from: "0x2222222222222222222222222222222222222222",
    to: "0x3333333333333333333333333333333333333333",
    value: "0x0",
    data: "0x",
    chainId: "0xaa36a7",
    functionSignature: "0x",
  },
  proofCid: "bafy...",
  wasmArgs: encodeWasmArgs({
    min_followers: 1000,
    twitter_username: "newton_protocol",
  }),
  timeout: 60,
  useTwoPhase: true,
});
```

## Proof retrieval and integrity

The example proof client retrieves proof bytes by CID and verifies that the returned bytes match the CID multihash before returning them to callers. The same verification runs after `store()`: the SDK re-derives the CID locally from the bytes it sent and rejects any gateway response whose CID does not match. This keeps the client boundary stable while proof storage is still IPFS-backed and prevents a malicious or misconfigured gateway from routing downstream `proofCid` submissions to content the client never authored.

Verification rejects unknown multihash algorithms — only sha2-256 (multicodec `0x12`) is accepted. CIDs using other hash functions throw before any byte comparison runs.

The planned backend migration moves proof persistence to gateway-owned Postgres. The public store/retrieve API should remain the handoff point for the demo even when the storage backend changes.

For the full set of client-side invariants (CID integrity, WebSocket lifecycle, bounded body reads, hex caps), see the [SDK Invariants](https://github.com/newt-foundation/newton-sdk/blob/main/docs/zktls-twitter/SDK_INVARIANTS.md) reference.

## Identity integration roadmap

Future iterations should bind this proof flow to Newton identity records:

* Upload encrypted identity data before proof submission.
* Include identity references alongside `proofCid` in policy-specific WASM args.
* Validate identity domain, proof freshness, and task chain ID together in the policy.
* Move address fields to checksum-validated branded address types when the SDK adopts them.

## More resources

* Repository tutorial pack: `docs/zktls-twitter/`
* Example SDK: `examples/zktls-twitter/sdk/`
* Browser demo: `examples/zktls-twitter/demo/`
* Config fixtures: `examples/zktls-twitter/configs/`