From 19098169522477f0118b4a2947b23cbd6e0fb628 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 20:50:28 +0100 Subject: [PATCH 1/3] CI: Create workflow to deploy to GH Pages The built-in GH Pages deployer only supports deploying from either the repo root, or the `docs/` subdirectory. We want to deploy from the `rendered/` subdirectory. --- .github/workflows/deploy.yml | 42 ++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 .github/workflows/deploy.yml diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 000000000..75b2c1a6a --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,42 @@ +# Simple workflow for deploying static content to GitHub Pages +name: Deploy pre-rendered static content to Pages + +on: + # Runs on pushes targeting the default branch + push: + branches: ["main"] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Single deploy job since we're just deploying + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'rendered' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From 1bcece4f857986ec6280849fa1451b9d8cc02dbb Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 19:52:16 +0000 Subject: [PATCH 2/3] Move `CNAME` into `rendered/` subdir AFAICT the file needs to be in the root of the GH Pages source directory, which is now a subdirectory. --- CNAME => rendered/CNAME | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename CNAME => rendered/CNAME (100%) diff --git a/CNAME b/rendered/CNAME similarity index 100% rename from CNAME rename to rendered/CNAME From 1de446352c9c1fc631f5957ff62e8a22cd107570 Mon Sep 17 00:00:00 2001 From: Jack Grigg Date: Tue, 16 Jul 2024 20:12:58 +0000 Subject: [PATCH 3/3] ZIP 315: Fix rendering issues --- rendered/zip-0315.html | 125 +++++++++++++++++------------------------ zips/zip-0315.rst | 7 ++- 2 files changed, 58 insertions(+), 74 deletions(-) diff --git a/rendered/zip-0315.html b/rendered/zip-0315.html index c373b47c2..9ae30b3d9 100644 --- a/rendered/zip-0315.html +++ b/rendered/zip-0315.html @@ -42,7 +42,7 @@

