Need a "guidelines"/"best practices" document for how to specify system contract APIs going forward

[david-bakin-sl]

Can't change the past, but we can be more consistent going forward. We've ~made mistakes~ have current APIs which could have been done better.

Some things that could be included:

• Obviously, the business about always using int64 and not uint64 to avoid EVM<->Java conversion issues.
• All APIs should return a response code, not a naked value. ("All" meaning either all or maybe meaning "unless all ramifications considered")
• View functions should not revert
• Overloading (with different or additional parameters) vs new method names.
• How to do versioning of returned structs given return types don't affect the selector and lack of inheritance of structs.
• How to supercede something - e.g., do we remove the old method (with previous signature) to remove clutter or maintain two versions going forward? (How to choose on a case-by-case method is probably the approach here.)

Solidity's rules for mapping function signatures (without the return type) to selectors, and its other capabilities or restrictions (e.g., restriction: no inheritance of structs from structs), play their role here.