This document, the Enterprise Ethereum Alliance Client Specification, defines the implementation requirements for Enterprise Ethereum clients, including the interfaces to external-facing components of Enterprise Ethereum and how they are intended to be used. Its primary intended audience is developers of Enterprise Ethereum clients

For licensing conditions and disclaimer of warranty, please see the terms of the Legal Notice.

This is an editors' draft of the Enterprise Ethereum Alliance Client Specification version 6. Changes made since version 5 of this Specification, released on 18 May 2020, have been reviewed by the Enterprise Ethereum Alliance (EEA) Technical Specification Working Group (TSWG), but not the EEA Board. The TSWG expects at time of writing that this revision of the Specification will be released in the last quarter of 2020, obsoleting version 5. Although predicting the future is known to be difficult, as well as ongoing quality enhancement, future work on this Specification is expected to include the following aspects: * Interoperability of Restricted Private transactions. * Agreement on a [[Byzantine-Fault-Tolerant]] consensus algorithm. * Off-chain trusted computing APIs * Cross-chain interoperability * Tracking developments for Ethereum 1.x and Ethereum 2.0 The group is also expecting to hear about further implementation experience, that could potentially lead to proposed modifications. This particularly applies to experimental sections of the specification: * The object syntax for recording changes to maxCodeSize * Asynchronous methods for private transactions Please send any comments to the EEA Technical Steering Committee at [https://entethalliance.org/contact/](https://entethalliance.org/contact/).

For licensing conditions and disclaimer of warranty, please see the terms of the Legal Notice.

Introduction

This document, the Enterprise Ethereum Alliance Client Specification, defines the implementation requirements for Enterprise Ethereum clients, including the interfaces to external-facing components of Enterprise Ethereum and how they are intended to be used. A partial list of use cases [[USECASES]] this specification attempts to address is available as a work in progress. A companion document, the Enterprise Ethereum Blockchain Specification [[EEA-chains]] defines requirements for Enterprise Ethereum blockchains to ensure that clients that conform to this specification can work interopably on blockchains that meet the requirements defined in that document. For the purpose of this Specification:

Why Produce a Client Specification?

With a growing number of vendors developing Enterprise Ethereum clients, meeting the requirements outlined in this Client Specification ensures different clients can communicate with each other and interoperate reliably on a given Enterprise Ethereum blockchain. For ÐApp developers, for example, a Client Specification ensures clients provide a set of identical interfaces so that ÐApps will work on all conforming clients. This enables an ecosystem where users can change the software they use to interact with a running blockchain, instead of being forced to rely on a single vendor to provide support. From the beginning, this approach has underpinned the development of Ethereum and it meets a key need for blockchain use in many enterprise settings. Client diversity also provides a natural mechanism to help verify that the protocol specification is unambiguous because interoperability errors revealed in development highlight parts of the protocol that different engineering teams interpret in different ways. Finally, standards-based interoperability allows users to leverage the widespread knowledge of Ethereum in the blockchain development community to minimize the learning curve for working with Enterprise Ethereum. This reduces risk when deploying an Enterprise Ethereum blockchain.

Experimental Requirements

