Merge pull request #117 from gnidan/readme

Improve README.md

CHANGELOG.md

@@ -19,6 +19,9 @@
 - Remove Gitter badge ([#116](https://github.com/gnidan/abi-to-sol/pull/116) by
   [@gnidan](https://github.com/gnidan))
 
+- Improve README.md ([#117](https://github.com/gnidan/abi-to-sol/pull/117) by
+  [@gnidan](https://github.com/gnidan))
+
 ## v0.7.1
 
 See [release notes](https://github.com/gnidan/abi-to-sol/releases/tag/v0.7.1).

packages/abi-to-sol/README.md

@@ -3,7 +3,20 @@
 [![npm version](https://badge.fury.io/js/abi-to-sol.svg)](https://www.npmjs.com/package/abi-to-sol)
 [![gitpoap badge](https://public-api.gitpoap.io/v1/repo/gnidan/abi-to-sol/badge)](https://www.gitpoap.io/gh/gnidan/abi-to-sol)
 
-_Generate Solidity `interface` source from a given ABI JSON!_
+Input an ABI JSON and get a Solidity `interface` compatible with whatever
+`pragma solidity <version-range>` you need.
+
+**abi-to-sol** evaluates your input ABI and finds all the external functions,
+events, structs, and user-defined value types in order to produce a source file
+that's suitable for copying and pasting into your project. Import your external
+contract's interface and interact with it, almost as if you had copied the whole
+other project's sourcecode into a "vendor" directory (but without the potential
+Solidity version mismatch!)
+
+It doesn't matter what version of Solidity generated the ABI in the first place
+(or if the contract wasn't even written in Solidity), **abi-to-sol** will give
+you `*.sol` output that's compatible with your existing project! (Some rare
+caveats may apply, see [below](#caveats).)
 
 ## Try online!
 
@@ -97,6 +110,36 @@ interface ENS {
 
 ```
 
+## Caveats
+
+- This tool works best with ABIs from contracts written in Solidity, thanks to
+  the useful `internalType` hints that Solidity provides. This is non-standard,
+  so abi-to-sol still works without those. You should be able to use this tool
+  to import someone else's Vyper contract interface into your Solidity project.
+
+- [User-defined value types](https://blog.soliditylang.org/2021/09/27/user-defined-value-types/)
+  are supported, but if these UDVTs require special constructors, abi-to-sol
+  won't give you any implementations. Take extra care to make sure you know how
+  to interact with an external contract that has UDVTs as part of its interface.
+
+- You might run into problems if you need this tool to output interfaces that
+  are compatible with sufficiently old versions of Solidity (`<0.5.0`), due to
+  certain missing features (structs/arrays couldn't be external function
+  parameters back then).
+
+  ... but probably you should definitely _just don't use solc that old._
+
+- Similarly, there might be problems if you need this tool to output interfaces
+  that are compatible with a particularly large range of solc versions (e.g.
+  `^0.6.0 || ^0.7.0`). This is because the data location changed across versions
+  (from `address[] calldata` to `address[] memory`, e.g.), and there's no single
+  syntax that abi-to-sol can output that would satisfy everything. (This only
+  matters for input ABIs where it's relevant, so you may still be alright.)
+
+- This project does not output Vyper code... but you don't need a project like
+  this one for Vyper because Vyper already lets you import `*.abi.json` files
+  directly! Maybe this isn't a caveat.
+
 ## Is this project useful to you?
 
 Feel free to donate to