feat: invite struct, event, errors and redeem function implemented by exo404 · Pull Request #59 · BreadchainCoop/safety-net

exo404 · 2025-10-09T12:49:06Z

Technical Spec – Safety Net Invite

1. Background

Problem Statement:
Today, when creating a Safety Net (SafetyNet), all members must be declared upfront. This makes progressive onboarding difficult and slows down organizers. The first design with on-chain stored invites exposed them publicly. A later proposal with counters and Merkle roots was too complex for the core use case.

Context / History:

SafetyNets repository
Discussion of on-chain invites → discoverability problem.
Discussion of counters / Merkle roots → overengineered for MVP.

Stakeholders:

Safety Net creators / owners.
Prospective members invited to join.
Bread maintainers.
Frontend / UI developers.

2. Motivation

Goals & Success Stories:

Safety Net owner generates an off-chain signed invite.
Invite is shared as a link or QR code.
Anyone holding the invite can redeem it once to join.
Each invite is single-use via a nonce.
Nothing is exposed on-chain until redemption.

3. Scope and Approaches

Non-Goals:

Technical Functionality	Reasoning for being off scope	Tradeoffs
Multi-use invites	Simpler MVP: one signature = one invite	Cannot share one link with many users
Allowlist / Merkle root	Overkill for current goals	Useful for enterprise, not needed now
Global counter revocation	Not required for MVP	Cannot invalidate all invites at once

Value Proposition:

Technical Functionality	Value	Tradeoffs
EIP-712 signed invites	Private, non-discoverable on-chain	Requires off-chain signing
Nonce (one-time use)	Prevents replay and double use	Storage required per invite

Alternative Approaches:

Approach	Pros	Cons
On-chain stored invites	Easy to track, transparent state	Publicly visible, like open join

Relevant Metrics:

Invite redemption success rate.
Number of invites consumed vs. issued.
Common failure cases (expired, already used, bad signature).

4. Step-by-Step Flow

4.1 Main (“Happy”) Path

Actor: Owner generates a invite using fundId, nonce and signs with EIP-712.
Pre-condition: Safety Net exists and has a defined owner.
System validates:
- Nonce not used.
- Signature matches fund owner.
System persists / computes:
- Marks nonce as used.
- Adds msg.sender as member.
- Emits InviteRedeemed.
Post-condition: Caller becomes a member of the Safety Net.

4.2 Alternate / Error Paths

#	Condition	System Action
A1	Invite already used	`revert Invite used`
A2	Invalid signer	`revert Invalid signer`
A3	User already member	`revert Already member`

5. UML Diagrams

Class Diagram

classDiagram
    class SafetyNet {
        +redeemInvite(Invite inv, bytes sig)
        -usedNonces[fundId][nonce]: bool
        -isMember[fundId][addr]: bool
        -ownerOf[fundId]: address
    }
    class Invite {
        +fundId: uint256
        +nonce: uint256
    }
    SafetyNet o--> Invite : verifies

Sequence Diagram

sequenceDiagram
    participant Owner
    participant User
    participant Safety Net Contract

    Owner->>Owner: Sign Invite {fundId, nonce}
    Owner->>User: Share link (Invite+sig)

    User->>Safety Net Contract: redeemInvite(inv, sig)
    Safety Net Contract->>Safety Net Contract: validate signature, nonce, and that the caller isn't already a member 
    Safety Net Contract->>Safety Net Contract: mark nonce used, add member
    Safety Net Contract-->>User: InviteRedeemed event

State Diagram

stateDiagram
    [*] --> Valid
    Valid --> Used : nonce consumed

5. Edge cases and concessions

Single-use only: each invite works once, then becomes invalid.
No global invalidation: leaked invites remain valid until used or expired.

6. Open Questions

Should fund owners be able to invalidate unused invites (e.g. via counter like @bagelface said) in the MVP?

7. Glossary / References

