The copyright in this document is owned by Enterprise Ethereum Alliance Inc. (“EEA” or “Enterprise Ethereum Alliance”).
This Specification is copyright © 2018-2021 Enterprise Ethereum Alliance Incorporated (EEA). It is made available under the terms of the Apache License version 2.0. [[Apache2]]
This is the editors' draft of the Enterprise Ethereum Blockchain Specification version 3. Changes made since version 2 of this Specification, released on 11 November 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 around the middle of 2021, obsoleting version 2. The group is also expecting to hear about further implementation experience, that could potentially lead to proposed modifications. This particularly applies to sections marked experimental: * Organization Registry contracts * The object syntax for maxCodeSize Please send any comments to the EEA Technical Steering Committee through [https://entethalliance.org/contact/](https://entethalliance.org/contact/).Permissioning can play an important role in mitigating network-level attacks, like the 51% attack. However, it is important to ensure permissioning administration does not compromise security.
The definition of a privileged key needs work. For example, if a contract creates token issuers, which keys are privileged keys: the ones that are authorised to issue tokens, or the one that can designate who those can be, or both? Similarly, this definition should integrate with account permissioning as defined for this specification.
Best practice is to ensure that each individual has and manages their own keys, using signing mechanisms that allow multiple signatures, rather than sharing a single private key among multiple people. This provides the flexibility to grant and revoke authority to individuals by providing or removing access to the accounts controlled by their individual key, to ensure some whose authority has been revoked cannot still use a privileged key that others need for administrative functions, and to provide resilience in the case of an individual unexpectedly being unable to operate on an account.
Enterprise Ethereum inherits the smart contract tools used by public Ethereum such as smart contract languages and associated parsers, compilers, and debuggers.
CodSec-010 Smart contracts deployed on an Enterprise Ethereum Blockchan MUST be certified to conform to EthTrust Security Level 1 [[!EthTrust]].
CodSec-030 Smart contracts deployed on an Enterprise Ethereum Blockchan SHOULD be certified to conform to EthTrust Security Level 3 [[!EthTrust]].
The EthTrust Security Levels specification [[!EthTrust]] defines a set of checks for audits of smart contract security. Testing to Level 1 typically requires an automated static analysis, for which a number tools are available. Level 3 implies testing that the contracts audited are fit their declared purpose and use exemplary coding practices in addition to a careful audit for complex security issues potentially beyond the reach of a static code analysis.Enterprise Ethereum implementations can restrict operations based on permissioning and authentication schemes.
KeySec-010 All privileged keys MUST be managed according to NIST best practices [[!NIST-key-bp]].
KeySec-020 All privileged keys MUST be stored in an Hardware Security Manager.
KeySec-030 Granting or revoking authority to any individual over privileged keys MUST triggers changes in access to the relevant private key.
KeySec-040 A record of all people who have been granted access to privileged keys or had it revoked, with effective dates, MUST exist for level 3 certification.
KeySec-050 All privileged keys MUST be accessible to precisely one individual person.
This actively motivates the use of multiple-signature approaches over sharing access to a key, to guard against the possibility of a mission-critical individual being unavailable to sign at some point
ORGIDS-300: Enterprise Ethereum Blockchains MAY implement a smart contract based Organization Registry that provides cryptographic bindings between Ethereum accounts and their owning organization with identity proofs.
An Organization Registry follows the design outlined below.
A participating organization represents a collection of accounts and nodes that share a collective identity, for example they are owned by the same company, or they are held by officers of a particular organization. The participating organization is identified by an account called the root signing account.
ORGIDS-310: An Organization Registry MUST require all root entries to present an identity proof with:
ORGIDS-320: If an Enterprise Ethereum blockchain implements an Organization Registry, the transactionAllowed method MUST NOT allow any account except a root signing account to call the registerUser, registerNode, removeUser and removeNode methods of the Organization Registry smart contract at the address specified in the organizationRegistryContract network configuration parameter.
ORGIDS-330: An Organization Registry MUST support an extensibility mechanism to allow different types of proofs to be submitted and verified.
ORGIDS-340: An Organization Registry MUST support at least one of the following proof types:
ORGIDS-350: An Organization Registry MAY verify the proofs in the smart contract and immediately reject a registration that did not present a valid proof, or allow a registration to be validated or invalidated by an off-chain agent.
ORGIDS-360:If an Organization Registry performs proof validation in the smart contract, it MUST offer at least the following options to support different "freshness" requirements:
ORGIDS-370: Identity proofs MUST protect against re-use by a malicious party, by embedding a chain-unique challenge segment, such as the chain ID, in the signed claims inside the proof.
Since the proofs are available to all network participants, protection against taking a proof from one network and using it in a different network is essential. An issuer of an Identity proof signs an identity claim that includes a unique identifier for the network where the proof is issued.ORGIDS-380: A Registry for Organizational Accounts MUST not allow a registered proof to be used to register a new root entry.
Using an X.509 certificate as an illustration:Subject: CN=Acme Air-290528951 Issuer: CN=Acme Air | | (signed by) | Intermediate CA: Subject: CN=Acme Air Issuer: CN=SymantecIf the
CN value of the subject property contains the chain ID, 290528951,
then a malicious party will not be able to steal this certificate
and re-use it in a different blockchain network because the chain ID will not match.
It is imnpossible to modify the chain ID without the private key of the intermediate CA.
ORGIDS-390 The network configuration parameter
organizationRegistryContract MUST provide the address of
any Organization Registry.
Interface OrganizationalIDRegistry {// Establish a new organization in the registry. // The transaction sender needs to be recorded by the transactionAllowed // perimssioning method as the new Organization's root signing account. // Implementations can validate the proof inside the smart contract, and // cache certain aspects of the proof to the state that helps with faster checking for // administrative operations, such as expiration date.function registerOrganization(bytes32 orgID, bytes32 orgName, string proof) external;// endorse and register user account within the organization // the user account will be inserted under the root account in the identity treefunction registerUser(bytes32 metadata, address userAccount) external;// endorse and register a node within the organization // the enode ID will be inserted under the root account in the identity treefunction registerNode(bytes32 metadata, string enodeID) external;// marks the user account within the organization as deleted/inactive // the operation is only allowed with the root accountfunction removeUser(address userAccount) external;// marks the node within the organization as deleted/inactive // the operation is only allowed with the root accountfunction removeNode(string enodeID) external;//getOwningOrganizationreturns the root organization account // that owns a user account or node depending on the parameter passedfunction getOwningOrganization(address userAccount) external view returns (bytes32 orgID, bytes32 orgName);function getOwningOrganization(string enodeID) external view returns (bytes32 orgID, bytes32 orgName);// updates the proof for the organization's root accountfunction updateProof(address rootAccount) external view returns (string proof);// returns the proof for the organization's root account for verificationfunction getProof(address rootAccount) external view returns (string proof);// broadcast registered organizations for participants to download and inspect the proofevent OrganizationRegistered(bytes32 orgID, bytes32 orgName, address rootAccount, string proof);// broadcast registered usersevent UserRegistered(bytes32 orgID, address userAccount);// broadcast removed usersevent UserRemoved(bytes32 orgID, address userAccount);// broadcast registered nodesevent NodeRegistered(bytes32 orgID, string enodeID);// broadcast removed nodesevent NodeRemoved(bytes32 orgID, string enodeID); }
An Ethereum JSON-RPC API is used to communicate between ÐApps and nodes.
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.
The Node permissioning contract 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. The node permissioning contract can maintain a list of trusted nodes that are always allowed to connect, a list of untrusted nodes that are not allowed to connect, or use other information such as that provided by the organization registry to determine whether to allow a connection from a given node.
TheconnectionAllowed function returns a bytes32 type,
which is interpreted as a bitmask with each bit representing a specific
permission for the connection.
PERMIT-020 If the permissions for a blockchain are updated to revoke any
permission previously granted to nodes, the
node permissioning contract MUST emit a
NodePermissionsUpdated event containing an
addsRestrictions property with the value true. See
also [P] PERM-220:.
PERMIT-030 If the permissions for a blockchain are updated to grant any
new permissions for nodes the node permissioning contract MUST
emit a NodePermissionsUpdated event containing an
addsRestrictions property with the value false. See
also [P] PERM-230:.
PERMIT-070 The node connection rules MUST support both the IPv4 and IPv6 protocol versions.
The node connection rules support IPv4 and IPv6 addresses, and domain names, defined as valid host strings [[!url]]. TheconnectionAllowed function implements the following interface,
including the `NodePermissionsUpdated` event:
Interface
[
{
"name": "connectionAllowed",
"stateMutability": "view",
"type": "function",
"inputs": [
{
"name": "sourceEnode",
"type": "string"
},
{
"name": "source",
"type": "string"
},
{
"name": "sourceEnodePort",
"type": "uint16"
}
],
"outputs": [
{
"name": "result",
"type": "bytes32"
}
]
},
{
"type": "event",
"name": "NodePermissionsUpdated",
"inputs": [
{
"name": "addsRestrictions",
"type": "bool",
"indexed": false
},
{
"name": "addsPermissions",
"type": "bool",
"indexed": false
},
{
"name": "enodeId",
"type": "string",
"indexed": false
},
{
"name": "source",
"type": "string",
"indexed": false
},
{
"name": "port",
"type": "uint16",
"indexed": false
},
{
"name": "raftport",
"type": "uint16",
"indexed": false
},
{
"name": "orgId",
"type": "string",
"indexed": false
}
]
}
]
**Arguments**
- `sourceEnode`: 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.
**Event parameters**
- `enodeId`: The enode address of the node for which the permissions have changed.
- `source`: The valid host string [[!url]] of the node whose permissions have changed.
- `port`: The peer-to-peer listening port of the node for which the permissions have changed.
- `raftport`: If using raft as consensus protocol, the raft port of the node for which the permissions have changed.
- `orgId`: If using organizations, the relevant organization ID.
**Returns**
- `result`: A boolean value, where `true` represents granting permissions for a node to access the network.
CONFIG-040: A node permissioning contract with the
connectionAllowed function as defined in section
,
MUST be included in the genesis block (block 0),
available at the address specified in the network configuration
parameter nodePermissionContract.
The account permissioning contract controls which accounts are allowed to send transactions, and the type of transactions permitted.
transactionAllowed function 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, specified in Wei (10-18 ETH).
- `gasPrice`: The gas price included in this transaction, specified in Wei (10-18 ETH).
- `gasLimit`: The gas limit in this transaction specified in Wei (10-18 ETH).
- `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`: A value of `true` means the account submitting the transaction
has permission to submit it.
PERMIT-090 Account permissioning contracts MUST respond with a `bool` value of `true` for the case where the transaction is allowed, or `false` for the case where the transaction is not allowed.
PERMIT-100 Node permissioning contracts and Account permissioning contracts MUST be certified as conforming to EthTrust Security Level 2 [[!EthTrust]].
,PERMIT-103 Node permissioning contracts and Account permissioning contracts MUST be certified as conforming to EthTrust Security Level 3 [[!EthTrust]].
The EthTrust Security Levels specification [[!EthTrust]] defines a set of checks for audits of smart contract security. Testing to Level 2 is essentially a static analysis, typically incorporating skilled human judgement to augment automatic analysis. Level 3 implies testing that the contracts audited are fit their declared purpose and use exemplary coding practices in addition to a careful audit for complex security issues potentially beyond the reach of a static code analysis.
CONFIG-050 A permissioning contract with the transactionAllowed
function as defined in section ,
MUST be included in the genesis block (block 0),
available at the address specified in the network configuration parameter
transactionPermissionContract.
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:
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 implementations can also support off-chain trusted computing, enabling privacy during code execution.
Off-chain trusted computing uses a privacy-enhanced system to handle some of the computation requested by a transactions. Such systems can be hardware-based, software-based, or a hybrid, depending on the use case.
The EEA has developed Trusted Compute APIs for Ethereum-compatible trusted computing [[EEA-OC]].
Performance is an important requirement 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 blockchain implementers free to implement whatever strategies are appropriate. This Specification does not constrain experimentation to improve performance. 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.
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 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.
Permissioning is the property of a system that ensures operations are executed by and accessible to designated parties. For Enterprise Ethereum, node permissioning refers to controlling the ability of a node to join an Enterprise Ethereum blockchain, and account permissioning refers to controls on the ability of individual accounts to perform specific functions, defined in [[EEA-client]]. For example, an Enterprise Ethereum blockchain can allow only certain nodes to act as validators, and only certain accounts to deploy smart contracts.
Enterprise Ethereum provides a permissioned implementation of Ethereum supporting node permissioning and account permissioning.
PERMIT-035: The node permissioning contract SHOULD specify a list of static peer nodes to establish peer-to-peer connections with. See also [P] NODE-010: in the Client Specification.
PERMIT-040: The node permissioning contracts MUST manage a list of nodes allowed to connect to the blockchain through a transaction into a smart contract.
PERMIT-010: An Enterprise Ethereum blockchain account permissioning contract MUST enable listing a set of accounts that are permitted to interact with the blockchain. See also [P] PART-010: in the Client Specification.
PERMIT-050: The account permissioning contract MAY manage additional permissioning for an account to execute a value transfer transaction to a specified account.
PERMIT-060: The account permissioning contract MUST manage separate permissioning for an account to:
Permissioning contracts can use the Proxy / Updateable contract patttern, for example to ensure that it is possible to change the management functions if an Enterprise Ethereum Blockchain needs a system with more features. If a new node is trying to synchronise the entire chain, it is important that it can "replay" each transaction, including those that make changes to the management of permissioning.
PERMIT-080 Permissioning contracts that are updateable MUST NOT allow changes through a private transaction.
DOCUMT-010: Enterprise Ethereum blockchains MUST document any extension to the public Ethereum EVM op-code set [[!EVM-Opcodes]] that can be used in smart contracts in the EEA Opcode Registry. See also [P] EXEC-020: in the Client Specification.
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.
Network configuration refers to the collection of settings defined for a blockchain, such as which consensus algorithm to use, addresses of permissioning smart contracts, and so on.
CONFIG-010: Any limit on the size of smart contracts that can be deployed on an Enterprise Ethereum Blockchain MUST be specified by the maxCodeSize network configuration parameter, as defined in the section below. See also [P] SMRT-040: in the Client Specification.
maxCodeSize network configuration
parameter is to specify a limit in kilobytes for the size
of a smart contract that can be deployed by a transaction.
A transaction to deploy a smart contract larger than the current limit
is invalid.
The default value of the limit is implementation-dependent and determined by individual
Enterprise Ethereum clients. It is **at least** 24 kilobytes.
Smart contracts that have already been deployed to the chain can be executed
regardless of the current value of the limit. Deployed smart contracts
can be stopped from operating through the permissioning contract.
The value of the maxCodeSize parameter is either an integer,
specifying the limit directly, or a Javascript object, consisting of pairs of integers.
If the value is an object, for each pair of integers:
- the first number in the pair specifies the limit,
- the second number specifies the first block at which the associated limit applies.
A missing or non-integer value for the limit means the blockchain imposes
the default value.
A negative value for the limit means the blockchain imposes no limit.
A value of 0 for the limit means that any transaction to deploy a smart contract
is invalid: no new smart contract can be added to the blockchain.
A missing, negative or non-integer value for the block height is an error,
and clients will ignore any associated limit.
A value for the block height that is lower than a previous value is an error,
and clients will ignore any associated limit.
INTROP-010: Enterprise Ethereum blockchains MUST use one of the Clique Proof of Authority consensus algorithm [[!EIP-225]] or the QBFT consensus algorithm [[!QBFT]]. See also [P] CONS-092: and [P] CONS-093: in the Client Specification.
CONFIG-020: Enterprise Ethereum blockchains MUST specify the consensus algorithm in use, in its network configuration information. See also [P] CONS-110: in the Client Specification.
The genesis block is the first block of a blockchain. A hard fork is a permanent divergence from the previous version of a blockchain. nodes running previous versions are no longer accepted by the newest version. A hard fork block is the block that marks the start of a hard fork.The following is a list of terms defined in this Specification.