Add envelopes technical specification and integration guide#114
Open
Douglasacost wants to merge 1 commit intomainfrom
Open
Add envelopes technical specification and integration guide#114Douglasacost wants to merge 1 commit intomainfrom
Douglasacost wants to merge 1 commit intomainfrom
Conversation
…n guide Specifies a bearer-link asset transfer system: a sender wraps assets in an on-chain envelope, gets a shareable URL containing a fresh ECDSA private key in the URL fragment, and anyone holding the URL can claim the contents through the app. Front-run-safe by construction — claim signature commits to the claimer's address, so a third party who observes a claim transaction cannot hijack it. Architecture: one BaseEnvelope abstract + four concrete contracts (EthEnvelope, Erc20Envelope, Erc721Envelope, Erc1155Envelope), each multi-tenant and immutable. Sender chooses single-claim or multi-claim per envelope; equal-share slots; on-chain dedup by claimer address. Optional expiration with sender reclaim post-expiry. Configurable flat per-envelope fee in ETH (default 0). Permissionless creation; no operator role. Two documents under src/envelopes/doc/: - spec/envelopes-specification.md — full technical specification (architecture, roles, interfaces, flows, storage, security model, testing strategy, deployment & ops, file layout, deferred items). - integration-guide.md — operational runbook mirroring src/swarms/doc/upgradeable-contracts.md: TypeScript/ethers.js v6 examples for sender create flows across all four asset classes, URL parsing and EIP-712 claim signing, recipient claim and reclaim flows, admin operations (setFee, setTreasury, pause/ unpause, role rotation), bug-fix rollout (replace, don't upgrade) with pre-replace and post-replace checklists, monitoring (events to index, cast event-streaming, health signals), and security considerations covering the bearer model's limits, front-run safety, reentrancy, and pause semantics. Operational sections describe the actual zkSync flow: deployment via a Forge script + ops/ shell wrapper mirroring the swarms pattern, source-code verification via ops/verify_zksync_contracts.py. Adds Linkdrop, keypair, typedata, autonumber, dedup, exfiltrated, and runbook to the project cspell ignoreWords list.
There was a problem hiding this comment.
Pull request overview
Adds documentation for the Envelopes bearer-link transfer feature and updates spell-check configuration to accept new domain terminology, so the docs can land without cspell noise.
Changes:
- Added Envelopes technical specification (
src/envelopes/doc/spec/envelopes-specification.md). - Added Envelopes integration & operations guide (
src/envelopes/doc/integration-guide.md) plus a doc index README. - Updated
.cspell.jsonto ignore new Envelopes-related terms.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
src/envelopes/doc/spec/envelopes-specification.md |
Adds the technical specification (architecture, interfaces, flows, security, ops). |
src/envelopes/doc/integration-guide.md |
Adds an integration/runbook guide with deployment, app, sender, and admin workflows. |
src/envelopes/doc/README.md |
Adds a short documentation index linking to spec and integration guide. |
.cspell.json |
Extends ignoreWords for new Envelopes terminology to reduce spellcheck false positives. |
| if (parts.length !== 3 || parts[0] !== "envelope") { | ||
| throw new Error("malformed envelope URL"); | ||
| } | ||
| const asset = parts[1] as Parsed["asset"]; |
Comment on lines
+882
to
+916
| ## 10. File Layout | ||
|
|
||
| ``` | ||
| src/envelopes/ | ||
| BaseEnvelope.sol | ||
| EthEnvelope.sol | ||
| Erc20Envelope.sol | ||
| Erc721Envelope.sol | ||
| Erc1155Envelope.sol | ||
| interfaces/ | ||
| IBaseEnvelope.sol | ||
| IEthEnvelope.sol | ||
| IErc20Envelope.sol | ||
| IErc721Envelope.sol | ||
| IErc1155Envelope.sol | ||
| EnvelopeTypes.sol | ||
| doc/ | ||
| README.md | ||
| spec/ | ||
| envelopes-specification.md | ||
| test/envelopes/ | ||
| BaseEnvelopeShared.t.sol | ||
| EthEnvelope.t.sol | ||
| Erc20Envelope.t.sol | ||
| Erc721Envelope.t.sol | ||
| Erc1155Envelope.t.sol | ||
| Envelopes.integration.t.sol | ||
| mocks/ | ||
| MockEnvelope.sol (minimal subclass for shared tests) | ||
| MockReentrantClaimer.sol (test helper for reentrancy) | ||
| script/ | ||
| DeployEnvelopesZkSync.s.sol | ||
| ops/ | ||
| deploy_envelopes_zksync.sh (mirrors deploy_swarm_contracts_zksync.sh) | ||
| ``` |
Comment on lines
+1
to
+10
| # Envelopes — Documentation | ||
|
|
||
| Bearer-link asset transfer: a sender wraps ETH, ERC-20, ERC-721, or ERC-1155 assets in an on-chain envelope, gets a shareable URL, and anyone holding the URL can claim the contents through the app. Front-run-safe by construction (claim signature commits to the claimer's address). | ||
|
|
||
| ## Contents | ||
|
|
||
| | Document | Description | | ||
| | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | ||
| | [spec/envelopes-specification.md](spec/envelopes-specification.md) | Full technical specification (architecture, roles, interfaces, flows, storage, security, testing, ops) | | ||
| | [integration-guide.md](integration-guide.md) | Operational runbook — TypeScript/ethers.js integration, Cast CLI, sender + app + recipient flows, admin operations, bug-fix rollout | |
Comment on lines
+81
to
+92
| Use the orchestration script (mirrors `ops/deploy_swarm_contracts_zksync.sh`): | ||
|
|
||
| ```bash | ||
| # Testnet (dry run) | ||
| ./ops/deploy_envelopes_zksync.sh testnet | ||
|
|
||
| # Testnet (broadcast) | ||
| ./ops/deploy_envelopes_zksync.sh testnet --broadcast | ||
|
|
||
| # Mainnet (broadcast) | ||
| ./ops/deploy_envelopes_zksync.sh mainnet --broadcast | ||
| ``` |
Comment on lines
+104
to
+111
| The script: | ||
|
|
||
| 1. Compiles with `forge build --zksync`. | ||
| 2. Calls `script/DeployEnvelopesZkSync.s.sol`, which deploys all four contracts in any order (no inter-contract dependencies). | ||
| 3. Sanity-checks each deployment via `cast` (admin role, pauser role, treasury, fee). | ||
| 4. Verifies source code on the zkSync block explorer via `python3 ops/verify_zksync_contracts.py` (see [Repo Convention on zkSync Verification](#repo-convention-on-zksync-verification)). | ||
| 5. Appends addresses to the env file. | ||
|
|
Comment on lines
+330
to
+336
|
|
||
| # Create a single-claim ETH envelope (1 ETH, no expiry) | ||
| ENVELOPE_ID=0xbeef... | ||
| SLOT_AMOUNT=1000000000000000000 # 1 ETH in wei | ||
| SLOTS=1 | ||
| EXPIRES=0 | ||
| TOTAL_VALUE=$(cast --to-dec $(echo "$FEE + $SLOT_AMOUNT * $SLOTS" | bc)) |
LCOV of commit
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request primarily introduces documentation for the Envelopes feature and updates the project's spell-check configuration to include relevant new terminology. The documentation provides an overview of bearer-link asset transfer and references detailed technical and integration guides.
Documentation additions:
README.mdinsrc/envelopes/doc/that describes the Envelopes feature, its security properties, and links to the technical specification and integration guide.Project configuration updates:
.cspell.jsonto include new terms related to Envelopes (e.g., "autonumber", "dedup", "Linkdrop", "keypair", "typedata", "exfiltrated", "runbook") to avoid false positives in spell-checking.This pull request adds new documentation for the Envelopes feature and updates the spell-check configuration to recognize several new domain-specific terms.
Documentation:
README.mdinsrc/envelopes/docthat provides an overview of the Envelopes bearer-link asset transfer system, including a contents table linking to the technical specification and integration guide.Developer tooling:
.cspell.jsonto include new terms such asautonumber,dedup,Linkdrop,keypair,typedata,exfiltrated, andrunbookto reduce false positives in spell checking.