Invite: EIP-712 signature over (fundId, nonce).
Nonce: Unique value ensuring invite is one-time use.
Deadline: Expiry timestamp for the invite.
Safety Net: Mutual aid group with periodic contributions.

Links:

exo404 · 2025-10-09T12:49:32Z

coverage and linting workflows are outdated

Copilot

Pull Request Overview

This PR implements an invite system for Safety Net contracts, allowing owners to create off-chain signed invites for progressive member onboarding. The implementation uses EIP-712 signatures to maintain privacy while preventing replay attacks through nonces.

Key changes:

Added EIP-712 based invite struct with signature verification
Implemented single-use nonce system to prevent invite reuse
Added comprehensive error handling for invite redemption edge cases

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/interfaces/ISafetyNet.sol	Defines Invite struct, InviteRedeemed event, invite-related errors, and redeemInvite function interface
src/contracts/SafetyNet.sol	Implements EIP-712 signature verification, nonce tracking, and invite redemption logic with proper validations

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/interfaces/ISafetyNet.sol

Copilot · 2025-10-09T12:50:13Z

src/contracts/SafetyNet.sol

+    if (usedNonces[_invite.safetyNetId][_invite.nonce]) revert InviteAlreadyUsed();
+    if (isMember[_invite.safetyNetId][msg.sender]) revert AlreadyMember();
+    if (_safetyNet.members.length >= _safetyNet.maximumMembers) revert SafetyNetFull();
+    if (_invite.redeemer != address(0) && _invite.redeemer != msg.sender) revert NotRedeemer();


The logic assumes that address(0) means 'anyone can redeem', but this behavior is not documented in the struct definition or function comments. Consider adding documentation to clarify that redeemer = address(0) creates an open invite.

Copilot · 2025-10-09T12:50:13Z

src/contracts/SafetyNet.sol

+      )
+    );
+
+    return keccak256(abi.encodePacked('\x19\x01', _domainSeparator, _structHash));


[nitpick] Consider using abi.encode instead of abi.encodePacked for the final hash construction. While this follows EIP-712 specification correctly, abi.encode is generally safer and the gas difference is negligible for this use case.

Suggested change

return keccak256(abi.encodePacked('\x19\x01', _domainSeparator, _structHash));

return keccak256(abi.encode('\x19\x01', _domainSeparator, _structHash));

RonTuretzky · 2025-10-10T03:50:35Z

@exo404 i think we should take the redeemer off scope completely. it was not in the spec, not sure why it was implemented. the whole point of an invite link is to not specify an address, this is the entire pain point we are trying to solve with this feature.

exo404 · 2025-10-10T07:40:50Z

@exo404 i think we should take the redeemer off scope completely. it was not in the spec, not sure why it was implemented. the whole point of an invite link is to not specify an address, this is the entire pain point we are trying to solve with this feature.

Acrually if you write 0x0 address the invite is open. I may read wrong but you and bagel said you wanted option so this is in the spec too. I can change it tho that's not a problem @RonTuretzky @bagelface

RonTuretzky · 2025-10-10T07:42:05Z

@exo404 i think we should take the redeemer off scope completely. it was not in the spec, not sure why it was implemented. the whole point of an invite link is to not specify an address, this is the entire pain point we are trying to solve with this feature.

Acrually if you write 0x0 address the invite is open. I may read wrong but you and bagel said you wanted option so this is in the spec too. I can change it tho that's not a problem

It's not in the UML. I don't think we need it at all. Would prefer to not have it.

exo404 · 2025-10-10T07:44:16Z

@exo404 i think we should take the redeemer off scope completely. it was not in the spec, not sure why it was implemented. the whole point of an invite link is to not specify an address, this is the entire pain point we are trying to solve with this feature.

Acrually if you write 0x0 address the invite is open. I may read wrong but you and bagel said you wanted option so this is in the spec too. I can change it tho that's not a problem

It's not in the UML. I don't think we need it at all. Would prefer to not have it.

