From d3403986e0c24186545449fcd953331a51aca1f6 Mon Sep 17 00:00:00 2001 From: 0xakk0r0kamui <0xakk0r0kamui@users.noreply.github.com> Date: Fri, 28 Nov 2025 09:44:15 +0700 Subject: [PATCH 1/4] Clarifies core privacy concepts and blockchain architecture --- GLOSSARY.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 3d2dd89..54f7eb4 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -2,27 +2,30 @@ ### Core Privacy Concepts -**Commitment**: Hash binding note contents (value, secrets); stored on-chain without revealing contents +**Commitment**: Cryptographic value computed from hidden data (for example, amount and secrets). It lets others later verify that revealed data is consistent, without learning the data from the commitment itself. -**Nullifier**: Unique tag derived from note secret; marks note as spent, prevents double-spending +**Note**: Private record that represents ownership of some value plus the secrets needed to prove it. The note is usually stored off-chain or encrypted; on-chain you only see commitments, nullifiers and proofs. -**Note**: Off-chain record encoding value + secrets; only commitment stored on-chain +**Nullifier**: Unique value derived from a note’s secret and revealed when the note is spent. The system stores used nullifiers to prevent double-spending without exposing which note belonged to which party. -**Stealth Address**: Ephemeral address derived per-transaction to prevent address reuse +**Stealth Address**: is an address generated per transaction so that multiple payments to the same party cannot be easily linked on-chain. The recipient publishes some public information once; senders use it to derive fresh, unlinkable addresses. -**View Key**: Cryptographic key allowing selective decryption of encrypted state without spending authority +**View Key**: is a cryptographic key that allows read-only access to encrypted state, like private balances or notes. It enables controlled visibility for auditors, regulators, or internal control functions. ### Blockchain Architecture -**Data Availability (DA)**: Where transaction/state data is stored for verification and reconstruction +**Data Availability (DA)**: The guarantee that all transaction and state data needed to recompute and verify the system is actually published and retrievable. If DA fails, independent verifiers cannot reliably check state, even if proofs appear valid. -**Sequencer**: L2 operator that orders transactions and produces batches +**Data Availability Layer (DA Layer)**: +A dedicated network or service that publishes and stores the data required for DA (for example, rollup or application data), separate from the main execution chain. + +**Sequencer**: Layer 2 operator that accepts transactions on a L2 network, orders them, and produces blocks or batches that are later finalized on Layer 1 (like Ethereum). **Prover**: Entity that generates validity proofs for L2 state transitions (can see private state) **Relayer**: Third party that submits transactions on behalf of users to hide identity -**Paymaster**: ERC-4337 entity that sponsors gas for UserOperations +**Paymaster**: ERC-4337 entity that defines how gas fees for user operations are paid or sponsored. It allows us to implement controlled gasless flows or internal fee routing. ### L2 Categories From 65489a7473c4d1bb766435412384153869a70002 Mon Sep 17 00:00:00 2001 From: 0xakk0r0kamui <0xakk0r0kamui@users.noreply.github.com> Date: Fri, 28 Nov 2025 10:00:39 +0700 Subject: [PATCH 2/4] Clarifies blockchain architecture --- GLOSSARY.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GLOSSARY.md b/GLOSSARY.md index 54f7eb4..da2dfdf 100644 --- a/GLOSSARY.md +++ b/GLOSSARY.md @@ -21,7 +21,9 @@ A dedicated network or service that publishes and stores the data required for D **Sequencer**: Layer 2 operator that accepts transactions on a L2 network, orders them, and produces blocks or batches that are later finalized on Layer 1 (like Ethereum). -**Prover**: Entity that generates validity proofs for L2 state transitions (can see private state) +**Prover**: Entity that runs a specified computation on given inputs (public and private, like L2 state transistions, private notes,...) and outputs both the result and a cryptographic proof that it was computed correctly. Provers may see plaintext data, so who runs them and how they are operated is an explicit part of the trust and privacy model. + +**Verifier**: Entity (often a smart contract) that checks proofs from provers and decides whether to accept the claimed result (for example, a new state root or settlement outcome). **Relayer**: Third party that submits transactions on behalf of users to hide identity From 2c5dc07df442b7bd63c989944050c8586d269cfe Mon Sep 17 00:00:00 2001 From: 0xakk0r0kamui <0xakk0r0kamui@users.noreply.github.com> Date: Mon, 8 Dec 2025 18:24:13 +0700 Subject: [PATCH 3/4] docs: update ERC-7573 DvP pattern with clearer explanations and operational detail --- patterns/pattern-dvp-erc7573.md | 123 ++++++++++++++++++++------------ 1 file changed, 76 insertions(+), 47 deletions(-) diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index 8e10804..6ac835e 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -3,89 +3,118 @@ title: "Pattern: Atomic DvP via ERC-7573 (cross-network)" status: ready maturity: pilot works-best-when: - - Asset and cash legs live on different networks (L1/L2). + - Asset side and payment side live on different networks (L1/L2 or sidechains). avoid-when: - - You rely on HTLC timeouts or manual reconciliation. + - Both sides already settle on the same network with simple on-chain transfers. dependencies: - - ERC-7573 - - Finality sensing/relayer + - ERC-7573 locking contract (asset side) + - ERC-7573 decryption contract (payment side) + - Stateless decryption oracle on the payment network --- ## Intent -Guarantee **atomic Delivery-versus-Payment** across network using **conditional-upon-transfer decryption/unlock** semantics—**no HTLC brittleness**. +Enable atomic Delivery-versus-Payment (DvP) across two networks using ERC-7573, so that either the asset is delivered and payment is completed, or the asset returns to the seller. +The pattern targets institutions that need cross-network settlement with clear behaviour, auditability, and optional privacy. + +In this pattern: +- **asset side** = the tokenised security or collateral being delivered +- **payment side** = the token used for payment (for example, a stablecoin or tokenised deposit) +- **decryption oracle** = a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim ## Ingredients -- **Standards**: ERC-7573 contracts on both networks -- **Infra**: Minimal relayer; finality detector -- **Off-chain**: Settlement runbooks +- **Standards** + - ERC-7573 locking contract on the asset network + - ERC-7573 decryption contract on the payment network + - Oracle proxy and callback contracts (per ERC-7573) -## Protocol (Standard ERC-7573) +- **Infra** + - Asset network where the security or collateral is issued + - Payment network that holds the payment token + - Stateless decryption oracle implementation (single or multi-operator) -1. Both parties lock assets in ERC-7573 contracts on respective networks -2. Relayer monitors both networks for settlement conditions -3. Cash network finality triggers asset network unlock -4. Either both legs execute or both revert +- **Off-chain** + - Trade negotiation or order system that assigns a shared trade identifier + - A component that creates and distributes two outcome keys per trade (success / failure) and keeps them off-chain + - Monitoring and logging for contracts and oracle -## Privacy Extensions +## Protocol (concise) -Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: +1. **Agree trade off-chain** + Two institutions agree on asset, quantity, payment token, amount, a shared trade identifier `T`, and a latest time to settle or unwind. They record `T` and the terms in their internal systems. -### Privacy-Preserving Coordination Methods +2. **Lock the asset with outcome keys** + For trade `T`, the trade-setup system provides two outcome keys (one meaning “deliver to buyer”, one meaning “return to seller”). + The seller locks the asset in the ERC-7573 locking contract on the asset network under `T`, registering hashed values of these two keys. The keys themselves stay off-chain. -Here are no standard methods but approaches that could be taken. +3. **Register the payment** + On the payment network, the buyer registers `T` and the payment details in the ERC-7573 decryption contract, along with encrypted forms of the same two outcome keys: one to use if the payment succeeds, one if it fails or is cancelled. -**Trusted Relayers:** +4. **Execute payment and call the oracle** + The buyer executes the payment through the decryption contract. The contract checks the payment against the registered details for `T` and then asks the decryption oracle to decrypt the encrypted key that matches the actual outcome (success or failure). + The oracle decrypts and returns that outcome key to the decryption contract. -- Institutional-grade coordination services with confidentiality agreements -- Encrypted settlement coordination without revealing trade details -- Multi-signature controls and audit trails for regulatory compliance +5. **Settle on the asset side** + An authorised party submits the outcome key for `T` to the locking contract on the asset network. The contract verifies it against the registered values and either: + - delivers the locked asset to the buyer (payment succeeded), or + - lets the seller reclaim the asset (payment failed, was cancelled, or never completed in time). -**MPC Relayers:** + If no valid outcome key is submitted before the latest time, the seller uses the reclaim path. -- Decentralized multi-party computation for settlement coordination -- No single party can see complete trade information -- Threshold-based coordination with cryptographic guarantees +## Privacy Extensions -### Privacy Protocol Flow +Standard ERC-7573 provides atomic settlement but no privacy. For institutional use cases requiring confidentiality: -1. Assets locked with encrypted parameters or in privacy domains -2. Privacy-preserving relayers coordinate without seeing trade details -3. Settlement conditions communicated via encrypted messages -4. Final execution maintains confidentiality while ensuring atomicity +- **Multi-operator oracle** + Run the decryption oracle with several independent operators and require a threshold of them to cooperate before an outcome key is released. -## Guarantees +- **Minimal on-chain trade data** + Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. -**Standard ERC-7573:** +- **Private or proof-based payment layer** + Use a network or rollup for the payment side that hides detailed balances but can provide a clear “payment completed / not completed” result for each trade identifier. -- True cross-network atomicity via conditional settlement -- Deterministic failure handling and revert mechanisms -- No HTLC brittleness or timeout risks +These extensions do not change how ERC-7573 contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. -**With Privacy Extensions:** +## Guarantees -- Maintains atomicity while preserving transaction confidentiality -- Privacy-preserving coordination without revealing trade details -- Regulatory compliance through selective disclosure mechanisms +- **Atomic settlement** + For each trade, both asset and payment settle together, or the asset is reclaimed by the seller; one-sided settlement is not an intended state. + +- **Defined failure behaviour** + If the payment fails, is cancelled, no outcome key is released, or the latest time passes, the contracts expose a predictable reclaim path for the seller. + +- **Optional privacy** + With minimal on-chain trade data and a private or proof-based payment layer, observers see that a trade settled or not without seeing full terms, while institutions can still disclose details off-chain when required. ## Trade-offs -- Requires robust finality detection and ops playbooks. -- Cross-network coordination adds complexity. -- Privacy coordination introduces additional trust assumptions or complexity. +- **Oracle governance** + Institutions must agree who runs the oracle, how its keys are managed, and how incidents (downtime, misconfiguration) are handled. -## Example +- **Latency and cost** + Settlement depends on payment finality, oracle processing, and any proof generation, adding delay and cost relative to same-network transfers. -**Standard ERC-7573 DvP:** +- **Integration effort** + Internal systems must handle outcome keys, track trade identifiers, listen to events on both networks, and reconcile them with internal ledgers. + +- **Failure and dispute handling** + Exceptional cases (incorrect parameters, operational errors, regulatory holds) still require documented off-chain procedures. + +## Example -- Bond on Ethereum L1, EURC payment on Polygon -- Public relayer coordinates settlement based on finality detection -- L1 bond transfer triggered by Polygon payment confirmation +- Bank A issues a tokenised bond on Ethereum L1 (asset side). +- Bank B holds EURC stablecoin on an L2 rollup (payment side). +- They agree off-chain on trade id `T`, bond quantity, payment amount, and a latest settlement time. +- Bank A locks the bond in the ERC-7573 locking contract on L1 under `T`. +- Bank B registers `T` and executes the EURC payment via the ERC-7573 decryption contract on the rollup; the oracle releases the success outcome key for `T`. +- That key is submitted to the L1 locking contract, which transfers the bond to Bank B. If the payment had failed or been cancelled, the failure outcome key would have been used instead and Bank A would reclaim the bond. ## See also - [Private Trade Settlement](../approaches/approach-private-trade-settlement.md) +- [Commit and Prove](pattern-commit-and-prove.md) - [MPC Custody](pattern-mpc-custody.md) - [Selective Disclosure](pattern-regulatory-disclosure-keys-proofs.md) - [ERC-7573 spec](https://ercs.ethereum.org/ERCS/erc-7573) From e9ad8bef9db7ae7be5de3ae4fe302a4d25b5d7a9 Mon Sep 17 00:00:00 2001 From: 0xakk0r0kamui <0xakk0r0kamui@users.noreply.github.com> Date: Wed, 10 Dec 2025 01:31:54 +0700 Subject: [PATCH 4/4] docs: reverted term leg and removed sidechain ref --- patterns/pattern-dvp-erc7573.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/patterns/pattern-dvp-erc7573.md b/patterns/pattern-dvp-erc7573.md index 6ac835e..5f67fa5 100644 --- a/patterns/pattern-dvp-erc7573.md +++ b/patterns/pattern-dvp-erc7573.md @@ -3,12 +3,14 @@ title: "Pattern: Atomic DvP via ERC-7573 (cross-network)" status: ready maturity: pilot works-best-when: - - Asset side and payment side live on different networks (L1/L2 or sidechains). + - Asset and cash legs live on different networks (L1/L2). avoid-when: - - Both sides already settle on the same network with simple on-chain transfers. + - Both legs already settle on the same network with simple on-chain transfers. + - You're searching for a production-ready solution (EIP not yet recommended) + - You're searching for a fully trustless solution dependencies: - - ERC-7573 locking contract (asset side) - - ERC-7573 decryption contract (payment side) + - ERC-7573 locking contract (asset leg) + - ERC-7573 decryption contract (payment leg) - Stateless decryption oracle on the payment network --- @@ -18,8 +20,8 @@ Enable atomic Delivery-versus-Payment (DvP) across two networks using ERC-7573, The pattern targets institutions that need cross-network settlement with clear behaviour, auditability, and optional privacy. In this pattern: -- **asset side** = the tokenised security or collateral being delivered -- **payment side** = the token used for payment (for example, a stablecoin or tokenised deposit) +- **asset leg** = the tokenised security or collateral being delivered +- **cash leg** = the token used for payment (for example, a stablecoin or tokenised deposit) - **decryption oracle** = a service on the payment network that, for each trade, decrypts one of two outcome keys based on the actual payment result; the asset contract then uses that key to decide whether to deliver or reclaim ## Ingredients @@ -55,7 +57,7 @@ In this pattern: The buyer executes the payment through the decryption contract. The contract checks the payment against the registered details for `T` and then asks the decryption oracle to decrypt the encrypted key that matches the actual outcome (success or failure). The oracle decrypts and returns that outcome key to the decryption contract. -5. **Settle on the asset side** +5. **Settle on the asset leg** An authorised party submits the outcome key for `T` to the locking contract on the asset network. The contract verifies it against the registered values and either: - delivers the locked asset to the buyer (payment succeeded), or - lets the seller reclaim the asset (payment failed, was cancelled, or never completed in time). @@ -73,14 +75,14 @@ Standard ERC-7573 provides atomic settlement but no privacy. For institutional u Keep full trade terms (price, size, counterparties) in internal systems; on-chain, store only a trade identifier and a short reference that links back to those records. - **Private or proof-based payment layer** - Use a network or rollup for the payment side that hides detailed balances but can provide a clear “payment completed / not completed” result for each trade identifier. + Use a network or rollup for the cash leg that hides detailed balances but can provide a clear “payment completed / not completed” result for each trade identifier. These extensions do not change how ERC-7573 contracts decide outcomes: the asset contract still receives an outcome key and either delivers the asset or allows reclaim. ## Guarantees - **Atomic settlement** - For each trade, both asset and payment settle together, or the asset is reclaimed by the seller; one-sided settlement is not an intended state. + For each trade, both asset and cash legs settle together, or the asset is reclaimed by the seller; one-sided settlement is not an intended state. - **Defined failure behaviour** If the payment fails, is cancelled, no outcome key is released, or the latest time passes, the contracts expose a predictable reclaim path for the seller. @@ -104,8 +106,8 @@ These extensions do not change how ERC-7573 contracts decide outcomes: the asset ## Example -- Bank A issues a tokenised bond on Ethereum L1 (asset side). -- Bank B holds EURC stablecoin on an L2 rollup (payment side). +- Bank A issues a tokenised bond on Ethereum L1 (asset leg). +- Bank B holds EURC stablecoin on an L2 rollup (cash leg). - They agree off-chain on trade id `T`, bond quantity, payment amount, and a latest settlement time. - Bank A locks the bond in the ERC-7573 locking contract on L1 under `T`. - Bank B registers `T` and executes the EURC payment via the ERC-7573 decryption contract on the rollup; the oracle releases the success outcome key for `T`. @@ -117,4 +119,4 @@ These extensions do not change how ERC-7573 contracts decide outcomes: the asset - [Commit and Prove](pattern-commit-and-prove.md) - [MPC Custody](pattern-mpc-custody.md) - [Selective Disclosure](pattern-regulatory-disclosure-keys-proofs.md) -- [ERC-7573 spec](https://ercs.ethereum.org/ERCS/erc-7573) +- [ERC-7573 spec](https://ercs.ethereum.org/ERCS/erc-7573) \ No newline at end of file