External API
Clef listens to HTTP requests on http.addr:http.port (or to IPC on ipcpath), with the same JSON-RPC standard as the Parallax client. The messages are expected to be JSON-RPC 2.0 standard. Some of these JSON-RPC calls require user interaction in the Clef terminal. Responses may be delayed significantly or may never be received if a user fails to respond to a confirmation request. The External API is untrusted: it does not accept credentials, nor does it expect that requests have any authority. See the external API changelog for up to date information about changes to this API. The External API encoding is as follows:- number: positive integers that are hex encoded
- data: hex encoded data
- string: ASCII string
Methods
account_new
Create new password protected account The signer will generate a new private key, encrypt it according to web3 keystore spec and store it in the keystore directory. The client is responsible for creating a backup of the keystore. If the keystore is lost there is no method of retrieving lost accounts. Arguments None Result- address [string]: account address that is derived from the generated key
account_list
List available accounts List all accounts that this signer currently manages Arguments None Result- array with account records:
- account.address [string]: account address that is derived from the generated key
account_signTransaction
Sign transactions Signs a transaction and responds with the signed transaction in RLP-encoded and JSON forms. Supports both legacy and EIP-1559-style transactions. Arguments- transaction object (legacy):
- from [address]: account to send the transaction from
- to [address]: receiver account. If omitted or 0x, will cause contract creation.
- gas [number]: maximum amount of gas to burn
- gasPrice [number]: gas price
- value [number:optional]: amount of Wei to send with the transaction
- data [data:optional]: input data
- nonce [number]: account nonce
- transaction object (1559):
- from [address]: account to send the transaction from
- to [address]: receiver account. If omitted or 0x, will cause contract creation.
- gas [number]: maximum amount of gas to burn
- maxPriorityFeePerGas [number]: maximum priority fee per unit of gas for the transaction
- maxFeePerGas [number]: maximum fee per unit of gas for the transaction
- value [number:optional]: amount of Wei to send with the transaction
- data [data:optional]: input data
- nonce [number]: account nonce
- method signature [string:optional]
- The method signature, if present, is to aid decoding the calldata. Should consist of methodname(paramtype,…), e.g. transfer(uint256,address). The signer may use this data to parse the supplied calldata, and show the user. The data, however, is considered totally untrusted, and reliability is not expected.
- raw [data]: signed transaction in RLP encoded form
- tx [json]: signed transaction in JSON form
account_signData
Sign data Signs a chunk of data and returns the calculated signature. Arguments- content type [string]: type of signed data
- text/validator: hex data with custom validator defined in a contract
- application/clique: clique headers
- text/plain: simple hex data validated by account_ecRecover
- account [address]: account to sign with
- data [object]: data to sign
- calculated signature [data]
account_signTypedData
Sign data Signs a chunk of structured data conformant to EIP-712 and returns the calculated signature. Arguments- account [address]: account to sign with
- data [object]: data to sign
- calculated signature [data]
account_ecRecover
Recover the signing address Derive the address from the account that was used to sign data with content type text/plain and the signature. Arguments- data [data]: data that was signed
- signature [data]: the signature to verify
- derived account [address]
account_version
Get external API version Get the version of the external API used by Clef. Arguments None Result- external API version [string]
Internal (UI) API
Clef has one native console-based UI, for operation without any standalone tools. However, there is also an API to communicate with an external UI. To enable that UI, the signer needs to be started with the--stdio-ui
option, which allocates stdin / stdout for the UI API.
The internal API methods need to be implemented by a UI listener. By starting the signer with the switch --stdio-ui-test
, the signer will invoke all known methods, and expect the UI to respond with denials. This can be used during development to ensure that the API is (at least somewhat) correctly implemented.
All methods in this API use object-based parameters, so that there can be no mixup of parameters: each piece of data is accessed by key.
An example (insecure) proof-of-concept external UI has been implemented in pythonsigner.py.
The model is as follows:
- The user starts the UI app (pythonsigner.py).
- The UI app starts clef with
--stdio-ui
, and listens to the process output for confirmation-requests. - clef opens the external HTTP API.
- When the signer receives requests, it sends a JSON-RPC request via stdout.
- The UI app prompts the user accordingly, and responds to clef.
- clef signs (or not), and responds to the original request.