This ZIP covers best practices for:

  • what information to display to the user about transactions and balances;
    • -
  • how to handle interactions between the ZIP 32 [#zip-0032]_ key tree and Unified Addresses [#zip-0316]_;
    • +
  • how to handle interactions between the ZIP 32 2 key tree and Unified Addresses 4;
  • when to use external or internal keys/addresses;
  • sharing addresses and viewing keys;
  • sending and receiving funds (including fee selection);
    • @@ -74,31 +74,17 @@

    Specification

    Long-term storage of funds

    It is RECOMMENDED that wallets only hold funds as shielded in the long term; that is, if a wallet supports receiving transparent funds (or supports importing a seed from another wallet that might have done so), then it SHOULD auto-shield such funds by default.

    -

    A shielding transaction is always linked to the transparent addresses it spends from. This can cause undesirable information leaks: a) if there are multiple transparent addresses, they will be linked to each

    -
    -

    System Message: ERROR/3 (zips/zip-0315.rst line 136)

    -

    Unexpected indentation.

    -
    -
    -

    other;

    -
    -
    -

    System Message: WARNING/2 (zips/zip-0315.rst line 137)

    -

    Block quote ends without a blank line; unexpected unindent.

    -
    -
      +

      A shielding transaction is always linked to the transparent addresses it spends from. This can cause undesirable information leaks:

      +
        +
      1. if there are multiple transparent addresses, they will be linked to each other;
      2. a link between the input transparent address(es) and the payment will be visible to the recipient(s), or to any other holder of an Incoming Viewing Key for the destination address(es).
      -
      -

      System Message: INFO/1 (zips/zip-0315.rst line 123)

      -

      Enumerated list start value not ordinal-1: "b" (ordinal 2)

      -

      Despite the fact that it is not possible to achieve strong privacy guarantees from any use of transparent addresses, it is undesirable to reveal this additional information. In particular, issue b) motivates ruling out the use of "opportunistic shielding", i.e. shielding previously received transparent funds as part of a user-initiated transaction.

      Wallets SHOULD NOT auto-shield from multiple transparent addresses in the same transaction, and SHOULD NOT use opportunistic shielding.

      Following all of the recommendations in this section improves both collective privacy and the user's individual privacy, by maximizing the size of the note anonymity set over time and minimizing the potential linkage of shielding transactions to other transactions.

      The remainder of this specification assumes a wallet that follows all of these recommendations, except where explicitly noted.

      A wallet MAY allow users to disable auto-shielding, auto-migration, and/or opportunistic migration. If it does so, this need not be via three independent settings.

      -

      Automatic shielding and automatic/opportunistic migration SHOULD NOT be applied to inputs where the cost of shielding or migrating them will exceed their economic value. If these transactions are paying the ZIP 317 conventional fee 3, that will be the case if the amount of the UTXO to be shielded/migrated exceeds the marginal fee, and cannot be accommodated by an input that would be present in any case due to padding of the number of inputs from a given shielded pool.

      +

      Automatic shielding and automatic/opportunistic migration SHOULD NOT be applied to inputs where the cost of shielding or migrating them will exceed their economic value. If these transactions are paying the ZIP 317 conventional fee 5, that will be the case if the amount of the UTXO to be shielded/migrated exceeds the marginal fee, and cannot be accommodated by an input that would be present in any case due to padding of the number of inputs from a given shielded pool.

    Trusted and untrusted TXOs

    A wallet SHOULD treat received TXOs that are outputs of transactions created by the same wallet, as trusted TXOs. Wallets MAY enable users to mark specific external transactions as trusted, allowing their received TXOs also to be classified as trusted TXOs.

    @@ -165,19 +151,10 @@

    System Message: INFO/1 (zips/zip-0315.rst line 123)

    A transaction is incoming if it contains unconfirmed-spendable TXOs. Incoming transactions SHOULD be reported with their number of confirmations and their balances as described in Reporting of balances.

    Sent transactions

    -

    A transaction is sent if it was either: * created by the wallet, or * detected by using the wallet's outgoing viewing keys to decrypt

    -
    -

    System Message: ERROR/3 (zips/zip-0315.rst line 308)

    -

    Unexpected indentation.

    -
    -
    -

    Sapling or Orchard outputs, or

    -
    -
    -

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    -

    Block quote ends without a blank line; unexpected unindent.

    -
    +

    A transaction is sent if it was either:

      +
    • created by the wallet, or
      • +
    • detected by using the wallet's outgoing viewing keys to decrypt Sapling or Orchard outputs, or
    • detected as spending a note that was at some time held by the wallet by recognizing that note's nullifier, or
    • detected as spending a transparent TXO associated with one of the wallet's addresses (including watch-only addresses).
    @@ -246,7 +223,7 @@

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    If multiple UTXOs are received at the same transparent address, it is safe to shield them all in the same transaction, because that is not leaking additional information.

    UTXOs received on different transparent receivers SHOULD NOT be shielded in the same transaction. Ideally, when they are shielded in separate transactions, this should be done in such a way that the timing of those transactions is not linkable.

    TODO: move this. Daira-Emma thinks that if we only document leakage rather than explicitly say in the specification of how to construct transactions how to mitigate it, then implementors will ignore it.

    -

    When spending transparent UTXOs, they SHOULD only be sent to an internal shielded receiver belonging to the wallet, except when they are generated and spent ephemerally as part of a ZIP 320 transfer 4.

    +

    When spending transparent UTXOs, they SHOULD only be sent to an internal shielded receiver belonging to the wallet, except when they are generated and spent ephemerally as part of a ZIP 320 transfer 6.

    A wallet MUST NOT send funds to a transparent address unless all of the source funds come from shielded pools, and this SHOULD be a single shielded pool.

    We want to minimize pool crossing.

    @@ -268,7 +245,7 @@

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    TODO: recommend that when nullifiers are revealed in a transaction that is then invalidated (or revealed in some other detectable way), they SHOULD be used in a note management tx to avoid linking the invalidated tx with some arbitrary future tx. Provided that there are no transparent outputs leaving this wallet's control, the same arities and transparent outputs SHOULD be preserved, which also avoids revealing whether the user changed their mind about whether to send the original semantic transaction.

    Expiration height

    -

    A wallet SHOULD create transactions using the default expiration height of 40 blocks from the current height, as specified in 2.

    +

    A wallet SHOULD create transactions using the default expiration height of 40 blocks from the current height, as specified in 3.

    Open question

    How should wallet developers time transactions to avoid linkability?

    @@ -323,28 +300,29 @@

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    • should there be an auto-migration option from Sapling to Orchard?
    -

    # str4d notes

    -

    If we want to have both automatic and opportunistic shielding, and keep the two indistinguishable, then we can't auto-shield when the transparent balance reaches some threshold (otherwise opportunistic would either never be used, or would be identifiable when it uses the balance below the threshold).

    -

    Instead, a proposition: we define a distribution of "time since last payment to the address" from which we sample the time at which the auto-shielding transaction will be created. This distribution is weighted by the balance in the address, so as more funds accrue, the auto-shielding transaction is more likely to be created.

    -
      -
    • It ensures that all funds will eventually be auto-shielded, while preventing fee-dusting attacks (where dust is sent in order to repeatedly consume fees from the wallet), as the auto-shielding transaction is not directly triggered by payment receipt.
      • -
    • If the user makes a shielding transaction in the meantime, we opportunistically shield, without it being clearly not an auto-shielding transaction.
      • -
    • If a wallet is offline for a long time, then it would likely auto-shield as soon as it finishes syncing. This maybe isn't enough to reveal that the wallet came online, except that it _might_ result in auto-shielding transactions for multiple transparent addresses being created at the same time. So we might want to special-case this?
      • -
    -

    Properties we want from auto-shielding:

    -
      -
    • Auto-shielding transactions MUST NOT shield from multiple transparent receivers in the same transaction. - Doing so would trivially link diversified UAs containing transparent receivers.
      • -
    -

    Properties we want from auto-migration:

    -
      -
    • Receipt of a shielded payment MUST NOT trigger any on-chain behaviour (as that reveals transaction linkability).
      • -
    -

    Both auto-shielding and auto-migration are time-triggered actions, not receipt-triggered actions. An auto-shielding or auto-migration transaction MUST NOT be created as a direct result of a payment being received.

    -

    Both of these are opportunistic: if the user's wallet is making a transaction in which one of these actions would occur anyway, then the wallet takes the opportunity to migrate as much as it would do if it were generating an autoshielding transaction. This both saves on a transaction, and removes the need for any kind of transparent change address within UAs.

    -

    TODO: what pool should change go to?

    -
      -
    • Proposal: the most recent pool already involved in the transaction.
      • -
    +

    str4d notes

    +

    If we want to have both automatic and opportunistic shielding, and keep the two indistinguishable, then we can't auto-shield when the transparent balance reaches some threshold (otherwise opportunistic would either never be used, or would be identifiable when it uses the balance below the threshold).

    +

    Instead, a proposition: we define a distribution of "time since last payment to the address" from which we sample the time at which the auto-shielding transaction will be created. This distribution is weighted by the balance in the address, so as more funds accrue, the auto-shielding transaction is more likely to be created.

    +
      +
    • It ensures that all funds will eventually be auto-shielded, while preventing fee-dusting attacks (where dust is sent in order to repeatedly consume fees from the wallet), as the auto-shielding transaction is not directly triggered by payment receipt.
      • +
    • If the user makes a shielding transaction in the meantime, we opportunistically shield, without it being clearly not an auto-shielding transaction.
      • +
    • If a wallet is offline for a long time, then it would likely auto-shield as soon as it finishes syncing. This maybe isn't enough to reveal that the wallet came online, except that it _might_ result in auto-shielding transactions for multiple transparent addresses being created at the same time. So we might want to special-case this?
      • +
    +

    Properties we want from auto-shielding:

    +
      +
    • Auto-shielding transactions MUST NOT shield from multiple transparent receivers in the same transaction. - Doing so would trivially link diversified UAs containing transparent receivers.
      • +
    +

    Properties we want from auto-migration:

    +
      +
    • Receipt of a shielded payment MUST NOT trigger any on-chain behaviour (as that reveals transaction linkability).
      • +
    +

    Both auto-shielding and auto-migration are time-triggered actions, not receipt-triggered actions. An auto-shielding or auto-migration transaction MUST NOT be created as a direct result of a payment being received.

    +

    Both of these are opportunistic: if the user's wallet is making a transaction in which one of these actions would occur anyway, then the wallet takes the opportunity to migrate as much as it would do if it were generating an autoshielding transaction. This both saves on a transaction, and removes the need for any kind of transparent change address within UAs.

    +

    TODO: what pool should change go to?

    +
      +
    • Proposal: the most recent pool already involved in the transaction.
      • +
    +

    Wallet Recovery

    In the case where we are recovering a wallet from a backed-up mnemonic phrase, and not from a wallet.dat, we don't have enough information to figure out what receiver types the user originally used when deriving each UA under an account. We have a similar issue if someone exports a UFVK, derives an address from it, and has a payment sent to the address: zcashd will detect the payment, but has no way to figure out what address it should display in the UI. A wallet could store this information in the memo field of change outputs, but that adds a bunch of coordination to the problem, and assumes ongoing on-chain state storage.

    @@ -372,18 +350,34 @@

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    - +
    + + + +
    2ZIP 32: Shielded Hierarchical Deterministic Wallets
    + + + +
    3 ZIP 203: Transaction Expiry
    + + + + + + + +
    4ZIP 316: Unified Addresses and Unified Viewing Keys
    - + @@ -391,27 +385,12 @@

    System Message: WARNING/2 (zips/zip-0315.rst line 309)

    35 ZIP 317: Proportional Transfer Fee Mechanism
    - +
    46 ZIP 320: Defining an Address Type to which funds can only be sent from Transparent Addresses
    -
    -

    Docutils System Messages

    -
    -

    System Message: ERROR/3 (zips/zip-0315.rst line 65)

    -

    Too many autonumbered footnote references: only 0 corresponding footnotes available.

    -
    -
    -

    System Message: ERROR/3 (zips/zip-0315.rst line 65) footnote-reference-2

    -

    Unknown target name: "zip-0032".

    -
    -
    -

    System Message: ERROR/3 (zips/zip-0315.rst line 65) footnote-reference-3

    -

    Unknown target name: "zip-0316".

    -
    -
    \ No newline at end of file diff --git a/zips/zip-0315.rst b/zips/zip-0315.rst index c64c7bd6a..519d5d2bc 100644 --- a/zips/zip-0315.rst +++ b/zips/zip-0315.rst @@ -132,6 +132,7 @@ auto-shield such funds by default. A shielding transaction is always linked to the transparent addresses it spends from. This can cause undesirable information leaks: + a) if there are multiple transparent addresses, they will be linked to each other; b) a link between the input transparent address(es) and the payment will be @@ -303,6 +304,7 @@ Sent transactions ''''''''''''''''' A transaction is sent if it was either: + * created by the wallet, or * detected by using the wallet's outgoing viewing keys to decrypt Sapling or Orchard outputs, or @@ -579,7 +581,8 @@ Open questions: * should there be an auto-migration option from Sapling to Orchard? -# str4d notes +str4d notes +''''''''''' If we want to have both automatic and opportunistic shielding, and keep the two indistinguishable, then we can't auto-shield when the transparent balance reaches @@ -691,6 +694,8 @@ References ========== .. [#BCP14] `Information on BCP 14 — "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels" and "RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words" `_ +.. [#zip-0032] `ZIP 32: Shielded Hierarchical Deterministic Wallets `_ .. [#zip-0203] `ZIP 203: Transaction Expiry `_ +.. [#zip-0316] `ZIP 316: Unified Addresses and Unified Viewing Keys `_ .. [#zip-0317] `ZIP 317: Proportional Transfer Fee Mechanism `_ .. [#zip-0320] `ZIP 320: Defining an Address Type to which funds can only be sent from Transparent Addresses `_