Merge coti-sdk-pod docs and upgrade to latest updates

README.md

@@ -12,4 +12,4 @@ Our developer documentation serves as a comprehensive guide to understanding and
 
 * [**Technology Overview**](how-coti-works/): Dive into the technical foundations of the COTI network, including the cryptographic principles and innovative solutions behind its operation.
 * [**Quickstart Guide**](build-on-coti/quickstart.md): Get up and running with the COTI network quickly, using step-by-step instructions and practical examples.
-* [**Developer Tools**](build-on-coti/tools/): Check out the innovative tools and resources to empower developers and organizations.
+* [Privacy on Demand](privacy-on-demand/README.md) — Private computation on COTI with EVM orchestration (PoD)

SUMMARY.md

@@ -129,8 +129,14 @@
   * [Async private operations](privacy-on-demand/async-private-operations.md)
   * [How do PoA fees work?](privacy-on-demand/how-poa-fees-work.md)
   * [For developers: mapping concepts to the SDK](privacy-on-demand/for-developers-mapping-to-the-sdk.md)
+  * [Account onboarding (AES key)](privacy-on-demand/account-onboarding-aes-key.md)
+  * [COTI TypeScript SDK for PoD](privacy-on-demand/coti-typescript-sdk-for-pod.md)
+  * [TypeScript PoD SDK](privacy-on-demand/typescript-pod-sdk.md)
+  * [Reference: data types (it/ct/gt)](privacy-on-demand/reference-data-types.md)
+  * [Reference: PodLib primitives](privacy-on-demand/reference-podlib-and-primitives.md)
+  * [Contract patterns checklist](privacy-on-demand/contract-patterns-checklist.md)
+  * [Reference: examples and contracts](privacy-on-demand/reference-examples-and-contracts.md)
   * [Tutorials: building PoD dApps](privacy-on-demand/tutorials-privacy-on-demand.md)
-  * [TypeScript PoD SDK (CotiPodCrypto, PodContract)](privacy-on-demand/typescript-pod-sdk.md)
   * [Cookbook: private investor allocations with PoD](privacy-on-demand/cookbook-private-investor-allocations.md)
   * [Tutorial: private Adder on Sepolia](privacy-on-demand/tutorial-private-adder-sepolia.md)
   * [Tutorial: custom privacy logic with PoD](privacy-on-demand/tutorial-custom-logic.md)

privacy-on-demand/README.md

@@ -17,24 +17,25 @@ Privacy on Demand lets applications use **strong privacy for data and computatio
 
 <h2 style="font-size: 2.35rem; font-weight: 600; margin-top: 1.75rem; margin-bottom: 1rem; line-height: 1.2;">Further resources</h2>
 
