Standard for On-Chain AgreementDetails

[Robert-MacWha]

Overview

Currently, the Safe Harbour Registry contains key information on all submitted agreements for protocols. Several of the fields (scope, contactDetails, bountyTerms) are just strings, meaning that different protocols will likely store information inconsistently. Creating an optional standard that agreements should abide to would standardize applications reading from / writing to the smart contract.

I'm personally working on a database & website frontend to record what protocols have signed onto this agreement. Standardizing the information would lead to cleaner UX, greater standardization, and less room for confusion.

Below is a proposed standard for the agreements, which should act as a good starting point.

Agreement Variables

Ideally, the smart contracts should include all vital information from EXHIBIT F ADOPTION FORM in the Safe Harbour Agreement. To my knowledge, these are all the options a protocol can change within the agreement.

Of these below options, the Technical Assets and Bounty Percentage could be standardized on-chain, as well as standardizing the protocol's contact information.

1. Technical Assets – [Plain Text - Non-Hierarchical List of Technical Assets in Scope]
2. Asset Recovery Address – [Plain Text – Blockchain Wallet Address]
3. Third-Party Program Administrator – [Plain Text – N/A; Name of Program Administrator]
4. Diligence Requirements – [Plain Text – Describe Diligence Process] 
5. Whitehat Identity Requirements – [Options – “Anonymous,” “Pseudonymous,” or “Named)]
6. Bounty Percentage – YY% of all Returnable Assets Attributable to Eligible Whitehat’s Blockchain Address]
7. Other Amendments or Modifications – [Plain Text – Describe other Amendments or Modifications; “See Adopting Addendum”]

Standard Agreement Format

struct AgreementDetails {
	// The name of the protocol adopting the agreement.
	string protocolName;
	// The assets in scope of the agreement.
	string scope;
	// The contact details (required for pre-notifying).
	string contactDetails;
	// The bounty terms (e.g. percentage bounty, cap, if payable immediately).
	string bountyTerms;
	// Address where recovered funds should be sent.
	address assetRecoveryAddress;
	// IPFS hash of the actual agreement document, which confirms all terms.
	string agreementURI;
}

scope

Technical Assets

{
	// Smart contract addresses that are directly within scope.  These represent 
	// contracts deployed and owned by the protocol.
	// 
	// For example, the vault smart contract for a lending / borrowing protocol.
	"contractAddresses": [
		{
			"address": "0x1234",
			"chains": [1, 10, 137],
		},
	],
	// Addresses, for which, all deployed smart contracts are within scope.
	// 
	// For example, a smart contract factory used to deploy multiple contracts
	// from a single address.
	"deployerAddresses": [
		{
			"deployer": "0x5678",
                        "chains": [1, 10, 137],
			// Whether contracts deployed by the deployer address *after* this agreement
			// was adopted are included in scope.
			"includeNewContracts": {options: true, false}
		}
	],
	
	// Additional information regarding the scope that is not covered by the above 
	// fields.
	"additionalInfo": "Plain Text",
}

contactDetails

{
	// Primary contact information for the protocol, comprising of a name and 
	// email address.
	"name": "",
	"email": "",
	
	// Secondary contact information. This may direct to other people (IE CTO, CSO),
	// to third-party program administrator, or to another method of contacting the
	// protocol (website form, sms, etc).
	"secondary": [
		{
			"name": "",
			"contact": "",
		},
	],
	
	// Additional information regarding the contact details that are not covered by the above 
	// fields.
	"additionalInfo": "Plain Text",
}

bountyTerms

Bounty Percentage

{
	// Percentage of "Returnable Assets" the white-hat recieves as a bounty.
	"percentage": 10,
	
	// Maximum value of the bounty, in US dollars, regardless of the percentage.
	"cap": 1_000_000,
	
	// Whether the white-hat can retain the bounty. See 3.2.b.ii for more details.
	"retainable": {options: true, false},
	
	// Additional information regarding the bounty terms that are not covered by
	// the above fields.
	"additionalInfo": "Plain Text",
}

[rholterhus]

Agree that this should be standardized - thanks for the detailed starting point! I'll be adding some more documentation to the registry soon, and will certainly incorporate this.

[Robert-MacWha]

Created a PR with some documentation for the registrar. Feel free to change / modify, but I felt guilty leaving all the work for you :)

#5

[rholterhus]

Awesome, just left a comment on the PR. Thanks!

[Robert-MacWha]

Closed because we've implemented this in PRs