This Specification includes requirements and Application Programming Interfaces (APIs) that are described as experimental. Experimental means that a requirement or API is in early stages of development and might change as feedback is incorporated. Implementors are encouraged to implement these experimental requirements, with the knowledge that requirements in future versions of the Specification are not guaranteed to be compatible with the current version. Please send comments and feedback on experimental portions of this Specification to the EEA Technical Steering Committee at [https://entethalliance.org/contact/](https://entethalliance.org/contact/).

Requirement Categorization

All requirements in this Specification are categorized as either:

Security Considerations

Security of information systems is a major field of work. Enterprise Ethereum software development shares with all software development the need to consider security issues and the obligation to update implementations in line with new information and techniques to protect its users and the ecosystem in which it operates.

However, some aspects of Ethereum in general, and Enterprise Ethereum specifically, are especially important in an organizational environment.

Callback URL Sanitization

The asynchronous JSON-RPC methods `eea_sendTransactionAsync` and `eea_sendRawTransactionAsync` utilize a URL provided by the user at call time to inform the user of the completion of the asynchronous operation. Attackers can use these URLs to cause the node server to invoke resources present on the private network for the node that the attacker would not normally have access to or to cause the node to spam the callback URL. Enterprise Ethereum clients need to provide appropriate URL sanitization and restrictions, such as whitelisting and request throttling, to prevent such vulnerabilities from being exploited in the course of executing asynchronous operations.

Attacks on Enterprise Ethereum

Modeling attacks against a node helps identify and prioritize the necessary security countermeasures to implement. Some attack categories to consider include: - Attacks on unauthenticated [[JSON-RPC]] interfaces through malicious JavaScript in the browser using DNS rebinding. - Eclipse attacks (attacks targeting specific nodes in a decentralized network) that attempt to exhaust client network resources or fool its node-discovery protocol. - Targeted exploitation of consensus bugs in EVM implementations. - Malicious code contributions to open-source repositories. - All varieties of social engineering attacks.

Positive Security Design Patterns

Complex interfaces increase security risk by making user error more likely. For example, entering Ethereum addresses by hand is prone to errors. Therefore, implementations can reduce the risk by providing user-friendly interfaces, ensuring users correctly select an opaque identifier using tools, like a contact manager. Gas (defined in the [[Ethereum-Yellow-Paper]]) is a virtual pricing mechanism for transactions and smart contracts that is implemented by Ethereum to protect against Denial of Service attacks and resource-consumption attacks by compromised, malfunctioning, or malicious nodes. Enterprise Ethereum provides additional tools to reduce security risks, such as more granular permissions for actions in a network.

Permissioning plays some role in mitigating network-level attacks (like the 51% attack), but it is important to carefully consider which risks are of most concern to a client implementation versus those that are better mitigated by updates to the Ethereum consensus protocol design.

Handling of Sensitive Data

The implications of private data storage are also important to consider, and motivate several requirements in this Specification. The long-term persistence of encrypted data on any public platform (such as Ethereum) exposes it to eventual decryption by brute-force attack, accelerated by the inevitable periodic advances in cryptanalysis. A future shift to post-quantum cryptography is a current concern, but will not likely be the last advancement in the field. Assuming no encryption scheme endures for eternity, a degree of protection is required to reasonably exceed the lifetime of the data's sensitivity. Besides user-generated data, a client is also responsible for managing and protecting private keys. Encrypting private keys with a passphrase or other authentication credential before storage helps protect them from disclosure. It is also important not to disclose sensitive data when recording events to a log file.

Security of Client Implementations

There are several specific functionality areas that are more prone to security issues arising from implementation bugs. The following areas deserve a greater focus during the design and the security assessment of an Enterprise Ethereum client: - Peer-to-peer protocol implementation - Object deserialization routines - Ethereum Virtual Machine (EVM) implementation - Key pair generation. The peer-to-peer protocol used for communication among nodes in Ethereum is a client's primary vector for exposure to untrusted input. In any software, the program logic that handles untrusted inputs is the primary focus area for implementing secure data handling. Object serialization and deserialization is commonly part of the underlying implementation of the P2P protocol, but also a source of complexity that, historically, is prone to security vulnerabilities across many implementations and many programming languages. Selecting a deserializer that offers strict control of data typing can help mitigate the risk. EVM implementation correctness is an especially important security consideration for clients. Unless EVMs behave identically for all possibilities of input, there is a serious risk of a hard fork caused by an input that elicits the differences in behavior across clients. EVM implementations are also exposed to denial-of-service attempts by maliciously constructed smart contracts, and the even more serious risk of an exploitable remote-code-execution vulnerability. A hard fork is a permanent divergence from the previous version of a blockchain. Nodes using older network configuration are no longer able to participate fully in the Enterprise Ethereum blockchain after the hard fork block. A hard fork block is the block from which a hard fork occurred. The Ethereum specification defines many of the technical aspects of public/private key pair format and cryptographic algorithm choice, but a client implementation is still responsible for properly generating these keys using a well-reviewed cryptographic library. Specifically, a client implementation needs a properly seeded, cryptographically secure, pseudo-random number generator (PRNG) during the keypair generation step. An insecure PRNG is not generally apparent by merely observing its outputs, but enables attackers to break the encryption and reveal users' sensitive data.

Anti-spam

This section refers to mechanisms to prevent the Enterprise Ethereum blockchain being degraded with a flood of intentional or unintentional messages (either malicious, buggy, or uncontrolled). This might be realized through interfacing with an external security manager, as described in Section , or implemented by the client.

Enterprise Ethereum Architecture

The following two diagrams show the relationship between Enterprise Ethereum components that can be part of any Enterprise Ethereum client implementation. The first is a stack representation of the architecture showing a library of interfaces, while the second is a more traditional style architecture diagram showing a representative architecture.
Enterprise Ethereum Architecture Stack
Enterprise Ethereum Architecture Stack
Representative Enterprise Ethereum High-level Architecture
Representative Enterprise Ethereum High-level Architecture
The architecture stack for Enterprise Ethereum consists of five layers: - Application - Tooling - Enterprise 3 P's - Core Blockchain - Network. These layers are described in the following sections.

Application Layer

The Application layer exists, often fully or partially outside of a client, where higher-level services are provided. For example, Ethereum Name Service (ENS), node monitors, blockchain state visualizations and explorers, self-sovereign and other identity schemes, wallets, and any other applications of the ecosystem envisaged. Wallets are software applications used to store an individual’s credentials (cryptographic private keys), which are associated with the state of that user’s Ethereum account.

Wallets can interface with Enterprise Ethereum using the Extended RPC API, as shown in . A wallet can also interface directly with the enclave of a private transaction manager, or interface with public Ethereum.

A private transaction manager is a subsystem of an Enterprise Ethereum system for implementing privacy and permissioning.

ÐApps Sublayer

Decentralized Applications, or ÐApps, are software applications running on a decentralized peer-to-peer network, often a blockchain. A ÐApp might include a user interface running on another (centralized or decentralized) system. ÐApps run on top of Ethereum. ÐApps running on an Enterprise Ethereum blockchain can use the extensions to the Ethereum JSON-RPC API that are defined in this Specification. Also at the ÐApps sublayer are blockchain explorers, tools to monitor the blockchain, and other business intelligence tools.

Infrastructure Contracts and Standards Sublayer

Some important tools for managing a blockchain, are built at the Application layer. These components together make up the Infrastructure Contracts and Standards sublayer. Permissioning contracts determine whether nodes and accounts can access, or perform specific actions on, an Enterprise Ethereum blockchain, according to the needs of the blockchain. These permissioning contracts can implement Role-based access control (RBAC) [[WP-RBAC]] or Attribute-based access control (ABAC) [[WP-ABAC]], as well as simpler permissioning models, as described in the Permissioning Management Examples section of the Implementation Guide [[EEA-implementation-guide]]. Token standards provide common interfaces and methods along with best practices. These token standards include [[ERC-20]], [[ERC-223]], [[ERC-621]], [[ERC-721]], and [[ERC-827]]. The Ethereum Name Service (ENS) provides a secure and decentralized mapping from simple, human-readable names to Ethereum addresses for resources both on and off the blockchain.

Smart Contract Tools Sublayer

Enterprise Ethereum inherits the smart contract tools used by public Ethereum. These tools include smart contract languages and associated developer tools, such as parsers, compilers, and debuggers, as well as methods used for security analysis and formal verification of smart contracts.

Enterprise Ethereum implementations enable use of these tools and methods through implementation of the Execution sublayer, as described in Section .

[P] SMRT-030: Enterprise Ethereum clients MUST support smart contracts of at least 24,576 bytes in size.

[P] SMRT-040: Enterprise Ethereum clients MUST read and enforce a size limit for transactions that deploy smart contracts from the maxCodeSize parameter in the network configuration, specified as a number of kilobytes as defined in the section below.

[P] SMRT-060: Enterprise Ethereum clients MUST read and enforce a size limit for transactions that deploy smart contracts from the maxCodeSize parameter in the network configuration, specified as a javascript object as defined in the section below.

See also [[CONFIG-010]](chainspec.html#req-config-010) in the Enterprise Ethereum Blockchain specification [[EEA-chains]].

The maxCodeSize parameter

This section is experimental The `maxCodeSize` parameter in the network configuration has a value that is either a positive integer or a Javascript object. If the value is an integer, it specifies the maximum size limit, in kilobytes, of a smart contract for deployment. It the value is a Javascript object, it is interpreted as a set of pairs of integers: - The first number in the pair specifies the maximum size limit, in kilobytes, of a smart contract for deployment. - The second number is the block height from which the associated size limit applies. Any transaction to deploy a smart contract larger than limit is an invalid transaction. A negative value of limit means the blockchain does not impose any limit. A missing or non-integer value of limit means the client imposes its implementation-dependent default limit, that MUST be **at least** 24 kilobytes (see [SMRT-030](#req-smrt-030)). A negative value for the block height is an error, and the client MUST NOT apply the associated limit. A missing value, or non-integer value, or value of block height that is less than or equal to the preceding value is an error, and the client MUST NOT apply the associated limit.

Tooling Layer

The Tooling layer contains the APIs used to communicate with clients. The Ethereum JSON-RPC API, implemented by public Ethereum, is the primary API to submit transactions for execution, deploy smart contracts, and to allow ÐApps and wallets to interact with the platform. The [[JSON-RPC]] remote procedure call protocol and format is used for the JSON-RPC API implementation. Other APIs are allowed, including those intended for inter-blockchain operations and to call external services, such as trusted oracles. Integration libraries, such as [[web3j]], [[web3.js]], and [[Nethereum]], are software libraries used to implement APIs with different language bindings (like the Ethereum JSON-RPC API) for interacting with Ethereum nodes. Enterprise Ethereum implementations can restrict operations based on permissioning and authentication schemes.

The Tooling layer also provides support for the compilation, and possibly formal verification, of smart contracts through the use of parsers and compilers for one or more smart contract languages.

Smart contract languages are the programming languages, such as [[Solidity]] and [[LLL]], used to create smart contracts. For each language, tools can perform tasks such as compiling to EVM bytecode, static security checking, or formal verification.

Formal verification is the mathematical verification of the logical correctness of a smart contract designed to run in the EVM.

Credential Management Sublayer

Credentials, in the context of Enterprise Ethereum blockchains, refer to an individual’s cryptographic private keys, which are associated with that user’s Ethereum account. Enterprise Ethereum clients can choose to offer local handling of user credentials, such as key management systems and wallets. Such facilities might also be implemented outside the scope of a client.

Integration and Deployment Tools Sublayer

Many software systems integrate with enterprise management systems using common APIs, libraries, and techniques, as shown in .
Management Interfaces
Management Interfaces
As well as deployment and configuration capabilities, Enterprise Ethereum clients can offer functionality such as software fault reporting, performance management, security management, integration with other enterprise software, and historical analysis tools. These are not requirements of this Specification, instead they are optional features to distinguish between different Enterprise Ethereum clients.

Client Interfaces and APIs Sublayer

As part of the Client Interfaces and APIs sublayer, [[JSON-RPC]] is a stateless, light-weight remote procedure call (RPC) protocol using [[JSON]] as its data format. The [[JSON-RPC]] specification defines several data structures and the rules around their processing.

An Ethereum JSON-RPC API is used to communicate between ÐApps and nodes.

Compatibility with the Core Ethereum JSON-RPC API

[P] JRPC-010: Enterprise Ethereum clients MUST provide support for the following Ethereum JSON-RPC API methods:

  • `net_version`
  • `net_peerCount`
  • `net_listening`
  • `eth_protocolVersion`
  • `eth_syncing`
  • `eth_coinbase`
  • `eth_hashrate`
  • `eth_gasPrice`
  • `eth_accounts`
  • `eth_blockNumber`
  • `eth_getBalance`
  • `eth_getStorageAt`
  • `eth_getTransactionCount`
  • `eth_getBlockTransactionCountByHash`
  • `eth_getBlockTransactionCountByNumber`
  • `eth_getCode`
  • `eth_sendRawTransaction`
  • `eth_call`
  • `eth_estimateGas`
  • `eth_getBlockByHash`
  • `eth_getBlockByNumber`
  • `eth_getTransactionByHash`
  • `eth_getTransactionByBlockHashAndIndex`
  • `eth_getTransactionByBlockNumberAndIndex`
  • `eth_getTransactionReceipt`
  • `eth_getUncleByBlockHashAndIndex`
  • `eth_getUncleByBlockNumberAndIndex`
  • `eth_getLogs`.

[P] JRPC-007: Enterprise Ethereum clients SHOULD implement [[JSON-RPC-API]] methods to be backward compatible with the definitions given in version e8e0771 of the Ethereum JSON-RPC API reference [[!JSON-RPC-API-e8e0771]], unless breaking changes were made and widely implemented for the health of the ecosystem. For example, to fix a major security or privacy problem.

[C] JRPC-015: Enterprise Ethereum clients MUST provide the capability to accept and respond to JSON-RPC method calls over a websocket interface.

[C] JRPC-040: Enterprise Ethereum clients MUST provide an implementation of the debug_traceTransaction method [[debug-traceTransaction]] from the Go Ethereum Management API.

[C] JRPC-050: Enterprise Ethereum clients MUST implement the [[!JSON-RPC-PUB-SUB]] API.

[P] JRPC-070: Enterprise Ethereum clients implementing additional nonstandard subscription types for the [[!JSON-RPC-PUB-SUB]] API MUST prefix their subscription type names with a namespace prefix other than eea_.

Extensions to the JSON-RPC API

[P] JRPC-080: Enterprise Ethereum clients must not use the prefix eea_ for the names of [[JSON-RPC]] methods that are not defined by this specification.

[P] JRPC-020: Enterprise Ethereum clients MUST implement at least one of the following extensions to create private transaction types defined in the Section :

[P] JRPC-025: Enterprise Ethereum clients MAY implement the following experimental extensions to create private transaction types defined in the Section :

[P] JRPC-030: The eea_sendTransactionAsync, eea_sendTransaction, eea_sendRawTransactionAsync, and eea_sendRawTransaction methods MUST respond with a [[JSON-RPC]] error response when an unimplemented private transaction type is requested. The error response MUST have the code -50100 and the message Unimplemented private transaction type.

**Example response**
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -50100,
    "message": "Unimplemented private transaction type"
  }
}
Synchronous Private Transaction Methods
eea_sendTransaction
A call to `eea_sendTransaction` creates a private transaction, signs it, generates the transaction hash and submits it to the transaction pool, and returns the transaction hash. **Parameters** The transaction object containing: - `from` DATA, 20 bytes – The address of the account sending the transaction. - `to` DATA, 20 bytes – Optional when creating a new contract. The address of the account receiving the transaction. - `gas` QUANTITY – Optional. The gas, as an integer, provided for the transaction. - `gasPrice` QUANTITY – Optional. The gas price, as an integer. - `value` QUANTITY – Optional. The value, as an integer, if present must be set to 0. - `data` DATA – Transaction data (compiled smart contract code or encoded method data). - `nonce` QUANTITY – Optional. A nonce value, as an integer. This allows you to overwrite your own pending transactions that use the same nonce. - `privateFrom` DATA, 32 bytes – Optional. The public key of the sender of this private transaction. If this parameter is not supplied, the node could supply a default for `privateFrom`. If this parameter is not supplied and the node is unable to supply a default, the transaction fails. - `privateFor` DATA – An array of the public keys of the intended recipients of this private transaction. Mutually exclusive with the `privacyGroupId` parameter. If both `privateFor` and `privacyGroupId` parameters are provided, an error response is generated. - `privacyGroupId` DATA, 32 bytes – The privacy group identifier for the group of intended recipients of this private transaction. If a client does not support this parameter, it should return a privacyGroupId not supported error response. The `privacyGroupId` and `privateFor` parameters are mutually exclusive. If both the `privacyGroupId` and `privateFor` parameters are provided, an error response is generated. - `restriction` STRING – If `restricted`, the transaction is a restricted private transaction. If `unrestricted`, the transaction is an unrestricted private transaction. For more information, see Section . **Returns** DATA, 32 Bytes – The transaction hash, or the zero hash if the transaction is not yet available. If creating a contract, use `eth_getTransactionReceipt` to retrieve the contract address after the transaction is finalized. **Request Format** ```js curl -X POST --data '{"jsonrpc":"2.0","method":"eea_sendTransaction","params": [{ "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", "to": "0xd46e8dd67c5d32be8058bb8eb970870f072445675", "gas": "0x76c0", "gasPrice": "0x9184e72a000", "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", "privateFor": ["g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw="], "restriction": "restricted"}], "id":1}' Or alternatively, when a privacyGroupId is provided instead of privateFor: "privacyGroupId": "Vbj70zF+G2V/8XoyZzwqawfcQ+r9BkXoLQOqkQideys=", ``` **Response Format** ```js { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" } ```
eea_sendRawTransaction
A call to `eea_sendRawTransaction` creates a private transaction, which has already been signed, generates the transaction hash and submits it to the transaction pool, and returns the transaction hash. The signed transaction passed as an input parameter is expected to include the `privateFrom`, `privateFor`, `privacyGroupId`, and `restriction` fields, as specified in the Parameters section of . **Parameters** The transaction object containing: - `data` DATA – The signed transaction data. ```js params: ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"] ``` **Returns** DATA, 32 Bytes – The transaction hash, or the zero hash if the transaction is not yet available. If creating a contract, use `eth_getTransactionReceipt` to retrieve the contract address after the transaction is finalized. **Request Format** ```js curl -X POST --data '{"jsonrpc":"2.0","method":"eea_sendRawTransaction","params": [{see above}], "id":1}' ``` **Response Format** ```js { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" } ```
Asynchronous Private Transaction Methods
This section is experimental.

At the time of publication, the asynchronous methods to create private transactions are only known to be implemented by the Quorum client. The Working Groups is seeking feedback from developers about these asynchronous methods:

  • Are they useful?
  • Is this the appropriate layer to be determining whether to make requests asynchronous?
  • Is the API comfortable to use, or should we consider changes such as using a parameter instead of a different method name?

Please provide feedback through the EEA Technical Steering Committee at https://entethalliance.org/contact/.

eea_sendTransactionAsync
A call to `eea_sendTransactionAsync` creates a private transaction, signs it, submits it to the transaction pool, and returns immediately. Using this method allows sending many transactions without waiting for recipient confirmation. **Parameters** The transaction object for this call contains: - `from` DATA, 20 bytes – The address of the account sending the transaction. - `to` DATA, 20 bytes – The address of the account receiving the transaction. - `gas` QUANTITY – Optional. The gas, as an integer, provided for the transaction. - `gasPrice` QUANTITY – Optional. The gas price, as an integer. - `value` QUANTITY – Optional. The value, as an integer, if present must be set to 0. - `data` DATA – Transaction data (compiled smart contract code or encoded method data). - `nonce` QUANTITY – Optional. A nonce value, as an integer. This allows you to overwrite your own pending transactions that use the same nonce. - `privateFrom` DATA, 32 bytes – Optional. The public key of the sender of this private transaction. If this parameter is not supplied, the node could supply a default for `privateFrom`. If this parameter is not supplied and the node is unable to supply a default, the transaction fails. - `privateFor` DATA – An array of the public keys of the intended recipients of this private transaction. Mutually exclusive with the `privacyGroupId` parameter. If both the `privateFor` and `privacyGroupId` parameters are provided, an error response is generated. - `privacyGroupId` DATA, 32 bytes – The privacy group identifier for the group of intended recipients of this private transaction. If a client does not support this parameter, it should return a privacyGroupId not supported error response. The `privacyGroupId` and `privateFor` parameters are mutually exclusive. If both the `privacyGroupId` and `privateFor` parameters are provided, an error response is generated. - `restriction` STRING – If `restricted`, the transaction is a restricted private transaction. If `unrestricted`, the transaction is an unrestricted private transaction. For more information, see Section . - `callbackUrl` STRING – The URL to post the results of the transaction to. **Callback Body** The callback object for this call contains: - `txHash` DATA, 32 bytes – The transaction hash (if successful). - `txIndex` QUANTITY – The index position, as an integer, of the transaction in the block. - `blockHash` DATA, 32 Bytes – The hash of the block this transaction was in. - `blockNumber` QUANTITY – The number of the block, as an integer, this transaction was in. - `from` DATA, 20 Bytes – The public key of the sender of this private transaction. - `to` DATA, 20 Bytes – The account address of the receiver. `null` if a contract creation transaction. - `cumulativeGasUsed` QUANTITY – The total amount of gas used when this transaction was executed in the block. - `gasUsed` QUANTITY – The amount of gas used by this specific transaction. - `contractAddress` DATA, 20 Bytes – The contract address created, if a contract creation transaction, otherwise `null`. - `logs` Array – An array of log objects generated by this transaction. - `logsBloom` DATA, 256 Bytes – A bloom filter for light clients to quickly retrieve related logs. - `error` STRING – Optional. Includes an error message describing what went wrong. - `id` DATA – Optional. The ID of the request corresponding to this transaction, as provided in the initial [[JSON-RPC]] call. Also returned is either: - `root` DATA, 32 bytes – The post-transaction stateroot (pre-Byzantium). - `status` QUANTITY – The return status, either 1 (success) or 0 (failure). **Request Format** ```js curl -X POST --data '{"jsonrpc":"2.0","method":"eea_sendTransactionAsync","params":[{ "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", "to": "0xd46e8dd67c5d32be8058bb8eb970870f072445675", "gas": "0x76c0", "gasPrice": "0x9184e72a000", "data":"0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", "privateFrom": "negmDcN2P4ODpqn/6WkJ02zT/0w0bjhGpkZ8UP6vARk=", "privateFor": ["g59BmTeJIn7HIcnq8VQWgyh/pDbvbt2eyP0Ii60aDDw="], "callbackUrl": "http://myserver/id=1", "restriction": "restricted"}], "id":1}' Or alternatively, when a privacyGroupId is provided instead of privateFor: "privacyGroupId": "Vbj70zF+G2V/8XoyZzwqawfcQ+r9BkXoLQOqkQideys=", ``` **Response Format** ```js { "id":1, "jsonrpc": "2.0" } ``` **Callback Format** ```js { "txHash": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" "txIndex": "0x1", // 1 "blockNumber": "0xb", // 11 "blockHash": "0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "cumulativeGasUsed": "0x33bc", // 13244 "gasUsed": "0x4dc", // 1244 "contractAddress": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", // or null, if none was created "logs": "[{ // logs as returned by getFilterLogs, etc. }, ...]", "logsBloom": "0x00...0", // 256 byte bloom filter "status": "0x1" } ```
eea_sendRawTransactionAsync
A call to `eea_sendRawTransactionAsync` creates a private transaction that is already signed, submits it to the transaction pool, and returns immediately. Using this method allows sending many transactions without waiting for recipient confirmation. The signed transaction passed as an input parameter is expected to include the `privateFrom`, `privateFor`, `privacyGroupId`, and `restriction` fields, as specified in the Parameters section of . It is also expected to include the `callbackUrl` field. **Parameters** The transaction object containing: - `data` DATA – The signed transaction data. ```js params: ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"] ``` **Callback Body** The callback object for this call contains: - `txHash` DATA, 32 bytes – The transaction hash (if successful). - `txIndex` QUANTITY – The index position, as an integer, of the transaction in the block. - `blockHash` DATA, 32 Bytes – The hash of the block this transaction was in. - `blockNumber` QUANTITY – The number of the block, as an integer, this transaction was in. - `from` DATA, 20 Bytes – The public key of the sender of this private transaction. - `to` DATA, 20 Bytes – The address of the account receiving this transaction. `null` if a contract creation transaction. - `cumulativeGasUsed` QUANTITY – The total amount of gas used when this transaction was executed in the block. - `gasUsed` QUANTITY – The amount of gas used by this specific transaction. - `contractAddress` DATA, 20 Bytes – The contract address created, if a contract creation transaction, otherwise `null`. - `logs` Array – An array of log objects generated by this transaction. - `logsBloom` DATA, 256 Bytes – A bloom filter for light clients to quickly retrieve related logs. - `error` STRING – Optional. Includes an error message describing what went wrong. - `id` DATA – Optional. The ID of the request corresponding to this transaction, as provided in the initial [[JSON-RPC]] call. Also returned is either: - `root` DATA, 32 bytes – The post-transaction stateroot (pre-Byzantium). - `status` QUANTITY – The return status, either 1 (success) or 0 (failure). **Request Format** ```js curl -X POST --data '{"jsonrpc":"2.0","method":"eea_sendRawTransactionAsync","params": [{see above}], "id":1}' ``` **Response Format** ```js { "id":1, "jsonrpc": "2.0" } ``` **Callback Format** ```js { "txHash": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" "txIndex": "0x1", // 1 "blockNumber": "0xb", // 11 "blockHash": "0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "cumulativeGasUsed": "0x33bc", // 13244 "gasUsed": "0x4dc", // 1244 "contractAddress": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", // or null, if none was created "logs": "[{ // logs as returned by getFilterLogs, etc. }, ...]", "logsBloom": "0x00...0", // 256 byte bloom filter "status": "0x1" } ```

Permissioning Smart Contract

This section presents smart contract interfaces providing the necessary information for Enterprise Ethereum clients to enforce permissioning models in an interoperable manner. This includes both node-permissioning and account-permissioning interfaces.

It is based on a chain deployment architecture where permissioning is split into permissioning management, handled by a permissioning contract on the Enterprise Ethereum blockchain, and permissioning enforcement, handled by the Enterprise Ethereum client based on information provided by the permissioning contract.

Permissioning Enforcement

Permissioning enforcement is performed to enforce the permissioning requirements of an Enterprise Ethereum blockchain. To obtain the information necessary to conduct enforcement, Enterprise Ethereum clients call specific functions in the permissioning contracts. These are common functions for all clients on the Enterprise Ethereum blockchain to use. The included functions are:

`connectionAllowed`
Determines whether to permit a connection with another node.
`transactionAllowed`
Determines whether to accept a transaction received from a given Ethereum account.
A client is not necessarily able to update the permissioning scheme, nor does it automatically have any knowledge of its implementation. The node-permissioning and account-permissioning interfaces emit `NodePermissionsUpdated` and `AccountPermissionsUpdated` events, respectively, when the underlying rules are changed. Clients register for these events that signal when to re-assess any permissions that were previously checked to ensure that results being used, or that were cached, are revalidated when necessary. The events contain the `addsRestrictions` and `addsPermissions` Boolean flags. If either flag is set to `true`, any previous connectionAllowed or transactionAllowed call could now result in a different outcome, because the previously checked permissions have changed. If `addsRestrictions` is `true`, then one or more `connectionAllowed` or `transactionAllowed` calls that previously returned `true` will now return `false`. Similarly, if `addsPermissions` is `true`, at least one `connectionAllowed` or `transactionAllowed` call that previously returned `false` will now return `true`.
Permissioning Management
The permissioning management smart contract functions provide the ability to configure and manage the permissioning model in use. These include the bulk of the constructs used to organize permissions, processes to adjust permissions, administration of the permissioning mechanism, and enforcing any regulatory requirements. The definition of these permissioning management functions depends on the permissioning model of the specific Enterprise Ethereum blockchain. It is outside the scope of this Specification, but crucial to the operation of the system. Enterprise Ethereum blockchain operators can choose any permissioning model that suits their needs. Implementations of the permissioning contracts (both enforcement and management functions) are provided on the Enterprise Ethereum blockchain by the blockchain operator. The implementation of permissioning enforcement functions, such as `connectionAllowed`, is part of the permissioning contract. When a management function is called that updates the permissioning model, the node or account smart contract interfaces emit `NodePermissionsUpdated` or `AccountPermissionsUpdated` events, respectively, based on the permissions change.
Node Permissioning

Node permissioning restricts the peer connections that can be established with other nodes in the Enterprise Ethereum blockchain. This helps to prevent interference and abuse by external parties and can establish a trusted whitelist of nodes.

[P] PERM-200: Enterprise Ethereum clients MUST call the connectionAllowed function, as specified in Section , or if it implements PERM-220 and PERM-230, MAY use cached information to determine whether a connection with another node is permitted, and any restrictions to be placed on that connection.

The `connectionAllowed` function returns a `bytes32` type, which is interpreted as a bitmask with each bit representing a specific permission for the connection.

[P] PERM-210: When checking the response to connectionAllowed, if any unknown permissioning bits are found to be zero, Enterprise Ethereum clients MUST reject the connection.

[P] PERM-220: On receipt of a NodePermissionsUpdated event containing an addsRestrictions property with the value true, Enterprise Ethereum clients MUST:

  • Purge all cached results from previous calls to `connectionAllowed` where the result returned was `true`.
  • Close any network connections that are no longer permitted.
  • Impose newly added restrictions on any network connections that have had restrictions added.

[P] PERM-230: On receipt of a NodePermissionsUpdated event containing an addsPermissions property with the value true, Enterprise Ethereum clients MUST:

  • Purge all cached results from previous calls to `connectionAllowed` where the result returned was `false`.
  • Check whether existing network connections have had their restrictions lifted and allow future actions that are now permitted.
Node Permissioning Functions
The node connection rules support both the IPv4 and IPv6 protocol versions. IPv6 addresses are represented using their logical byte value with big endian byte ordering. IPv4 addresses are specified in the IPv4 reserved space within the IPv6 address space, which is found at `0000:0000:0000:0000:0000:ffff:`, and can be be assembled by taking the logical byte value of the IPv4 address with big endian byte ordering, and prefixing it with 80 bits of zeros followed by 16 bits of ones. The `connectionAllowed` function is found at the address given by the `nodePermissionContract` parameter in the network configuration. It implements the following interface, including the `NodePermissionsUpdated` event:
Interface
[
  {
    "name": "connectionAllowed",
    "stateMutability": "view",
    "type": "function",
    "inputs": [
      {
        "name": "sourceEnodeHigh",
        "type": "bytes32"
      },
      {
        "name": "sourceEnodeLow",
        "type": "bytes32"
      },
      {
        "name": "sourceIp",
        "type": "bytes16"
      },
      {
        "name": "sourcePort",
        "type": "uint16"
      },
      {
        "name": "destinationEnodeHigh",
        "type": "bytes32"
      },
      {
        "name": "destinationEnodeLow",
        "type": "bytes32"
      },
      {
        "name": "destinationIp",
        "type": "bytes16"
      },
      {
        "name": "destinationPort",
        "type": "uint16"
      },
    ],
    "outputs": [
      {
        "name": "result",
        "type": "bytes32"
      }
    ]
  },
  {
    "type": "event",
    "name": "NodePermissionsUpdated",
    "inputs": [
    {
      "name": "addsRestrictions",
      "type": "bool",
      "indexed": false
    },
    {
      "name": "addsPermissions",
      "type": "bool",
      "indexed": false
    }
    ]
  }
]
  
**Arguments** - `sourceEnodeHigh`: The high (first) 32 bytes of the enode address of the node initiating the connection. - `sourceEnodeLow`: The low (last) 32 bytes of the enode address of the node initiating the connection. - `sourceIp`: The IP address of the node initiating the connection. If the address is IPv4, it should be prefixed by 80 bits of zeros and 16 bits of ones, bitmasking it such that it fits the IPv4 reserved space in IPv6. For example, `::ffff:127.0.0.1`. - `sourceEnodePort`: The peer-to-peer listening port of the node initiating the connection. - `destinationEnodeHigh`: The high (first) 32 bytes of the enode address of the node receiving the connection. - `destinationEnodeLow`: The low (last) 32 bytes of the enode address of the node receiving the connection. - `destinationIp`: The IP address of the node receiving the connection. If the address is IPv4, it should be prefixed by 80 bits of zeros and 16 bits of ones, bitmasking it such that it fits the IPv4 reserved space in IPv6. For example, `::ffff:127.0.0.1`. - `destinationEnodePort`: The peer-to-peer listening port of the node receiving the connection. - `result`: A bitmask of the permissions granted for this connection. - `addsRestrictions`: If the rules change that caused the NodePermissionsUpdated event to be emitted involves further restricting existing permissions, this will be `true`, otherwise `false`. - `addsPermissions`: If the rules change that caused the NodePermissionsUpdated event to be emitted involves granting new permissions, this will be `true`, otherwise `false`.
Node Permissions
While the core premise of node permissioning is whether a connection is allowed to occur or not, there are additional restrictions that can be imposed on a connection between two nodes based on the permitted behavior of the nodes. The various permissions that can be granted to a connection are represented by bits being set in the bitmask response from `connectionAllowed`. Where bits are unset, the client restricts the behavior of the remote node according to the unset bits. The remaining bits in the response are normally set to one. If any of the remaining bits are zero, an unknown permission restriction was placed on the connection and the connection will be denied. These unknown zeros are likely to represent permissions defined in future versions of this specification. Where they cannot be interpreted by a client, the connection is rejected. Connection Permitted Permission Bit Index: 0 The connection is allowed to be established.
Client Implementation
A client connecting to a chain that maintains a permissioning contract finds the address of the contract in the network configuration. When a peer connection request is received, or a new connection request initiated, the permissioning contract is queried to assess whether the connection is permitted. If permitted, the connection is established and when the node is queried for peer discovery, this connection can be advertised as an available peer. If not permitted, the connection is either refused or not attempted, and the peer excluded from any responses to peer discovery requests. During client startup and initialization the client begins at a bootnode and initially has a global state that is out of sync. Until the client reaches a trustworthy head it is unable to reach a current version of the node permissioning that correctly represents the current state of the blockchain.
Chain Initialization
At the genesis block an initial permissioning contract is normally included, configured so the initial nodes are able to establish connections to each other. The genesis block is the first block (block 0) of a blockchain.
Account Permissioning

Account permissioning controls which accounts are able to send transactions and the type of transactions permitted.

[P] PERM-240: Enterprise Ethereum clients MUST NOT accept a transaction unless either:

    • The client calls the transactionAllowed function, as specified in Section , for the transaction, with worldstate as at the block's parent, and
    • the function returns a value of true;
    or

[P] PERM-250: On receipt of an AccountPermissionsUpdated event containing an addsRestrictions property with the value true, Enterprise Ethereum clients MUST:

  • Purge all cached results from previous calls to `transactionAllowed` where the result returned was `true`.
  • Impose newly added restrictions on any accounts that have had restrictions added.

[P] PERM-260: On receipt of an AccountPermissionsUpdated event containing an addsPermissions property with the value true, Enterprise Ethereum clients MUST:

  • Purge all cached results from previous calls to `transactionAllowed` where the result returned was `false`.
  • Allow future transactions from accounts that are now permitted.
Account Permissioning Function
The `transactionAllowed` function is found at the address given by the `transactionPermissionContract` parameter in the network configuration. It implements the following interface, including the `AccountPermissionsUpdated` event:
Interface
[
  {
    "name": "transactionAllowed",
    "stateMutability": "view",
    "type": "function",
    "inputs": [
      {
        "name": "sender",
        "type": "address"
      },
      {
        "name": "target",
        "type": "address"
      },
      {
        "name": "value",
        "type": "uint256"
      },
      {
        "name": "gasPrice",
        "type": "uint256"
      },
      {
        "name": "gasLimit",
        "type": "uint256"
      },
      {
        "name": "payload",
        "type": "bytes"
      }
    ],
    "outputs": [
      {
        "name": "result",
        "type": "bool"
      }
    ]
  },
  {
    "type": "event",
    "name": "AccountPermissionsUpdated",
    "inputs": [
    {
      "name": "addsRestrictions",
      "type": "bool",
      "indexed": false
    },
    {
      "name": "addsPermissions",
      "type": "bool",
      "indexed": false
    }
    ]
  }
]
  
**Arguments** - `sender`: The address of the account that created this transaction. - `target`: The address of the account or contract that this transaction is directed at. For a creation contract where there is no target, this should be zero filled to represent the `null` address. - `value`: The eth value being transferred in this transaction. - `gasPrice`: The gas price included in this transaction - `gasLimit`: The gas limit in this transaction. - `payload`: The payload in this transaction. Either empty if a simple value transaction, the calling payload if executing a contract, or the EVM code to be deployed for a contract creation. - `addsRestrictions`: If the rules change that caused the AccountPermissionsUpdated event to be emitted involves further restricting existing permissions, this will be `true`. - `addsPermissions`: If the rules change that caused the AccountPermissionsUpdated event to be emitted grants new permissions, this will be `true`. **Return value** - boolean `result`, where a value of `true` means the account submitting the transaction has permission to submit it, and `false` meaning the account does not.
Client Implementation
A client connecting to a chain that maintains a permissioning contract can find the address of the transactionAllowed function in the transactionPermissionContract parameter of the network configuration. When mining new blocks the node checks the validity of transactions using the appropriate permissioning contract with the state at the block's parent. If not permitted, the transaction is discarded. If permitted, the transaction is included in the new block and the block dispatched to other nodes. When receiving a block the node checks each included transaction using the permissioning contract with the state at the block's parent. If any transactions in the new block are not permitted, the block is considered invalid and discarded. If all transactions are permitted, the block passes the permissioning validation check and is then subject to any other validity assessments the client might usually perform. Depending on the use case of a client, the implementation can also check validity of transactions submitted through RPC methods or received through peer-to-peer communication. For such validation, it is expected that the contracts are used with the state represented at the current head. Reading of a contract is an unrestricted operation.
Contract Implementation
When a transaction is checked by the contract it can be assessed by any of the fields provided to restrict operations, such as transferring value between accounts, rate limiting spend or receipt of value, restricting the ability to execute code at an address, limiting gas expenditure or enforcing a minimum expenditure, or restricting the scope of a created contract. When checking the execution of code at an address, it can be useful to be aware of the `EXTCODEHASH` EVM operation, which allows for checking whether there is code present to be executed at the address that received the request. For restricting the scope of created contracts it might be necessary to do static code analysis of the EVM bytecode payload for properties that are not allowed. For example, restricting creation of contracts that employ the create contract opcode.
Chain Initialization
At the genesis block the permissioning contract function is included in block 0, configured so initial accounts can perform required value transactions, a predetermined set of accounts can invoke the contracts defined in the genesis file, and if desired, a predetermined set of accounts can create new contracts.

Inter-chain

With the rapid expansion in the number of different blockchains and ledgers, inter-chain mediators allow interaction between these blockchains. Like other solutions that provide privacy and scalability, inter-chain mediators can be built in Layer 2, such as using public Ethereum to anchor state as needed for tracking and checkpoints.

Enterprise 3 P's Layer

Privacy, performance, and permissioning are the "3 P's" of Enterprise Ethereum. This section describes the extensions in Enterprise Ethereum that support these requirements.

Privacy and performance solutions are broadly categorized into:

Privacy Sublayer

Many use cases for Enterprise Ethereum blockchains have to comply with regulations related to privacy. For example, banks in the European Union are required to comply with the European Union revised Payment Services Directive [[PSD2]] when providing payment services, and the General Data Protection Regulation [[GDPR]] when storing personal data regarding individuals.

Enterprise Ethereum clients support privacy with techniques such as private transactions and enabling an Enterprise Ethereum blockchain to permit anonymous participants. Clients can also support privacy-enhanced Off-chain trusted computing.

New privacy mechanisms are are also being explored as extensions to public Ethereum, including zero-knowledge proofs [[ZKP]], which is a cryptographic technique where one party (the prover) can prove to another party (the verifier) that the prover knows a value x, without conveying any information apart from the fact that the prover knows the value. [[ZK-STARKS]] is an example of a zero-knowledge proof method. A transaction is a request to execute operations on a blockchain that change the state of one or more accounts. Transactions are a core component of most blockchains, including public Ethereum and Enterprise Ethereum. Nodes processing transactions is the fundamental basis of adding blocks to the chain. A private transaction is a transaction where some information about the transaction, such as the payload data, or the sender or the recipient, is only available to the subset of parties privy to that transaction.

Enterprise Ethereum clients support at least one form of private transactions, as outlined in Section . Private transactions can be realized in various ways, controlling which nodes see which private transactions or transaction data.

Enterprise Ethereum implementations can also support off-chain trusted computing, enabling privacy during code execution.

On-chain Privacy

Various on-chain techniques can improve the security and privacy capabilities of Enterprise Ethereum blockchains.

Off-chain Privacy (Trusted Computing)

Off-chain trusted computing uses a privacy-enhanced system to handle some of the computation requested by a transaction. Such systems can be hardware-based, software-based, or a hybrid, depending on the use case.

The EEA has developed Trusted Computing APIs for Ethereum-compatible trusted computing [[EEA-OC]], and requirement EXEC-050 enables Enterprise Ethereum clients to use them for improved privacy.

Privacy Groups

A privacy group is a collection of participants privy to a private transaction. Each member of the group has the ability to decrypt and read a private transaction sent to the group. An Enterprise Ethereum client maintains the public world state for the blockchain and a private state for each privacy group. The private states contain data that is not shared in the globally replicated world state. A private transaction causes a state transition in the public state (that is, a private transaction was committed) and a state transition in the private state (that is, a smart contract state was changed or some information was exchanged in the private state). The `privateFrom` and `privateFor` parameters in the send transaction calls are the public keys of the participants intended to be able to decrypt the private transaction. The `privacyGroupId` parameter uniquely identifies a privacy group. Members of a privacy group are specified by their public keys. A client is expected to propagate a newly created or updated privacy group to the other members which are part of the privacy group.

Private Transactions

The `privateFrom` and `privateFor` parameters in the `eea_sendTransactionAsync` and `eea_sendTransaction` calls specify the public keys of the sender and the intended recipients, respectively, of a private transaction. The private transaction type is specified using the `restriction` parameter. The two defined private transaction types are:

[P] PRIV-010: Enterprise Ethereum clients MUST support one of restricted private transactions or unrestricted private transactions.

Transaction information consists of two parts:

If implementing restricted private transactions:

If implementing unrestricted private transactions:

[P] PRIV-180: Enterprise Ethereum clients SHOULD be able to extend the set of parties privy to a private transaction (or forward the private transaction in some way).

[P] PRIV-190: Enterprise Ethereum clients SHOULD provide the ability for nodes to achieve consensus on their mutually private transactions.

The differences between restricted private transactions and unrestricted private transactions are summarized in the table below.

Table 2 Restricted and Unrestricted Private Transactions
Restricted Private TXNs (if implemented) Unrestricted Private TXNs (if implemented)
Metadata Payload Data Metadata Payload Data
MAY encrypt MUST encrypt

MAY encrypt

SHOULD encrypt sender and recipient identity

MUST encrypt in transit

SHOULD encrypt in storage

SHOULD NOT allow storage by non-participating nodes MUST NOT allow storage by non-participating nodes MAY allow storage by non-participating nodes MAY allow storage by non-participating nodes

Performance Sublayer

Performance is an important requirement for Enterprise Ethereum clients because many use cases for Enterprise Ethereum blockchains imply a high volume of transactions, or computationally-heavy tasks. The overall performance of a blockchain is constrained by the slowest node.

There are many different aspects of performance, and instead of mandating specific requirements, this Specification notes the importance of performance, leaving Enterprise Ethereum client developers free to implement whatever strategies are appropriate for their software. This Specification does not constrain experimentation to improve the performance of Enterprise Ethereum clients. This is an active area of research and it is likely various techniques to improve performance will be developed over time, which cannot be exactly predicted.

This Specification does mandate or allow for several optimizations to improve performance. The most important techniques maximize the throughput of transactions.

On-chain (Layer 1 and Layer 2) Scaling

Techniques to improve performance through scaling are valuable for blockchains where processing is kept on the blockchain and have high transaction throughput requirements.

On-chain (layer 1) scaling techniques, like [[sharding]], are changes or extensions to the public Ethereum protocol to facilitate increased transaction speeds.

On-chain (layer 2) scaling techniques use smart contracts, and approaches like [[Plasma]], or [[state-channels]], to increase transaction speed without changing the underlying Ethereum protocol. For more information, see [[Layer2-Scaling-Solutions]].

Off-chain (Layer 2 Compute)

Off-chain computing can be used to increase transaction speeds by moving the processing of computationally-intensive tasks from nodes processing transactions to one or more trusted computing services. This reduces the resources needed by nodes allowing them to produce blocks faster. This functionality can be enabled by Enterprise Ethereum clients by implementing requirement EXEC-050.

Permissioning Sublayer

Permissioning is the property of a system that ensures operations are executed by and accessible to designated parties. For Enterprise Ethereum, permissioning refers to the ability of a node to join an Enterprise Ethereum blockchain, and the ability of individual accounts or nodes to perform specific functions. For example, an Enterprise Ethereum blockchain might allow only certain nodes to act as validators, and only certain accounts to instantiate smart contracts.

Enterprise Ethereum provides a permissioned implementation of Ethereum supporting peer node connectivity permissioning, account permissioning, and transaction type permissioning.

Nodes

[C] NODE-010: Enterprise Ethereum implementations MUST provide the ability to specify at startup a list of static peer nodes to establish peer-to-peer connections with.

[C] NODE-020: Enterprise Ethereum clients MUST provide the ability to enable or disable peer-to-peer node discovery.

[P] NODE-030: Enterprise Ethereum clients MUST provide the ability to specify a whitelist of the nodes permitted to connect to a node.

[P] NODE-080: Enterprise Ethereum clients MUST provide the ability to specify node identities in a way aligned with the concept of groups.

[P] NODE-090: Enterprise Ethereum clients SHOULD implement transaction ordering identically to the ordering in Geth: "by Price and by Nonce" (ethereum/go-ethereum/core/types/transaction.go, lines 337-349, as of commit #50e3795 ).

[P] NODE-095: Enterprise Ethereum clients MUST specify explicitly and precisely in documentation any transaction ordering logic that is different from that of Geth as recommended in NODE-090.

Ethereum Accounts

For the purpose of this Specification:
  • An organization is a logical group composed of Ethereum accounts, nodes, and other organizations or suborganizations. A suborganization is an organization controlled by and subordinate to another organization. An organization typically represents an enterprise, or some identifiable part of an enterprise. For the purpose of permissioning, organizations roughly correspond to the UNIX concept of groups.
  • A user is a human or an automated process interacting with an Enterprise Ethereum blockchain using the Ethereum JSON-RPC API. The identity of a user is represented by an Ethereum account. Public key cryptography is used to sign transactions made by the user so the EVM can authenticate the identity of a user sending a transaction.
  • An Ethereum account is an established relationship between a user and an Ethereum blockchain. Having an Ethereum account allows users to interact with a blockchain, for example to submit transactions or deploy smart contracts. See also, wallet.
  • Groups are collections of users that have or are allocated one or more common attributes. For example, common privileges allowing users to access a specific set of services or functionality.
  • Roles are sets of administrative tasks, each with associated permissions that apply to users or administrators of a system, used for example in RBAC permissioning contracts.

[P] PART-010: Enterprise Ethereum clients MUST provide the ability to specify a whitelist of accounts that are permitted to transact with the blockchain.

[P] PART-015: Enterprise Ethereum clients MUST be able to verify that accounts are present on the whitelist required by PART-010 when adding transactions from the account to a block, and when verifying a received block containing transactions created by that account.

Core Blockchain Layer

The Core Blockchain layer consists of the Storage and Ledger, Execution, and Consensus sublayers. The Storage and Ledger sublayer is provided to store the blockchain state, such as smart contracts for later execution. This sublayer follows blockchain security paradigms such as using cryptographically hashed tries, a UTXO model, or at-rest-encrypted key-value stores. The Execution sublayer implements the Ethereum Virtual Machine (EVM), which is a runtime computing environment for the execution of smart contracts. Each node operates an EVM. Ethereum-flavored WebAssembly [[eWASM]], which has its own instruction set and other computational capabilities, is also implemented at this layer. Smart contracts are computer programs that the EVM executes. Smart contracts can be written in higher-level programming languages and compiled to EVM bytecode. Smart contracts can implement a contract between parties, where the execution is guaranteed and auditable to the level of security provided by Ethereum itself. A precompiled contract is a smart contract compiled into EVM bytecode and stored by a node. Finally, the Consensus sublayer provides a mechanism to establish consensus between nodes. Consensus is the process of nodes on a blockchain reaching agreement about the current state of the blockchain. A consensus algorithm is the mechanism by which a blockchain achieves consensus. Different blockchains can use different consensus algorithms, but all nodes of a given blockchain need to use the same consensus algorithm. Different consensus algorithms are available for both public Ethereum and Enterprise Ethereum. Enterprise Ethereum clients can provide additional consensus algorithms for operations within their private consortium network (an Ethereum blockchain, either public Ethereum or Enterprise Ethereum, which is not part of the Ethereum MainNet).

Storage and Ledger Sublayer

To operate an Enterprise Ethereum client, and to support optional off-chain operations, local data storage is needed. For example, clients can locally cache the results from a trusted oracle or store information related to systems extensions that are beyond the scope of this Specification.

Private State is the state data that is not shared in the clear in the globally replicated state tree. This data can represent bilateral or multilateral arrangements between parties, for example in private transactions.

[P] STOR-040: Enterprise Ethereum clients SHOULD permit a smart contract operating on private state to access private state created by other smart contracts involving the same parties to the transaction.

[P] STOR-050: Enterprise Ethereum clients MUST NOT permit a smart contract operating on private state to access private state created by other smart contracts involving different parties to the transaction.

[P] STOR-070: If an Enterprise Ethereum client stores private state persistently, it SHOULD protect the data using an Authenticated Encryption with Additional Data (AEAD) algorithm, such as one described in [[RFC5116]].

Execution Sublayer

[P] EXEC-010: Enterprise Ethereum clients MUST provide a smart contract execution environment implementing the public Ethereum EVM opcode set [[!EVM-Opcodes]] that are compatible with the Istanbul hard fork [[!EIP-1679]].

[P] EXEC-020: Enterprise Ethereum clients that provide a smart contract execution environment extending the public Ethereum EVM opcode set [[!EVM-Opcodes]] MUST register the opcode and the name of the Enterprise Ethereum client in the [[!EEA-extended-opcode-registry]].

[P] EXEC-025: Enterprise Ethereum clients that provide a smart contract execution environment extending the public Ethereum EVM opcode set [[!EVM-Opcodes]] SHOULD register a description of the new functionality, and a URL for a complete specification and test suites in the [[!EEA-extended-opcode-registry]], and create an EIP describing the new opcode.

[P] EXEC-030: Enterprise Ethereum clients SHOULD support the ability to synchronize their public state with the public state held by other public Ethereum nodes.

Trusted computing ensures only authorized parties can execute smart contracts on an execution environment available to a given Enterprise Ethereum blockchain.

[C] EXEC-050: Enterprise Ethereum clients that support off-chain trusted computing MUST implement the precompiled function for Worker Attestation [[!TC-Precompile]] defined by the EEA Offchain / Trusted Computing group.

Multiple encryption techniques can be used to secure trusted computing and private state.

[C] EXEC-060: Enterprise Ethereum clients MAY support configurable alternative cryptographic curves as encryption options for Enterprise Ethereum blockchains.

Finality

Finality occurs when a transaction is definitively part of the blockchain and cannot be removed. A transaction reaches finality after some event defined for the relevant blockchain occurs. For example, an elapsed amount of time or a specific number of blocks added.

[P] FINL-010: When a deterministic consensus algorithm is used, Enterprise Ethereum clients SHOULD treat transactions as final after a defined interval or event. For example, after a defined time period has elapsed, or after a defined number of blocks were created since the transaction was included in a block.

Consensus Sublayer

A common consensus algorithm implemented by all clients is required to ensure interoperability between clients. [[Byzantine-Fault-Tolerant]] consensus algorithms ensure a certain proportion of malfunctioning nodes performing voting, block-making, or validation roles do not pose a critical risk to the blockchain. This makes them an excellent choice for many blockchains. The Technical Specification Working Group are [considering](https://github.com/entethalliance/enhanced-bft) existing and new Byzantine-Fault-Tolerant consensus algorithms, primarily those related to IBFT [[EIP-650]], with the goal of adopting the outcomes of that work as a required consensus algorithm as soon as possible.

[P] CONS-050: Enterprise Ethereum clients MAY implement multiple consensus algorithms.

[P] CONS-093: Enterprise Ethereum clients MUST support the Clique, Proof of Authority consensus algorithm [[EIP-225]].

[P] CONS-110: Enterprise Ethereum clients MUST provide the ability to specify the consensus algorithms, through network configuration, to be used for each public blockchain and private blockchain in use.

Network Layer

The Network layer consists of a peer-to-peer networking protocol implementation allowing nodes to communicate with each other. For example, the DEVp2p protocol, which defines messaging between nodes to establish and maintain a communications channel for use by higher layer protocols.

Network Protocol Sublayer

Network protocols define how nodes communicate with each other.

[P] PROT-010: Nodes MUST be identified and advertised using the Ethereum [[!enode]] URL format.

[P] PROT-015: Enterprise Ethereum clients MUST implement the [[!DEVp2p-Node-Discovery]] protocol.

The [[Ethereum-Wire-Protocol]] defines higher layer protocols, known as capability protocols, for messaging between nodes to exchange status, including block and transaction information. [[Ethereum-Wire-Protocol]] messages are sent and received over an already established DEVp2p connection between nodes.

[P] PROT-020: Enterprise Ethereum clients MUST use the [[!DEVp2p-Wire-Protocol]] for messaging between nodes to establish and maintain a communications channel for use by capability protocols.

[P] PROT-050: To minimize the number of point-to-point connections needed between private nodes, some private nodes SHOULD be capable of relaying private transaction data to multiple other private nodes.

[P] PROT-060: Enterprise Ethereum clients SHOULD implement the [[!Whisper-protocol]].

[P] PROT-070: Enterprise Ethereum clients MUST interpret the parameters defined in Section for network configuration when found in the genesis file.

Network configuration refers to the collection of settings defined for a blockchain as described in Section , such as the addresses of the permissioning contracts. It is a set of parameters included as JSON data in the genesis file (genesis.json).

Cross-client Compatibility

Cross-client compatibility refers to the ability of an Enterprise Ethereum blockchain to operate with different clients. Enterprise Ethereum clients implements a web3 programming model, which can be updated with hard forks.

[P] XCLI-001: Enterprise Ethereum clients MUST implement [[!EIP-155]] (included in the Spurious Dragon hard fork) to introduce `chain_id` into transaction signing.

[P] XCLI-002: Enterprise Ethereum clients MUST implement [[!EIP-658]] (included in the Byzantium hard fork) to embed the transaction status code in receipts.

Future versions of this Specification are expected to align with newer versions of public Ethereum as they are deployed.

This Specification extends the capabilities and interfaces of public Ethereum. The requirements relating to supporting and extending the public Ethereum opcode set are outlined in Section .

[P] XCLI-020: Enterprise Ethereum clients MAY extend the public Ethereum APIs. To maintain compatibility, Enterprise Ethereum clients SHOULD ensure these new features are a superset of the public Ethereum APIs.

[P] XCLI-030: Enterprise Ethereum clients MUST implement the gas mechanism specified in the [[!Ethereum-Yellow-Paper]].

[P] XCLI-035: Enterprise Ethereum clients MUST implement the same gas cost per opcode used in the main net's Istanbul hard fork. [[!EIP-1679]].

[P] XCLI-040: Enterprise Ethereum clients MUST function correctly when the Gas price is set to zero.

[P] XCLI-050: Enterprise Ethereum clients MUST implement the eight precompiled contracts defined in Appendix E of the [[!Ethereum-Yellow-Paper]]:

Cross-client compatibility extends to the different message encoding formats used by clients.

[P] XCLI-051: Enterprise Ethereum clients MUST implement the precompiled contract for [[!RFC7693]] Blake 2b F compression defined in [[!EIP-152]]

[P] XCLI-055: Enterprise Ethereum clients MUST register precompiled contracts following the mechanisms defined by [[!EIP-1352]].

[P] XCLI-060: Enterprise Ethereum clients MUST support the Contract Application Binary Interface ([[!ABI]]) for interacting with smart contracts.

[P] XCLI-070: Enterprise Ethereum clients MUST support Recursive Length Prefix ([[!RLP]]) encoding for binary data.

Cross-chain Interoperability

Cross-chain interoperability broadly refers to the ability to consume data from another chain (read) and to cause an update or another transaction on a distinct chain (write).

Cross-chain interoperability can take two forms: - Ethereum to Ethereum (for example, two or more logically distinct EVM-based chains) - Ethereum to another blockchain architecture. Cross-chain interoperability is seen as a valuable feature by both the Enterprise Ethereum community and outside. Users of blockchain and blockchain-inspired platforms want to make use of data and functionality on heterogenous platforms. The goals for cross-chain interoperability in this specification are to: - Describe the layers of interoperability that are relevant to Enterprise Ethereum blockchains. - Enable data consumption between different blockchains without using a trusted intermediary. - Allow transaction execution across blockchains without a trusted intermediary.

Synchronization and Disaster Recovery

Synchronization and disaster recovery refers to how nodes in a blockchain behave when connecting for the first time or reconnecting. Various techniques can help do this efficiently. For an Enterprise Ethereum blockchain with few copies, off-chain backup information can be important to ensure the long-term existence of the information stored. A common backup format helps increase client interoperability.

Additional Information

Defined Terms

The following is a list of terms defined in this Specification.

Defined Events, Functions, and Parameters

The following is a list of events, functions, and parameters defined in this Specification:

Summary of Requirements

This section provides a summary of all requirements in this Specification.

Acknowledgments

The EEA acknowledges and thanks the many people who contributed to the development of this version of the specification. Please advise us of any errors or omissions. This version builds on the work of all who contributed to [previous versions of the Enterprise Ethereum Client Specification](https://entethalliance.org/resources/), whom we hope are all acknowledged in those documents. We apologize to anyone whose name was left off the list. Please advise us at [https://entethalliance.org/contact/](https://entethalliance.org/contact/) of any errors or omissions. We would also like to thank our former co-editors Grant Noble and Robert Coote who worked on all the first 5 versions, David Hyland-Wood (version 1) and Daniel Burnett (version 2), and former EEA Technical Director, the late and missed Clifton Barber, for their work on previous versions of this specification. Enterprise Ethereum is built on top of Ethereum, and we are grateful to the entire community who develops Ethereum, for their work and their ongoing collaboration to helps us maintain as much compatibility as possible with the Ethereum ecosystem.

Changes

Full details of all changes since the version 1.0 release of this Specification are available in the [GitHub repository for this Specification](https://github.com/entethalliance/client-spec). This section outlines substantive changes made to the specification since version 5: - [Pull Request 862](https://github.com/EntEthAlliance/client-spec/pull/862) Update wording of [**JRPC 080**](#rec-jrpc-080) to make the requirement clearer. Similar sections in version 2, version 3, version 4, and version 5 describe the changes made to each version. Old requirements have been removed from earlier versions of the specification, for a variety of reasons. The full list of requirements removed in earlier versions is: ACCT-010, ACCT-020, CONS-010, CONS-020, CONS-030, CONS-040, CONS-060, CONS-070, CONS-080, CONS-090, CONS-100, DAPP-010, ENTM-010, ENTM-020, ENTM-030, ENTM-040, ENTM-050, ENTM-060, ICHN-010, ILIB-010, JRPC-011, JRPC-060, NODE-040, NODE-050, NODE-060, NODE-070, OFFCH-010, ORCL-010, PART-020, PART-025, PART-030, PART-040, PART-050, PART-055, PART-060, PART-070, PERM-075, PERF-010, PERF-020, PERF-030, PERF-040, PERM-010, PERM-020, PERM-030, PERM-040, PERM-050, PERM-060, PRIV-200, PRIV-200, PRIV-200, PROT-040, SCAL-010, SCAL-020, SMRT-010, SMRT-020, SMRT-050, SPAM-010, STOR-010, STOR-020, STOR-030, STOR-060, SYNC-010, SYNC-020, XCLI-005, and XCLI-010.

Legal Notice

The copyright in this document is owned by Enterprise Ethereum Alliance Inc. (“EEA” or “Enterprise Ethereum Alliance”).

No modifications, edits or changes to the information in this document are permitted. Subject to the terms and conditions described herein, this document may be duplicated for internal use, provided that all copies contain all proprietary notices and disclaimers included herein. Except as otherwise provided herein, no license, express or implied, by estoppel or otherwise, to any intellectual property rights are granted herein.

Use of this document and any related intellectual property incorporated herein, is also governed by the Bylaws, Intellectual Property Rights Policy and other governing documents and policies of EEA and is subject to the disclaimers and limitations described below.

No use or display of any of the following names or marks "Enterprise Ethereum Alliance", the acronym "EEA", the EEA logo, or any combination thereof, to claim compliance with or conformance to this document (or similar statements) is permitted absent EEA membership and express written permission from the EEA. The EEA is in process of developing a compliance testing and certification program only for the EEA members in good standing, which it targets to launch towards the end of 2020.

THE CONTENTS OF THIS DOCUMENT ARE PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, SATISFACTORY QUALITY, OR REASONABLE SKILL OR CARE, OR ANY WARRANTY ARISING OUT OF ANY COURSE OF DEALING, USAGE, TRADE PRACTICE, PROPOSAL, SPECIFICATION OR SAMPLE. EEA DOES NOT WARRANT THAT THIS DOCUMENT IS COMPLETE OR WITHOUT ERROR AND DISCLAIMS ANY WARRANTIES TO THE CONTRARY.

Each user of this document hereby acknowledges that sofftware or products implementing the technology specified in this document ("EEA-Compliant Products") may be subject to various regulatory controls under the laws and regulations of various governments worldwide. Such laws and regulatory controls may govern, among other things, the combination, operation, use, implementation and distribution of EEA-Compliant Products. Examples of such laws and regulatory controls include, but are not limited to, airline regulatory controls, telecommunications regulations, finance industry and security regulations, technology transfer controls, health and safety and other types of regulations. Each user of this document is solely responsible for the compliance by their EEA-Compliant Products with any such laws and regulations and for obtaining any and all required authorizations, permits, or licenses for their EEA-Compliant Products related to such regulations within the applicable jurisdictions. Each user of this document acknowledges that nothing in this document or the relevant specification provides any information or assistance in connection with securing such compliance, authorizations or licenses. NOTHING IN THIS DOCUMENT CREATES ANY WARRANTIES WHATSOEVER REGARDING THE APPLICABILITY OR NON-APPLICABILITY OF ANY SUCH LAWS OR REGULATIONS OR THE SUITABILITY OR NON-SUITABILITY OF ANY SUCH PRODUCT OR SERVICE FOR USE IN ANY JURISDICTION.

EEA has not investigated or made an independent determination regarding title or non-infringement of any technologies that may be incorporated, described or referenced in this document. Use of this document or implementation of any technologies described or referenced herein may therefore infringe undisclosed third-party patent rights or other intellectual property rights. The user is solely responsible for making all assessments relating to title and non-infringement of any technology, standard, or specification referenced in this document and for obtaining appropriate authorization to use such technologies, standards, and specifications, including through the payment of any required license fees.

NOTHING IN THIS DOCUMENT CREATES ANY WARRANTIES OF TITLE OR NONINFRINGEMENT WITH RESPECT TO ANY TECHNOLOGIES, STANDARDS OR SPECIFICATIONS REFERENCED OR INCORPORATED INTO THIS DOCUMENT.

IN NO EVENT SHALL EEA OR ANY OF ITS MEMBERS BE LIABLE TO THE USER OR TO A THIRD PARTY FOR ANY CLAIM ARISING FROM OR RELATING TO THE USE OF THIS DOCUMENT, INCLUDING, WITHOUT LIMITATION, A CLAIM THAT SUCH USE INFRINGES A THIRD PARTY’S INTELLECTUAL PROPERTY RIGHTS OR THAT IT FAILS TO COMPLY WITH APPLICABLE LAWS OR REGULATIONS. BY USE OF THIS DOCUMENT, THE USER WAIVES ANY SUCH CLAIM AGAINST EEA AND ITS MEMBERS RELATING TO THE USE OF THIS DOCUMENT.

EEA reserves the right to adopt any changes or alterations to this document as it deems necessary or appropriate without any notice. User is solely responsible for determining whether this document has been superseded by a later version or a different document.