-- **[Examples](https://github.com/cotitech-io/coti-pod-sdk/tree/main/contracts/examples)** — Contract examples in the PoD SDK repo.
-- **[PoD SDK documentation](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs)** — Full SDK docs on GitHub.
-
-The same **Quick Access** and **Further resources** blocks appear on the [docs homepage](../README.md).
+- **[Examples](reference-examples-and-contracts.md)** — Contract examples in `@coti-io/coti-contracts`.
+- **[TypeScript PoD SDK](typescript-pod-sdk.md)** — Full `@coti/pod-sdk` reference.
+- **[coti-sdk-pod on GitHub](https://github.com/coti-io/coti-sdk-pod)** — TypeScript SDK source.
+- **[coti-contracts on GitHub](https://github.com/coti-io/coti-contracts/tree/main/contracts/pod)** — Solidity libraries and examples.
+- **[coti-pod-inbox-contracts on GitHub](https://github.com/coti-io/coti-pod-inbox-contracts)** — Inbox implementation and fee contracts.
 
 </div>
 
 ---
 
-This section explains **what PoD is**, **how it feels to users and operators**, and **how the main pieces fit together**. For step-by-step integration with the **COTI PoD SDK**, use the [npm package](https://www.npmjs.com/package/@coti/pod-sdk), the [documentation on GitHub](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs), and the links below.
+This section is the **canonical user-facing documentation** for PoD. See [Architecture and main components](architecture-and-components.md) for the three-package stack (`@coti/pod-sdk`, `@coti-io/coti-contracts`, `@coti-io/coti-pod-inbox-contracts`).
 
 ## Who this documentation is for
 
 | Audience | What you will get here |
 | --- | --- |
 | **Product, compliance, and business readers** | Plain-language model of privacy, where data lives, and what “async” private operations mean in practice. |
 | **Architects and technical leads** | End-to-end diagrams, component roles, and boundaries between chains and domains. |
-| **Developers** | A clear map from concepts to Solidity/TypeScript work, plus pointers to the authoritative SDK docs. |
+| **Developers** | Tutorials, API reference, checklists, and links to authoritative contract source. |
 
 ## Table of contents
 
@@ -60,8 +61,10 @@ This section explains **what PoD is**, **how it feels to users and operators**,
 12. [Tutorial: private Adder on Sepolia](tutorial-private-adder-sepolia.md) — Minimal primitive-only adder: `PodUserSepolia`, fees, TypeScript crypto.
 13. [Tutorial: custom privacy logic with PoD](tutorial-custom-logic.md) — Encrypted messaging shape: `DirectMessageCotiSide` + Sepolia orchestrator.
 
-## Official technical reference
+## Official code repositories
 
-The machine-readable contracts, types, and APIs live in the open-source SDK. Treat this book chapter as the **human-oriented companion**; treat the repository as the **source of truth** for signatures, fees, and network constants:
+Machine-readable **signatures and constants** live in the repos above. This book is the **documentation source of truth** for integration guidance:
 
-- [COTI PoD SDK — documentation index](https://github.com/cotitech-io/coti-pod-sdk/tree/main/docs)
+- [COTI contracts — PoD contracts](https://github.com/coti-io/coti-contracts/tree/main/contracts/pod)
+- [COTI PoD SDK — TypeScript source](https://github.com/coti-io/coti-sdk-pod)
+- [COTI PoD inbox contracts](https://github.com/coti-io/coti-pod-inbox-contracts)

privacy-on-demand/account-onboarding-aes-key.md

@@ -0,0 +1,66 @@
+# Account onboarding (AES key)
+
+Every PoD user needs an **account AES key** to decrypt `ct*` values returned from private operations. The key is a 16-byte AES secret represented as **32 hexadecimal characters without a `0x` prefix**.
+
+This page describes a practical onboarding flow. Low-level crypto helpers live in [`@coti-io/coti-sdk-typescript`](coti-typescript-sdk-for-pod.md); decryption in app code typically goes through [`CotiPodCrypto`](typescript-pod-sdk.md).
+
+## Trust model
+
+- AES key recovery happens on a **trusted client** (browser, mobile app, or user-controlled wallet extension).
+- A backend may broker encrypted key shares but must **never** see the plaintext AES key.
+- Do not pass the recovered key in URLs, query parameters, or server logs.
+
+## Typical flow
+
+1. Client generates an RSA key pair.
+2. Client sends the RSA **public** key to your onboarding service.
+3. Service returns two encrypted key shares.
+4. Client decrypts and combines shares into the account AES key.
+5. Client stores the key in secure local storage.
+
+## Example implementation
+
+```typescript
+import { generateRSAKeyPair, recoverUserKey } from "@coti-io/coti-sdk-typescript";
+
+type KeySharesResponse = {
+  encryptedKeyShare0: string;
+  encryptedKeyShare1: string;
+};
+
+async function onboardAccount(
+  requestShares: (publicKey: Uint8Array) => Promise<KeySharesResponse>
+): Promise<string> {
+  const { publicKey, privateKey } = generateRSAKeyPair();
+  const { encryptedKeyShare0, encryptedKeyShare1 } = await requestShares(publicKey);
+
+  const accountAesKey = recoverUserKey(privateKey, encryptedKeyShare0, encryptedKeyShare1);
+
+  if (!/^[0-9a-fA-F]{32}$/.test(accountAesKey)) {
+    throw new Error("invalid AES key format");
+  }
+
+  return accountAesKey;
+}
+```
+
+## Storage recommendations
+
+| Environment | Recommendation |
+| --- | --- |
+| Web dApp | Encrypted-at-rest in browser storage with strict origin and session controls |
+| Mobile | OS keychain or secure enclave |
+| Server-rendered apps | Avoid persisting the AES key on the server |
+
+## Operational guardrails
+
+- Never log key shares or the recovered key.
+- Enforce TLS and authenticated onboarding endpoints.
+- Define account recovery and key-rotation policy before production launch.
+- Pair onboarding with [async UX guidance](async-private-operations.md): users cannot decrypt results until onboarding completes.
+
+## See also
+
+- [COTI TypeScript SDK for PoD](coti-typescript-sdk-for-pod.md) — `generateRSAKeyPair`, `recoverUserKey`, decrypt helpers
+- [TypeScript PoD SDK](typescript-pod-sdk.md) — `CotiPodCrypto.decrypt`
+- [Tutorial: private Adder on Sepolia](tutorial-private-adder-sepolia.md) — end-to-end walkthrough that assumes a key is available

privacy-on-demand/architecture-and-components.md

@@ -3,21 +3,29 @@
 ## Vocabulary: PoD versus “Pod” in code
 
 - **PoD** — **Privacy on Demand**, the **product pattern**: private work on COTI, orchestration on your EVM chain.
-- **PodUser / PodLib** — **Solidity building blocks**. They help your **dApp contract** configure routing and call common private operations. They are **not** a separate blockchain; they are **libraries and base contracts** you inherit or use.
+- **PodUser / PodLib** — **Solidity building blocks** in `@coti-io/coti-contracts`. They help your **dApp contract** configure routing and call common private operations. They are **not** a separate blockchain.
+
+## Three repositories
+
+| Package | What it ships |
+| --- | --- |
+| `@coti-io/coti-contracts` | `PodLib`, `PodUser*`, `IInbox` interface, `MpcAbiCodec`, examples, tokens |
+| `@coti-io/coti-pod-inbox-contracts` | Inbox **implementation**, `InboxMiner`, `InboxFeeManager`, `PriceOracle` |
+| `@coti/pod-sdk` | TypeScript client: encrypt/decrypt, fee-aware calls, request tracking |
+
+The Inbox uses a **CREATE3 deterministic address** shared across Sepolia, COTI testnet, and Avalanche Fuji (`0xAb625bE229F603f6BBF964474AFf6d5487e364De` in [`PodNetworkConstants`](https://github.com/coti-io/coti-contracts/blob/main/contracts/pod/PodNetworkConstants.sol)).
 
 ## High-level deployment view
 
 Think of **three domains**:
 
 1. **User device** — keys, encryption, decryption, UX.
-2. **Your EVM chain** — your app’s contracts, assets, and the **Inbox** contract that speaks cross-domain.
-3. **COTI execution** — private computation and the **MPC executor** contract your integration targets.
+2. **Your EVM chain** — your app’s contracts, assets, and the **Inbox** contract.
+3. **COTI execution** — private computation and the **MPC executor** (or custom COTI contract).
 
-**Inbox** sits on **your chain** and is the **trusted bridge** between your contract logic and COTI. **MPC executor** sits on **COTI** and is the **entry point** for the SDK-configured private operation flow.
+**Inbox** sits on **your chain** and is the **trusted bridge** between your contract logic and COTI. A matching Inbox on COTI receives cross-domain messages for the return leg.
 
-## Component diagram: your dApp contract’s perspective
-
-The next diagram shows **logical modules** as engineers wire them. Exact inheritance names come from the SDK (for example `PodUserSepolia` on test networks).
+## Component diagram
 
 ```mermaid
 flowchart TB
@@ -26,10 +34,9 @@ flowchart TB
         PodInboxEvm["Inbox contract (EVM)"]
     end
 
-
-    subgraph CotiSyetem["Privacy Application (EVM)"]
+    subgraph CotiSystem["COTI testnet"]
         PodInboxCoti["Inbox contract (COTI)"]
-        Exec["MPC executor or Custom Executor (COTI)"]
+        Exec["MPC executor or custom contract"]
     end
 
     AppLogic --> PodInboxEvm
@@ -39,45 +46,43 @@ flowchart TB
 
 ### Inbox
 
-- **What it is**: An on-chain **message router** and **callback** mechanism between domains.
-- **Why it matters**: Without it, your EVM contract cannot **reach** COTI private execution or **receive** structured answers.
-- **Analogy**: A **certified courier** between two offices: it does not replace either office, but **only** it can hand off the parcel and bring the signed reply back.
+- **What it is**: On-chain **message router** and **callback** mechanism between domains.
+- **Implementation**: [`coti-pod-inbox-contracts`](https://github.com/coti-io/coti-pod-inbox-contracts); interface in [`IInbox.sol`](https://github.com/coti-io/coti-contracts/blob/main/contracts/pod/IInbox.sol).
+- **Why it matters**: Without it, your EVM contract cannot reach COTI private execution or receive structured answers.
 
 ### MPC executor (COTI)
 
-- **What it is**: The **COTI-side contract address** your dApp is configured to call for a given deployment. The SDK’s network presets expose this as a constant you set during construction (for example `MPC_EXECUTOR_ADDRESS` alongside `COTI_CHAIN_ID` in [Getting started](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/04-getting-started.md)).
-- **Why it matters**: It anchors **where** private execution is invoked in the COTI environment for **library-style** flows.
+- **What it is**: The COTI-side contract your dApp targets for **library-style** flows. Network presets such as [`PodUserSepolia`](https://github.com/coti-io/coti-contracts/blob/main/contracts/pod/mpc/PodUserSepolia.sol) call `configureCoti` in their constructor with the current executor address from `PodNetworkConstants`.
+- **Why it matters**: Anchors where private execution is invoked on COTI.
 
 ### PodUser
 
-- **What it is**: A **configuration surface** for integrators: **which Inbox**, **which COTI chain**, **which executor**. Administrative changes are expected to be **access-controlled** (`onlyOwner` patterns in the SDK).
-- **Why it matters**: Lets the same codebase target **different environments** (testnet vs mainnet, future routing updates) without rewriting core logic—**if** governance is handled responsibly.
+- **What it is**: Configuration surface for **Inbox address**, **COTI chain id**, and **executor address**. Presets (`PodUserSepolia`, `PodUserFuji`) auto-wire testnet values; production changes should be **access-controlled** (`onlyOwner`).
+- **Why it matters**: Same codebase can target different environments without rewriting core logic.
 
 ### PodLib
 
-- **What it is**: **High-level helpers** for **common private operations** (for example comparisons and arithmetic at fixed bit widths—see the SDK [features](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/03-features.md) table).
-- **Why it matters**: Faster path than writing a **custom** COTI contract for every operation. If you outgrow it, you move to **custom** encoding and COTI-side contracts using `MpcAbiCodec`, described in the SDK’s [Writing privacy contracts](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/05-writing-privacy-contracts-on-ethereum.md).
-
-## Data shapes: a non-developer mental model
+- **What it is**: High-level helpers for **common private operations** (arithmetic, comparison, bitwise ops at 64/128/256 bits). See [Reference: PodLib primitives](reference-podlib-and-primitives.md).
+- **Why it matters**: Faster than a custom COTI contract for every operation. When you outgrow it, use `MpcAbiCodec` and custom COTI contracts ([Tutorial: custom privacy logic](tutorial-custom-logic.md)).
 
-Engineers talk about **`it*`**, **`gt*`**, and **`ct*`**. At a high level:
+## Data shapes
 
-| Symbol (in docs) | Think of it as | Where it “lives” |
+| Symbol | Think of it as | Where it lives |
 | --- | --- | --- |
-| **`it*`** | **Signed, encrypted user input** bundled for submission | Built on the **client**, consumed by **your EVM contract** |
-| **`gt*`** | **Private compute representation** during the operation | **Inside COTI** private execution |
-| **`ct*`** | **Encrypted output** you can **store on your chain** and **decrypt client-side** | **Returned** to your contract, **read** by the user’s app |
+| **`it*`** | Signed encrypted user input | Built on **client**, consumed by **EVM contract** |
+| **`gt*`** | Private compute representation | **Inside COTI** execution |
+| **`ct*`** | Encrypted output stored on-chain | **Returned** to your contract, **decrypted** client-side |
 
-A fuller table lives in the SDK’s [data types](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/contracts/01-it-ct-gt-data-types.md) page.
+Full reference: [Reference: data types](reference-data-types.md).
 
-## Trust and security highlights (for architects)
+## Trust and security highlights
 
-- **Callback authentication**: Your contract should only accept **Inbox-originated** callbacks for private results—otherwise anyone could try to spoof answers. The SDK’s `onlyInbox` pattern exists for this boundary ([features](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/03-features.md)).
-- **Request correlation**: Private work completes **later**; your system must track **request IDs** and statuses honestly in UX and backends ([Async private operations](async-private-operations.md)).
-- **Key stewardship**: Client-side AES material is powerful; treat it like **credentials**, not analytics metadata ([TypeScript integration](https://github.com/cotitech-io/coti-pod-sdk/blob/main/docs/06-typescript-integration-ux-development.md)).
+- **Callback authentication**: Only accept **Inbox-originated** callbacks (`onlyInbox` from [`InboxUser.sol`](https://github.com/coti-io/coti-contracts/blob/main/contracts/pod/InboxUser.sol)).
+- **Request correlation**: Track **request IDs** in UX and backends ([Async private operations](async-private-operations.md), [`PodRequest`](typescript-pod-sdk.md)).
+- **Key stewardship**: Account AES keys are credentials ([Account onboarding](account-onboarding-aes-key.md)).
 
 ## Next steps
 
-- **[Interactive PoD architecture (pod.coti.io)](https://pod.coti.io/)** — Explore the same cross-chain picture interactively: step through **MpcAdder**, open linked contracts on GitHub, and see how fees deplete across blocks.
-- [Glossary](glossary.md) — quick term lookup.
-- [For developers: mapping concepts to the SDK](for-developers-mapping-to-the-sdk.md) — concrete doc links and checklists.
+- **[Interactive PoD architecture (pod.coti.io)](https://pod.coti.io/)**
+- [Glossary](glossary.md)
+- [For developers: mapping concepts to the SDK](for-developers-mapping-to-the-sdk.md)