diff --git a/docs/pages/privacy-pools/ppoi.mdx b/docs/pages/privacy-pools/ppoi.mdx index 0ba8a343c..9631215a6 100644 --- a/docs/pages/privacy-pools/ppoi.mdx +++ b/docs/pages/privacy-pools/ppoi.mdx @@ -1,5 +1,14 @@ -# Private Proof of Innocence +# Private Proofs of Innocence :::info -TODO +Privacy Pools does not describe this compliance flow through Railgun's PPOI terminology. +In the official Privacy Pools docs, the equivalent model is described through the Association Set Provider (ASP), approved labels, private withdrawal eligibility, and `ragequit`. + +In the current Kohaku package: + +- balances are surfaced as an approved entry plus a `pending` entry for unapproved deposits +- private withdrawals depend on approved deposits +- unapproved deposits can be exited with `ragequit` + +For the canonical protocol model, see the [Privacy Pools overview](https://docs.privacypools.com/) and the [ASP Layer documentation](https://docs.privacypools.com/layers/asp). ::: diff --git a/docs/pages/railgun/ppoi.mdx b/docs/pages/railgun/ppoi.mdx index 4285bb17d..52fca703e 100644 --- a/docs/pages/railgun/ppoi.mdx +++ b/docs/pages/railgun/ppoi.mdx @@ -1,7 +1,32 @@ -# Private Proof of Innocence +# Private Proofs of Innocence -:::info -TODO -::: +Private Proofs of Innocence (PPOI) is Railgun's zero-knowledge assurance system. +It sits alongside the Railgun smart contracts and uses public on-chain data plus zero-knowledge proofs to show that shielded funds are not part of a configured list of known malicious activity, without exposing a user's 0zk address, balances, or private transaction history. +Within Kohaku, PPOI affects the lifecycle that starts in [Shielding](/railgun/shielding), continues through [Transacting](/railgun/txs), and matters again when [Unshielding](/railgun/unshielding) funds back to an EOA. -For more information see [Railgun documentation](https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence). +## What PPOI changes for users + +- PPOI begins at the shield step. The assurance proof is anchored to the funds entering Railgun, rather than being generated only when a user later unshields. +- Freshly shielded funds may remain pending PPOI validation before they are ready for normal private transfers and unshields. In the current Kohaku plugin, the underlying Railgun provider tracks each balance's `poiStatus`, and Kohaku only selects spendable balances for those flows. +- Once funds have a valid PPOI proof, that assurance can be carried forward through later private transfers inside Railgun. Recipients inherit the assurance on the funds without learning the sender's private history. +- When funds eventually leave Railgun, recipients or exchanges can verify that the tokens have valid PPOI coverage without gaining visibility into the user's private balance graph. + +## What Kohaku exposes today + +Kohaku currently exposes PPOI through balance availability and transaction preparation behavior rather than through a dedicated PPOI management flow. + +- The current Kohaku implementation uses `poiStatus` internally to filter spendable ERC20 balances, aggregating only positive `Valid` balances by asset. +- When Kohaku prepares private transfers and unshields, it skips balances with a defined non-`Valid` POI status. +- Broadcasting is handled through the selected Waku broadcaster; PPOI affects whether the private operation can be prepared by controlling which notes are spendable. +- Kohaku currently uses a fixed PPOI configuration rather than exposing PPOI settings in its higher-level flow. +- Kohaku does not currently expose PPOI list or POI node selection controls in its higher-level flow. + +## Canonical references + +These links are protocol and integration references for background on PPOI. They are the right place to look for richer POI state categories, list and provider setup, and operational PPOI controls that are not exposed in the current Kohaku implementation. + +- [Railgun wiki: Private Proofs of Innocence](https://docs.railgun.org/wiki/assurance/private-proofs-of-innocence) +- [Railgun wiki: RAILGUN Assurance Suite](https://docs.railgun.org/wiki/assurance/railgun-assurance-suite) +- [Railgun developer guide: Balance and Sync Callbacks](https://docs.railgun.org/developer-guide/wallet/private-balances/balance-and-sync-callbacks) +- [Railgun developer guide: Start the RAILGUN Privacy Engine](https://docs.railgun.org/developer-guide/wallet/getting-started/5.-start-the-railgun-privacy-engine) +- [ppoi.info](https://ppoi.info) diff --git a/docs/vocs.config.ts b/docs/vocs.config.ts index 589326464..ee4df89b8 100644 --- a/docs/vocs.config.ts +++ b/docs/vocs.config.ts @@ -66,7 +66,7 @@ export default defineConfig({ ] }, { - text: 'Proof of Innocence', + text: 'Private Proofs of Innocence', link: '/railgun/ppoi' } ] @@ -97,7 +97,7 @@ export default defineConfig({ disabled: true, }, { - text: 'Proof of Innocence', + text: 'Private Proofs of Innocence', link: '/privacy-pools/ppoi', disabled: true, }