I forgot to specify the 0x0 thing you right. I'll change the code and the spec

exo404 · 2025-10-10T17:11:53Z

@exo404 i think we should take the redeemer off scope completely. it was not in the spec, not sure why it was implemented. the whole point of an invite link is to not specify an address, this is the entire pain point we are trying to solve with this feature.

Acrually if you write 0x0 address the invite is open. I may read wrong but you and bagel said you wanted option so this is in the spec too. I can change it tho that's not a problem

It's not in the UML. I don't think we need it at all. Would prefer to not have it.
@RonTuretzky
1716aae

RonTuretzky · 2025-10-11T02:03:30Z

please add something like this and this to this PR. eventually we will need to do a typescript version as well but we can open a seperate issue for this. cc @crystal503

exo404 · 2025-10-13T11:14:30Z

@RonTuretzky working on this now

exo404 · 2025-10-13T18:17:26Z

please add something like this and this to this PR. eventually we will need to do a typescript version as well but we can open a seperate issue for this. cc @crystal503

@RonTuretzky b41de51

RonTuretzky

please add test for the invite validation

RonTuretzky · 2025-10-14T01:57:43Z

script/InviteGenerator.sol

+/// @notice Utility contract that produces Safety Net invite signatures matching the on-chain verification logic
+contract InviteGenerator is Script {
+  /// @notice Invite signing domain name used for EIP-712 signatures
+  string private constant INVITE_SIGNING_DOMAIN = 'SafetyNetInvite';


getting warnings on the next 3 variables they should start with _

RonTuretzky · 2025-10-14T23:07:23Z

script/README_INVITES.md

add to the README instead of introducing another file

please have some discretion, this file seems very long

exo404 · 2025-10-15T13:47:14Z

please add test for the invite validation
@RonTuretzky
4335d72

exo404 · 2025-10-15T15:27:44Z

@RonTuretzky done with testing, both for SafetyNet redeemInvite function and InviteGenerator contract

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot · 2025-10-16T08:49:01Z

script/InviteGenerator.sol

+  }
+
+  /// @notice Computes the full EIP-712 digest for a struct invite
+  function inviteDigest(


Use abi.encodePacked instead of abi.encode on line 70 for the EIP-712 digest. According to EIP-712 specification, the final digest should use encodePacked for the \x19\x01 prefix concatenation.

Copilot · 2025-10-16T08:49:01Z

test/unit/InviteGeneratorUnit.t.sol

+  function test_shouldReturnsInviteDigest() public {
+    bytes32 structHash = inviteGenerator.hashInvite(STRUCT_ID, NONCE);
+    bytes32 domainSeparator = inviteGenerator.domainSeparator(CHAIN_ID, VERIFYING_CONTRACT);
+    bytes32 expectedDigest = keccak256(abi.encode('\x19\x01', domainSeparator, structHash));


Use abi.encodePacked instead of abi.encode for the EIP-712 digest in the test expectation to match the EIP-712 specification.

Suggested change

bytes32 expectedDigest = keccak256(abi.encode('\x19\x01', domainSeparator, structHash));

bytes32 expectedDigest = keccak256(abi.encodePacked('\x19\x01', domainSeparator, structHash));

RonTuretzky

here is a refrerene for a cfrontend compoenent that is compatible with a less rigorus implementation , please adjust to work with this implementation , test locally , it is enough just to document a correct typescript/javacript snippet that works with this solidity code

RonTuretzky · 2025-10-17T15:46:17Z

script/InviteGenerator.sol

+/// @notice Utility contract that produces EIP712 invite signatures matching the on-chain verification logic
+contract InviteGenerator is Script {
+  /// @notice Invite signing domain name used for EIP-712 signatures
+  string private _inviteSigningDomain;


drop in favor of a comment on the hasehd version

RonTuretzky · 2025-10-17T15:46:32Z

script/InviteGenerator.sol

+  string private _inviteSigningDomain;
+
+  /// @notice Invite signing version used for EIP-712 signatures
+  string private _inviteSignatureVersion;


drop string in favor of comment next to hashed version

update from dev

exo404 · 2025-10-19T17:58:48Z

@RonTuretzky all test pass, I'm merging this to start to work on the frontend component locally

feat: invite struct, event, errors and redeem functoon implemented

4c00d32

exo404 requested review from RonTuretzky, bagelface and Copilot October 9, 2025 12:49

exo404 self-assigned this Oct 9, 2025

exo404 added the enhancement New feature or request label Oct 9, 2025

exo404 linked an issue Oct 9, 2025 that may be closed by this pull request

Refactor: Enable Breadfund Creation Without Specifying All Users #42

Closed

Copilot AI reviewed Oct 9, 2025

View reviewed changes

exo404 added 2 commits October 9, 2025 14:55

fix: change encodePacked to encode

83e57e7

fix: natspec clarifing the redeemer address field

e5f1229

fix: delete redeemer

1716aae

feat: invite generator script

b41de51

RonTuretzky requested changes Oct 14, 2025

View reviewed changes

fix: private constant names

52b8a9b

RonTuretzky reviewed Oct 14, 2025

View reviewed changes

exo404 added 2 commits October 15, 2025 15:45

refactor: making the contract reusable for other structs

b15d749

test: add unit testing for InviteGenerator

4335d72

exo404 added 3 commits October 15, 2025 16:02

test: function headers for redeemInvite testing

8723813

fix: hash after refactoring

f3b165b

test: add unit testing for invite function

87467f3

RonTuretzky requested a review from Copilot October 16, 2025 08:48

Copilot AI reviewed Oct 16, 2025

View reviewed changes

RonTuretzky requested changes Oct 17, 2025

View reviewed changes

RonTuretzky and others added 4 commits October 18, 2025 00:52

Merge pull request #64 from BreadchainCoop/dev

740bceb

update from dev

fix: change encode with encodePacked

d73c226

fix: linting errors, drop useless constants

5eb2386

fix: delete assembly code from testing

c4179b6

exo404 mentioned this pull request Oct 19, 2025

Frontend component for invite generation #66

Open

exo404 merged commit 914f714 into dev Oct 19, 2025
5 checks passed

	return keccak256(abi.encodePacked('\x19\x01', _domainSeparator, _structHash));
	return keccak256(abi.encode('\x19\x01', _domainSeparator, _structHash));

	bytes32 expectedDigest = keccak256(abi.encode('\x19\x01', domainSeparator, structHash));
	bytes32 expectedDigest = keccak256(abi.encodePacked('\x19\x01', domainSeparator, structHash));

Conversation

exo404 commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Technical Spec – Safety Net Invite

1. Background

2. Motivation

3. Scope and Approaches

4. Step-by-Step Flow

4.1 Main (“Happy”) Path

4.2 Alternate / Error Paths

5. UML Diagrams

Class Diagram

Sequence Diagram

State Diagram

5. Edge cases and concessions

6. Open Questions

7. Glossary / References

Uh oh!

exo404 commented Oct 9, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 9, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RonTuretzky commented Oct 10, 2025

Uh oh!

exo404 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RonTuretzky commented Oct 10, 2025

Uh oh!

exo404 commented Oct 10, 2025

Uh oh!

exo404 commented Oct 10, 2025

Uh oh!

RonTuretzky commented Oct 11, 2025

Uh oh!

exo404 commented Oct 13, 2025

Uh oh!

exo404 commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

RonTuretzky left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

exo404 commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

exo404 commented Oct 15, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 16, 2025

exo404 commented Oct 9, 2025 •

edited

Loading

exo404 commented Oct 10, 2025 •

edited

Loading

exo404 commented Oct 13, 2025 •

edited

Loading

exo404 commented Oct 15, 2025 •

edited

Loading