Ethereum Homestead 中文文档

_images/ethereum-homestead-documentation-logo.png

该文档是 Ethereum社区 的志愿者共同持续协作完成的。 尽管该文档并没有被 基金会 授权批准，但我们希望它依然会有所帮助。

另外，欢迎新的 贡献者加入。

目录

简介

以太坊是什么？

以太坊是一个全新开放的区块链平台，它允许任何人在平台中建立和使用通过区块链技术运行的去中心化应用。 就像比特币一样，以太坊不受任何人控制，也不归任何人所有——它是一个开放源代码项目，由全球范围内的很多人共同创建。 和比特币协议有所不同的是，以太坊的设计十分灵活，极具适应性。在以太坊平台上创立新的应用十分简便，随着Homestead的发布，任何人都可以安全地使用该平台上的应用。

下一代区块链

区块链技术是比特币的底层技术，这一技术第一次被描述是在中本聪2008年发表的白皮书“比特币：点对点电子现金系统”中。 区块链技术更多的一般性用途在原书中已经有所讨论，但直到几年后，区块链技术才作为通用术语出现。 一个区块链是一个分布式计算架构，里面的每个网络节点执行并记录相同的交易，交易被分组为区块。一次只能增加一个区块，每个区块有一个数学证明来保证新的区块与之前的区块保持先后顺序。 这样一来，区块链的“分布式数据库”就能和整个网络保持一致。个体用户与总账的互动（交易）受到安全的密码保护。由数学执行并编码到协议中的经济激励因素刺激着维持和验证网络的节点。

在比特币中，分布式数据库被设想为一个账户余额表，一个总账，交易就是通过比特币的转移以实现个体之间无需信任基础的金融活动。 但是随着比特币吸引了越来越多开发者和技术专家的注意，新的项目开始将比特币网络用于有价代币转移之外的其他用途。 其中很多都采用了“代币”的形式——以原始比特币协议为基础，增加了新的特征或功能，采用各自加密货币的独立区块链。 在2013年末，以太坊的发明者Vitalik Buterin建议能够通过程序重组来运行任意复杂运算的单个区块链应该包含其他的程序。

2014年，以太坊的创始人Vitalik Buterin, Gavin Wood和Jeffrey Wilcke开始研究新一代区块链，试图实现一个总体上完全无需信任基础的智能合约平台。

以太坊虚拟机

以太坊是可编程的区块链。它并不是给用户一系列预先设定好的操作（例如比特币交易），而是允许用户按照自己的意愿创建复杂的操作。 这样一来，它就可以作为多种类型去中心化区块链应用的平台，包括加密货币在内但并不仅限于此。

以太坊狭义上是指一系列定义去中心化应用平台的协议，它的核心是以太坊虚拟机（“EVM”），可以执行任意复杂算法的编码。 在计算机科学术语中，以太坊是“图灵完备的”。开发者能够使用现有的JavaScript和Python等语言为模型的其他友好的编程语言，创建出在以太坊模拟机上运行的应用。

和其他区块链一样，以太坊也有一个点对点网络协议。以太坊区块链数据库由众多连接到网络的节点来维护和更新。 每个网络节点都运行着以太坊模拟机并执行相同的指令。因此，人们有时形象地称以太坊为“世界电脑”。

这个贯穿整个以太坊网络的大规模并行运算并不是为了使运算更高效。实际上，这个过程使得在以太坊上的运算比在传统“电脑”上更慢更昂贵。 然而，每个以太坊节点都运行着以太坊虚拟机是为了保持整个区块链的一致性。去中心化的一致使以太坊有极高的故障容错性，保证零停机，而且可以使存储在区块链上的数据保持永远不变且抗审查。

以太坊平台本身没有特点，没有价值性。和编程语言相似，它由企业家和开发者决定其用途。 不过很明显，某些应用类型较之其他更能从以太坊的功能中获益。 以太坊尤其**适合那些在点与点之间自动进行直接交互或者跨网络促进小组协调活动的应用**。 例如，协调点对点市场的应用，或是复杂财务合约的自动化。 比特币使个体能够不借助金融机构、银行或政府等其他中介来进行货币交换。以太坊的影响可能更为深远。 理论上，任何复杂的金融活动或交易都能在以太坊上用编码自动且可靠地进行。 除金融类应用外，任何对信任、安全和持久性要求较高的应用场景————比如资产注册、投票、管理和物联网————都会大规模地受到以太坊平台影响。

以太坊如何工作？

以太坊合并了很多对比特币用户来说十分熟悉的特征和技术，同时自己也进行了很多修正和创新。

比特币区块链纯粹是一个关于交易的列表，而以太坊的基础单元是账户。 以太坊区块链跟踪每个账户的状态，所有以太坊区块链上的状态转换都是账户之间价值和信息的转移。账户分为两类：

  • 外部账户（EOAs），由私钥控制
  • 合约账户，由它们的合约编码控制，只能由外部账户（EOA）“激活”

于大部分用户来说，两者基本的区别在于外部账户是由人类用户掌控————因为他们能够控制私钥，进而控制外部账户。 而合约账户则是由内部编码管控。如果他们是被人类用户“控制”的，那也是因为程序设定它们被具有特定地址的外部账户控制，进而被持有私钥控制外部账户的人控制着。 “智能合约”这个流行的术语指的是在合约账户中编码————交易被发送给该账户时所运行的程序。 用户可以通过在区块链中部署编码来创建新的合约。

只有当外部账户发出指令时，合约账户才会执行相应的操作。 所以合约账户不可能自发地执行诸如任意数码生成或应用程序界面调用等操作—只有受外部账户提示时，它才会做这些事。 这是因为以太坊要求节点能够与运算结果保持一致，这就要求保证严格确定执行。

和比特币一样，以太坊用户必须向网络支付少量交易费用。 这可以使以太坊区块链免受无关紧要或恶意的运算任务干扰，比如分布式拒绝服务（DDoS）攻击或无限循环。 交易的发送者必须在激活的“程序”每一步付款，包括运算和记忆储存。费用通过以太坊自有的有价代币，以太币的形式支付。

交易费用由节点收集，节点使网络生效。这些“矿工”就是以太坊网络中收集、传播、确认和执行交易的节点。 矿工们将交易分组——包括许多以太坊区块链中账户“状态”的更新——分成的组被称为“区块”，矿工们会互相竞争，以使他们的区块可以添加到下一个区块链上。 矿工们每挖到一个成功的区块就会得到以太币奖励。这就为人们带来了经济激励，促使人们为以太坊网络贡献硬件和电力。

和比特币网络一样，矿工们有解决复杂数学问题的任务以便成功地“挖”到区块。 这被称为“工作量证明”。一个运算问题，如果在算法上解决，比验证解决方法需要更多数量级的资源，那么它就是工作证明的极佳选择。 为防止比特币网络中已经发生的，专门硬件（例如特定用途集成电路）造成的中心化现象，以太坊选择了难以存储的运算问题。 如果问题需要存储器和CPU，事实上理想的硬件是普通的电脑。 这就使以太坊的工作量证明具有抗特定用途集成电路性，和比特币这种由专门硬件控制挖矿的区块链相比，能够带来更加去中心化的安全分布。

如何使用该文档?

以太坊的使用: 基础指南

通过本节可以获取用户参与到以太坊项目中的基本方法。 首先，要想成为网络中的节点，需要运行一个以太坊客户端。 在 选择客户端 这一节中列出了多种实现， 同时针对不同的安装应选择什么样的客户端给出了建议。 连接到网络 会告诉你关于网络、连接故障排除和区块链同步的基本信息。 设立私有链等高级的网络主题可以在 测试网络 章节中找到。

Homestead的发布

Homestead是以太坊平台的第二个主要版本，也是以太坊发布的第一个正式版本。 它包括几处协议变更和网络设计变更，使网络进一步升级成为可能。 以太坊的第一个版本Frontier实际上是测试版，供开发者学习、试验并开始建立以太坊去中心化的应用和工具。

以太坊开发路线图里程碑

参见 这个网址 以获取最新信息。

如果你正在运行一个和实时网络连接的节点，非常有必要升级到一个兼容的客户端。 这些客户端及对应版本可从 以太坊客户端列表 中获得。 如果客户端不兼容，你会进入到错误的分叉，并无法和网络的其他部分同步。

以太坊区块链一旦到达1,150,000号区块，以太坊网络就会经历一个硬分叉，带来几项主要变更，这将在下一章节中阐述。

Homestead硬分叉变更

以太坊从狭义上来说，是一系列协议。 Homestead带来了几个反向不兼容的协议变更，进而要求硬分叉。 这些变更遵循 以太坊改进建议 流程， 主要包括以下几个内容：

  • EIP 2:
    • 通过交易创建合约的费用由21000增加到53000。用 CREATE 操作码通过合约来创建合约不受影响。
    • S值比 secp256k1n/2 大的交易签名现在被认定无效。
    • 如果创建合约时没有足够的gas用来支付给状态增加合约编码所需的最终gas费用，合约创建就会失败（例如，无gas可用）而不会留下一个空合约。
    • 改变算法难度调整
  • EIP 7: DELEGATECALL: 增加一个新的操作码, DELEGATECALL at 0xf4, 它和 CALLCODE 的概念相似，不过会把发送者和父作用域的价值发送到子作用域，比如，创建的调用与原始调用具有相同的发送者和价值。这就意味着合约可以通过信息存储通路，同时遵从父合约中的 msg.sender 和 msg.value 。这样对创建合约的合约来说是好事，但是不要重复那些存储gas的附加信息。参见对 EIP 7的评论
  • EIP 8: devp2p 向前兼容性符合健壮性原则 RLPx 发现协议和 RLPx TCP传输协议确保以太坊网路上使用的客户端软件可以应对将来的网络协议升级。对于以太坊的旧版本来说，网络协议升级并不被旧客户端所接受，发现接收到的hello数据包不是预期数据时，通信会被拒绝。这个升级意味着未来的客户端版本能够接受即将到来的网络升级和握手通信。

这些变化有以下几项好处:

  • EIP-2/1消除了通过交易创建合约的过量激励，通过交易创建的成本是21000，而通过合约创建的成本是32000。
  • EIP-2/1 在自杀式退款的帮助下修复了协议中的漏洞， 现在只用11664 gas就能实现简单的以太币价值转移。
  • EIP-2/2 修复了交易可塑性方面的担忧（不是安全性缺陷，是用户界面不便利性）
  • EIP-2/3 在合约创建过程中，建立了更加直观的"成功或失败"的区分，而不像现在"成功，失败或者空账户" 三分的情况。
  • EIP-2/4 将设置时间戳区别的过量激励消除到1，以便创建难度稍大的区块，进而保障搞定任何可能的分叉。这样就保证了出块时间维持在10-20范围，并且按照模拟可以恢复目标的15秒出块时间（现在有效时间是17秒）。
  • EIP-7 使合约更容易储存另一个地址，作为编码和"通过"调用的可变来源，子编码会和父编码在本质上相同的环境下执行（除非gas减少，调用栈深度增加）
  • EIP-8 确保以太坊网络上使用的所有客户端软件可以应对未来网络协议升级。

参考资料:

Web 3: 去中心化应用平台

很多人相信像以太坊这样一个公开、无需信任的区块链平台十分适合作为Web 3.0的共享"后端"， 像Web3.0这样去中心化、安全的互联网，它的核心服务， 比如DNS和数字身份是去中心化的，个体可以参与到经济互动中。

正如以太坊开发者希望的那样，以太坊是一张空白的帆布，你可以在上面创建任何你想要的东西。 以太坊协议的目的是普遍化，以使其核心特征能够以任意方式结合。 理想状态下，以太坊上的数据采集和处理程序会利用以太坊区块链来建立解决方案， 这些解决方案依靠去中心化的一致性提供以往无法实现的新产品和服务。

称以太坊为一个生态系统再合适不过了：核心协议由不同的基础设施、编码和社群支持， 他们共同构成了以太坊项目。你也可以通过观察使用以太坊的项目来理解以太坊。 现在已经有很多基于以太坊的项目已经非常引人注目了， 比如Augur，Digix，Maker和其他很多项目（参见 Dapps ）。 此外，还有开发团队建立了人人皆可使用的开源组件。 尽管这些组织都独立于以太坊基金之外，有各自的组织目标，但他们无疑对整个以太坊生态系统是有益的。

拓展视频/阅读:

智能合约

你愿意和从未谋面的人签合约吗？你会同意把钱借给埃塞俄比亚的农民吗？ 你愿意投资一个战乱地区由少数人管理的报纸吗？ 你会不嫌麻烦为了网上一次5美元的购买签一个有法律效力的合约吗？

大多数的答案都是否定的，原因是合约需要的基础太多了： 有时需要双方之间互相信任的工作关系，有时要依靠合法的工作体系、警察和律师费用。

在以太坊这些都不需要：如果合约所必需的要求都能放在区块链中， 那么就会放在区块链中，这是一个无需信任基础也几乎不用任何成本的环境。

不要想将你现有的合约转移到区块链中会麻烦， 想一想那些因为经济上不可行或是没有足够法律保护而被你拒绝的成千上万的小合约吧。

DAO

这里简单地举个例子：想象一下你和朋友有个小生意。 律师和会计费用很贵，完全信任让一个单独的合伙人来看管账簿可能让你精神很紧张（这甚至可能是个诈骗的机会）。 你可以尝试一下多个合伙人共同看管账簿，但只要协议没有被严格遵守，就可能导致诈骗发生。

使用智能合约，公司的所有权和基金分配的条款可以在一开始就详细规定。 智能合约签署的方式是，只有大部分拥有者批准，合约才可以变更。 这样的智能合约可以像开源软件一样获取，你甚至都不必雇佣自己的程序员来代替会计和律师。

这样的智能合约可以立即按比例决定分配。几个年轻人分配柠檬水站收入， 可以像主权基金给拥有基金的亿万公民分配收益一样透明。 在这两个案例中，这种透明性带来的花费可能每美元连一美分都不到。

以太坊的历史

近期的以太坊历史记录， 可参考 Taylor Gerring的博客文章。

诞生

2013年末Vitalik Buterin第一次描述了以太坊，作为他研究比特币社群的成果， 不久后，Vitalik发表了 以太坊白皮书， 他在书中详细描述了以太坊协议的技术设计和基本原理，以及智能合约的结构。 2014年1月，Vitalik在美国佛罗里达州迈阿密举行的北美比特币会议上正式宣布了以太坊。

与此同时，Vitalik开始和Gavin Wood博士合作共同创建以太坊。 2014年4月， Gavin发表了 以太坊黄皮书， 作为以太坊虚拟机的技术说明。按照黄皮书中的具体说明， 以太坊客户端已经用7种编程语言实现（C++, Go, Python, Java, JavaScript, Haskell, Rust），使软件总体上更加优化。

以太坊基金和以太币预售

除开发以太坊软件外，要发布新的加密货币和区块链，需要大量的辅助程序努力来组装启动和运行所需要的资源。 为了快速建立一个包括开发者、矿工和其他利益相关方的大型网络，以太坊宣布了一个以太币（以太坊货币单位）预售计划。 通过预售筹募基金的法律和金融复杂性导致了几个法律实体的诞生， 包括2014年6月在瑞士楚格建立的以太坊基金（Stiftung Ethereum）。

从2014年6月开始，以太坊借助42天公开的以太币预售活动对第一批以太币进行了分配， 净赚31,591比特币，当时价值 18,439,086 美元，交换出大约60,102,216以太币。 销售所得首先用于偿还日益增加的法律债务，回报开发者们数月以来的努力，以及资助以太坊的持续开发。

ETH/DEV和以太坊开发

以太币预售成功之后，以太坊的开发在非营利组织ETH DEV的管理下走向正式化， 它依据Ethereum Suisse的合约管理以太坊开发————Vitalik Buterin，Gavin Wood和Jeffrey Wilcke作为组织的3个主管。 2014年间开发者对以太坊的兴趣持续稳定增长，ETH DEV团队发布了一系列概念验证(PoC)供开发者社群进行评估。 ETH DEV团队在 以太坊博客 频繁的发帖也保持了以太坊对公众注意力的持续吸引和强劲的发展势头。 以太坊论坛和以太坊reddit分支上渐增的访问量和用户基础证明平台正在引起一个快速增长和热衷于此事业的开发者社群的兴趣， 这一趋势一直延续至今。

DEVCON-0

2014年4月, ETH DEV组织了 DEVCON-0 活动 ， 世界各地的以太坊开发者聚集在柏林，讨论各种以太坊技术议题。DEVcon-0的一些陈述和会议后来驱使以太坊向更加可靠、 更安全和更加可扩展的方向发展。总体来说，这一活动激励了开发者为发布以太坊这一目标继续努力。

DEVgrants项目

2015年4月，DEVgrants项目 发布， 这个项目为所有对以太坊平台和基于以太坊的项目所做的贡献提供基金。 成百上千的开发者为以太坊项目和开源项目贡献了时间和智慧。这一项目旨在奖励和扶持开发者们所做的努力。 DEVgrants项目时至今日仍在运行，项目基金情况最近一次更新是在2016年1月。

Olympic测试网，漏洞报告奖励和安全审查

2014年和2015年的开发经历了一系列概念验证发布，带来了第九届POC公开测试网，被称为Olympic。 开发者社群 受邀进行网络极限测试 ， 大量的奖励资金被分配给保持着不同记录或以某种方式成功攻破系统的人。 发布一个月之后，官方公布了 获奖名单 。

2015年早期，以太坊奖励项目 启动，奖励那些发现以太坊软件栈任何弱点的人BTC奖金。 这无疑有利于以太坊的可靠性，安全性和以太坊社群技术上的自信。这一奖金项目至今仍然活跃， 并没有结束的计划。

以太坊安全审查开始于2014年末，持续到2015年上半年。 以太坊请了很多第三方软件安全公司对所有协议关键的组成部分（以太坊 VM，网络，工作量证明）开展端对端审查。 审查发现了很多安全问题，问题提出并再次检测后，带来了一个更安全的平台。

以太坊Frontier启动

以太坊Frontier网络于2015年7月30日启动，开发者开始编写智能合约和去中心化应用以部署在以太坊实时网络上。 此外，矿工们开始加入以太坊网络以帮助保障以太坊区块链的安全并从挖矿区块中赚取以太币。 尽管Frontier的发布是以太坊项目的第一个里程碑，开发者们只试图将其作为测试版本， 但结果它比任何人预期得都更有用且可靠，开发者们立即开始建立解决方案，改进以太坊生态系统。

另请参阅:

DEVCON-1

第二次开发者会议 DEVCON-1 于2015年11月初在伦敦举办。 5天的会议进行了100多次陈述，专题讨论会和快速讨论，吸引了400多名参会者， 包括开发者，企业家，思考者和业务主管。 所有的演讲都有视频资料并可 免费获取 。

像UBS，IBM和微软这样的大公司明确表示了公司对这一技术的兴趣。 微软宣称将在 新的区块链即服务上支持以太坊 以作为微软Azure云平台上的服务。 这一公告标志着以太坊为中心的区块链技术成为主流的时刻，将和DEVCON-1一样被铭记。

社区

发起讨论和问问题时，请正确选择论坛，并维护论坛环境整洁。

Reddit

以太坊reddit分论坛是最全面的以太坊论坛，这里是大部分社区讨论发生的地方和核心开发者最活跃的地方。 如果你想对新闻、媒体、报道、公告、头脑风暴进行一般的讨论，选这个论坛就对了。 一般来讲，这里有与更广泛社区相关的一切以太坊事件。

讨论完全免费。

但这个论坛不适合寻求实际帮助或者得到迅速明确的答复（如果有以上两方面需求，可分别使用 Gitter Rooms 和 Stack Exchange ）

发帖前请阅读 以太坊subreddit规定 。

更多专业subreddits:

  • /r/EthTrader - 以太币交易、价格和市场
  • /r/EtherMining - 关于以太币挖矿的讨论
  • /r/Ethmarket - 个人用实物和服务交换以太币的市场
  • /r/Ethinvestor - 以太坊投资新闻和前景，以及以太坊市场发展的长期趋势
  • /r/ethereumism/ - A bit more ism, ostic, ical, ist and tinfoil hats, pyramids and crystal ball type of views - the ethereal side of Ethereum

Stack Exchange

以太坊Stack Exchange 是StackExchange网络问答社区的一部分。 StackExchange是免费的问答网站，网站上所有的问题和答案都会为后人保存下来。

这是最适合询问技术问题的网站。可以通过回答问题来帮助以太坊同仁们，增加威望值。

Gitter Rooms

日常聊天可以选择Gitter。这是开发者们的虚拟公用工作空间，如果有需要，在这里你可以迅速得到帮助和一些支持。

Gitter 使用Github账户，提供Github集成（pull请求通知等），个人频道，Markdown格式化等。

大部分Gitter频道都围绕特定的资源库或是研究管理这类一般议题组织的。请选择合适的房间，保持讨论话题的相关性。

查阅 以太坊组织gitter房间完整列表 。以下是活跃的公开频道列表：

  • go-ethereum - 关于geth（以及与go实现相关的工具）
  • cpp-ethereum - 关于eth（以及与C++实现相关的工具）
  • web3.js - 关于web3.js，以太坊JavaScritpt API库
  • Solidity - Solidity合约相关编程语言
  • serpent - 用于合约开发的Serpent语言
  • mist - GUI dapp browser, 官方钱包应用
  • light-client - 关于light客户端和LES协议
  • research - 以太坊研究
  • governance - 关于开发者管理
  • whisper - 匿名数据电报发表
  • swarm - 去中心化的内容存储和分配网络
  • EIPs - Ethereum Improvement Proposals 讨论
  • ethereumjs-lib - 以太坊核心 JavaScript 库
  • devp2p - ÐΞV's p2p 网络协议及框架

以太坊改进协议 (EIPs)

以太坊改进协议计划旨在成为协调协议改进的框架和非正式商业流程。 人们会首先向以太坊改进协议资源库提出想法作为一个问题或pull请求。 经过基本的过滤，提议会收到一个数字并以草稿的形式发布。必须经过社区一致同意，以太坊改进协议才能变成活跃状态。 提出的改变应该考虑到最终的同意取决于以太坊用户的共识。 对于以太坊改进协议的讨论，可进入 gitter channel for EIP discussions 。

作废声明

Skype

一些社区讨论会仍然在使用skype房间，但是我们想取消这一途径，并推荐大家使用 gitter 或 slack。

Ethereum Forum

Stephan Tual的 以太坊论坛 将不再维护，可能很快就会停用。我们鼓励大家使用以上列出的推荐选择。

以太坊基金会

以太坊基金会是在瑞士注册的非营利性机构，旨在管理以太币销售中筹措的基金，以更好地为以太坊和去中心化技术生态系统服务。

Stiftung Ethereum于2014年6月在瑞士创建，它的使命是促进新技术和应用的开发，尤其是在新的开放的、去中心化的软件架构领域。

它的目标是开发、培育、促进和维护去中心化、开放的技术。 它主要但并非唯一的重心是促进以太坊协议和相关技术的开发，以及扶持使用以太坊技术及协议的应用。 此外Stiftung Ethereum还会通过各种方式支持去中心化的因特网。

查看 基金会管理团队网页 获取更多信息。

以太坊基金会面向社区的门户

以太坊基金会的正式照会通常在 以太坊博客 上以综合性发帖的形式呈现。 有些发贴是技术性的，有些是组织性的，还有一些是私人的。所有的博客发贴都会在 Twitter 和 Reddit. 上宣布。

Youtube 频道 里，包含了开发者会议DEVCON0和DEVCON1上的所有视频。

欲了解社区讨论论坛, 参见 社区.

以太坊客户端

选择客户端

为什么有多个以太坊客户端?

项目早期，在众多不同的操作系统中就有多个可以彼此协作的客户端实现。 客户端的多样性对于整个生态系统来说是巨大的成功。 它使我们能够证明协议(参见 黄皮书 )是明确清晰的， 为创新打开大门，也让我们都保持诚实。但是对终端用户来说，没有通用的"以太坊安装程序"可供他们使用，可能引起他们的困惑。

自2016年9月起，主导的客户端实现为 go-ethereum 和 Parity 。

客户端 语言 | 开发者 | 最新版本
go-ethereum Go Ethereum Foundation go-ethereum-v1.4.18
Parity Rust Ethcore Parity-v1.4.0
cpp-ethereum C++ Ethereum Foundation cpp-ethereum-v1.3.0
pyethapp Python Ethereum Foundation pyethapp-v1.5.0
ethereumjs-lib Javascript Ethereum Foundation ethereumjs-lib-v3.0.0
Ethereum(J) Java <ether.camp> ethereumJ-v1.3.1
ruby-ethereum Ruby Jan Xie ruby-ethereum-v0.9.6
ethereumH Haskell BlockApps no Homestead release yet

台式机/笔记本电脑上应该安装什么?

大部分的用户只需要安装 Mist / 以太坊钱包 就能满足使用需求。

以太坊钱包是**Mist浏览器**"单独的DApp"部署方式，它将成为Homestead之后Metropolis开发的核心。

Mist附有绑定的 go-ethereum 和 cpp-ethereum 二进制。 如果Mist开启的时候，你没有在运行命令行以太坊客户端，它就会运行其中一个绑定的客户端（默认为 geth ）进行同步区块链。 如果希望使用Parity和Mist，或在一个私有网络中运行Mist，只需要在Mist运行前前启动你的节点， 此时，Mist不会启动它自己的节点，而是连接你的节点。

添加Parity、其他客户端以及Mist作为“一等实体”的工作正在进行

如果你想在命令行和以太坊互动，并且利用JavaScript控制台，那么你会想直接安装一个客户端软件以及Mist。 可从上文中表格中的链接获取详细信息。

如你想要挖矿，那么Mist不能满足需求。请参阅 挖矿 部分。

手机/平板电脑上应该安装什么?

移动设备上的软件支持还在起步阶段。Go团队正在发布试用的iOS和安卓程序库， 一些开发者正在用程序库开始研究手机应用辅助程序，但是目前还没有任何可用的以太坊手机客户端。

在移动设备上使用以太坊最主要的障碍是Light客户端支持尚不完备。 已完成的工作成果在私有分支上关闭，只在Go客户端上可用。 Doublethinkco将在接下来的几个月开始为C++客户端开发Light客户端，接下来会有资金支持。

查看 Status.im, 它最先使用了 Ethereum(J) 的 ethereumj-personal 但是最近跳转到了和Light客户端的Geth交叉构建。

单板计算机（SBC）上应该安装什么?

按照技术水平的不同，以及你想要达到的目的，可以有不同的选择。

  • 下载一个完整的安装镜像（链接到有具体下载和安装说明的页面）
    • 如果你刚开始使用以太坊AND SBC板，诸如树莓派，那么这就是为你准备的！只需要下载你正在使用的开发板的特定安装镜像，刻录到SD卡上，启动设备。运行以太坊！
  • 下载一个预编译的应用（链接到有具体下载和安装说明的页面）
    • 如果你已经有SBC运行，并且有特定、偏好的OS或是想保留的设置，这是你的最佳选择！你可以只根据平台，下载合适的可执行文件，只需最少的资源库链接和PATH设置，就能运行以太坊！
  • 下载一个预编译的应用（链接到详细说明与SBC链接 https://github.com/ethembedded)
    • 想要运行定制的安装程序？ 我们有可以从设备的源上编译的描述语言。我们的描述语言包含自动安装依赖的软件以及客户端本身。这就使你能够安装以太坊客户端的特定版本（比如"develop"， "master"等），编译你自己的客户端分叉版本，尝试创建程序中的各种复杂的问题找到最佳解决方案。

客户端交互

如需通过编程与以太坊客户端进行交互，请参见 连接到以太坊客户端 。

cpp-ethereum

_images/cpp_35k9.png _images/ETHEREUM-ICON_Black.png

快速入门

详情

Current status

We blog about the codebase periodically on the Official Ethereum blog and elsewhere. Here are some recent articles from the development team:

We simplified the project naming at Homestead (March 2016), although some naming shadows of the past still linger. With the homecoming we have another name to retire - webthree-umbrella.

At the time of writing (August 2016), we are just completing our "Homecoming", where the code has been reconsolidated into the ethereum/cpp-ethereum repository. From October 2015 until August 2016 it was split across multiple repositories under ethereum/webthree-umbrella

The re-licensing plan is the culmination of a very long-term plan to liberalize the core. An effort was begun in 2015 to re-license the cpp-ethereum core as MIT, but it was never completed.

This is a revival of that effort, especially with a view towards the potential for collaboration with the Linux Foundation's Hyperledger project, and with other corporations outside of Hyperledger who wish to build Ethereum private/consortium chain solutions similar to HydraChain. The Rubix by Deloitte project is an example of that approach.

Building from source
Overview

The cpp-ethereum codebase lives on Github.com in the cpp-ethereum repository.

Between October 2015 and August 2016 it was split into various repositories which were grouped as sub-modules under the webthree-umbrella repository, and you will likely see many references to webthree-umbrella online. Those all refer to the cpp-ethereum codebase during that period of its development.

We use a common CMake build system to generate platform-specific build files, meaning that the workflow is very similar whatever operating system you use:

  • Install build tools and external packages (these are platform dependent)
  • Clone the source code from the webthree-umbrella git repository
  • Run CMake to generate a build file (makefile, Visual Studio solution, etc)
  • Build it
Platform-specific instructions
Building for Linux
Getting the source code

We use git and GitHub to maintain the source code. Clone the repository by:

git clone --recursive https://github.com/ethereum/cpp-ethereum.git
cd cpp-ethereum

The --recursive option is important. It orders git to clone additional submodules which are required to build the project. If you missed it you can correct your mistake with command git submodule update --init.

CMake

We use CMake to control the build configuration of the project. Quite recent version of CMake is required (at the time of writing 3.4 is the minimum). We recommend installing CMake by downloading and unpacking the binary distribution of the latest version available on the download page:

https://cmake.org/download/

Alternative method

The repository contains the script install_cmake.sh that downloads a fixed version of CMake and unpacks it to the given directory prefix. Example usage scripts/install_cmake.sh --prefix /usr/local.

Installing dependencies

The following libraries are required to be installed in the system:

  • boost
  • leveldb
  • curl
  • microhttpd
  • miniupnp
  • gmp

They usually can be installed using distribution-specific package manager. For example on Debian-based systems:

sudo apt-get install libboost-all-dev libleveldb-dev libcurl4-openssl-dev libmicrohttpd-dev libminiupnpc-dev libgmp-dev

or on RedHat-based systems:

dnf install boost-devel leveldb-devel curl-devel libmicrohttpd-devel miniupnpc-devel gmp-devel

Linux has a horror-show of fragmentation when it comes to packaging systems.

We support a "one-button" bash script which attempts to make this minefield more navigable for users of common distros. It identifies your distro and installs the external packages which you will need, using whatever combination of package servers and build-from-source is required for your specific distro version. This is a non-trivial task, but by that token is also something which we don't want anybody to have to replicate themselves.

scripts/install_deps.sh

We use the same script for automated builds and continuous integration, so it is continuously tested, which is especially important on MacOS, where Homebrew is a constantly moving target.

If you try it, and it doesn't work for you, please report the problem with details of your distro, your version number and any other important details and we can work together to get it working for your use-case.

We have manual instructions for Fedora, openSUSE and Arch Linux (see below). If you using some other distro then please contact us and we'll see if we can get you going.

Installing dependencies for Fedora
Fedora 24

Steps:

dnf install git automake autoconf libtool cmake gcc gcc-c++ xkeyboard-config \
        leveldb-devel boost-devel gmp-devel cryptopp-devel miniupnpc-devel \
        qt5-qtbase-devel qt5-qtdeclarative-devel qt5-qtquick1-devel qt5-qtwebkit-devel \
        mesa-dri-drivers snappy-devel ncurses-devel readline-devel curl-devel \
        python-devel jsoncpp-devel argtable-devel libmicrohttpd-devel

Make sure you have cloned the repository recursively. If not please clone the submodules of the respository as well. It may happen that after # make install, you might not be able to run eth because of linking errors. In that case you have to add the shared objects of eth into your load path for shared objects.

Installing dependencies for openSUSE

Here is how to get the dependencies needed to build the latest webthree-umbrella on OpenSUSE. This was done on Leap 42.1 and 42.2, but there should be equivalent packages available for Tumbleweed and 13.x.

First install dependencies provided by the main repos:

zypper in git automake autoconf libtool cmake gcc gcc-c++ \
    xkeyboard-config leveldb-devel boost-devel gmp-devel \
    libcryptopp-devel libminiupnpc-devel libqt5-qtbase-common-devel \
    libqt5-qtdeclarative-devel libQtWebKit-devel libqt5-qtwebengine-devel \
    libQt5Concurrent-devel Mesa ncurses-devel readline-devel libcurl-devel \
    llvm llvm-clang llvm-clang-devel llvm-devel libLLVM binutils \
    libmicrohttpd-devel jsoncpp-devel opencl-headers-1.2 zlib-devel
If Opencl-headers-1.2 is not found, you can install it manually from the CLI:
zypper addrepo http://download.opensuse.org/repositories/home:valmar73:crystfel-releases/openSUSE_13.1/home:valmar73:crystfel-releases.repo zypper refresh zypper install opencl-headers-1.2

It may be possible to use the generic libOpenCL1, but I have only tested with the AMD proprietary package from the AMD drivers repo fglrx64_opencl_SUSE421

These packages are not in the standard repos but can be found using the OpenSUSE build service package search and YaST 1-Click Install:

  • libargtable2-devel
  • libv8-3
  • v8-devel

If you also have v8 from the chromium repo installed the devel package will default to the 4.x branch which will not work. Use YaST or zypper to downgrade this package to 3.x

Note that Opencl-headers is used to mine the chain with GPU. If this is not a requirement, you can bypass it when creating the makefile (cmake -DETHASHCL=0 .. ) instead of (cmake ..)

Installing dependencies for Arch Linux

Compiling webthree-umbrella on Arch Linux requires dependencies from both the official repositories and the Arch User Repository (AUR). To install packages from the official repositories pacman is used. For installation of packages from the AUR, a number of AUR helpers is available. For this guide, yaourt AUR helper is used.

Installing dependencies

# from official repositories sudo pacman -Sy git base-devel cmake boost crypto++ leveldb llvm miniupnpc libcl opencl-headers libmicrohttpd qt5-base qt5-webengine

# from AUR yaourt -Sy libjson-rpc-cpp

Compiling the source code

During this step, an installation folder for the Ethereum can be specified. Specification of the folder is optional though. If not given, the binary files will be located in the build folder. However, for this guide, it is assumed that the Ethereum files will be installed under /opt/eth. The reason for using /opt is that it makes much easier to delete the Ethereum files later on, as compared to having them installed under, e.g., /usr. Also /opt is commonly used to install software that is not managed by packaging systems, such as manually compiled programs.

# enter webthree-umbrella folder after cloning its github repository
cd webthree-umbrella

# make a build folder and enter into it
mkdir -p build && cd build

# create build files and specify Ethereum installation folder
cmake .. -DCMAKE_INSTALL_PREFIX=/opt/eth

# compile the source code
make

# alternatively it is possible to specify number of compilation threads
# for example to use 4 threads execute make as follows:
# make -j 4

# install the resulting binaries, shared libraries and header files into /opt
sudo make install

After successful compilation and installation, Ethereum binaries can be found in /opt/eth/bin, shared libraries in /opt/eth/lib, and header files in /opt/eth/include.

Specifying Ethereum libraries path

Since Ethereum was installed in /opt/eth, executing its binaries can result in linker error due to not being able to find the Ethereum shared libraries. To rectify this issue, it is needed to add the folder containing Ethereum shared libraries into LD_LIBRARY_PATH environmental variable:

# update ~/.bashrc
echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/eth/lib" >> ~/.bashrc

# reload ~/.bashrc
source ~/.bashrc
Build on the command-line

When you have installed your dependencies you can build.

mkdir build                                              Make a directory for the build output
cd build                                                 Switch into that directory

cmake ..                                                 To generate a makefile.
make                                                     To build that makefile on the command-line
make -j<number>                                          (or) Execute makefile with multiple cores in parallel
32-bit Linux builds

We have cpp-ethereum building and running successfully on many 32-bit Linux distros, with the main constraint being the availability of external dependencies in 32-bit variants. Probably the most active demand here is for single-board computers like the Raspberry Pi family.

You will need to disable the JIT and the heavy-weight LLVM dependency which comes with that. EVMJIT only supports x86_64. Other than that, cpp-ethereum should "just work" on 32-bit platforms. To disable JIT, you will need to use the following command for the Makefile generation phase:

cmake .. -DEVMJIT=Off
Building for Windows

We support only 64-bit builds and only for the following versions of Windows:

It may be possible to get the client working for Windows 32-bit, by disabling EVMJIT and maybe other features too. We might accept pull-requests to add such support, but we will not put any of our own development time into supporting Windows 32-bit builds.

Pre-requisites

You will need to install the following dependencies

Software Notes
Git for Windows Command-line tool for retrieving source from Github.
CMake Cross-platform build file generator.
Visual Studio 2015 C++ compiler and dev environment.
Get the source

Clone the git repository containing all the source code by executing the following command:

git clone --recursive https://github.com/ethereum/cpp-ethereum.git
cd cpp-ethereum
Get the external dependencies

Execute the CMake script that downloads and unpacks pre-built external libraries needed to build the project:

scripts\install_deps.bat
Generate Visual Studio project files

Then execute the following commands, which will generate a Visual Studio solution file using CMake:

mkdir build
cd build
cmake -G "Visual Studio 14 2015 Win64" ..

Which should result in the creation of cpp-ethereum.sln in that build directory.

NOTE: We only support Visual Studio 2015 as of cpp-ethereum-v.1.3.0. If you don't have it already, install the `Visual C++ 2015 Build Tools <http://landinghub.visualstudio.com/visual-cpp-build-tools>`_

Double-clicking on that file should result in Visual Studio firing up. We suggest building RelWithDebugInfo configuration, but all others work.

Build on the command-line

Alternatively, you can build the project on the command-line, like so:

cmake --build . --config RelWithDebInfo
Building for OS X
Overview - Here be dragons!

It is impossible for us to avoid OS X build breaks because Homebrew is a "rolling release" package manager which means that the ground will forever be moving underneath us unless we add all external dependencies to our Homebrew tap, or add them as git sub-modules. End-user results vary depending on when they are build the project. Building yesterday may have worked for you, but that doesn't guarantee that your friend will have the same result today on their machine. Needless to say, this isn't a happy situation.

If you hit build breaks for OS X please look through the Github issues to see whether the issue you are experiencing has already been reported. If so, please comment on that existing issue. If you don't see anything which looks similar, please create a new issue, detailing your OS X version, cpp-ethereum version, hardware and any other details you think might be relevant. Please add verbose log files via gist.github.com or a similar service.

The cpp-ethereum-development gitter channel is where we hang out, and try to work together to get known issues resolved.

We only support the following OS X versions:

The cpp-ethereum code base does not build on older OS X versions and this is not something which we will ever support. If you are using an older OS X version, we recommend that you update to the latest release, not just so that you can build cpp-ethereum, but for your own security.

Clone the repository

To clone the source code, execute the following command:

git clone --recursive https://github.com/ethereum/cpp-ethereum.git
cd cpp-ethereum
Pre-requisites and external dependencies

Ensure that you have the latest version of xcode installed. This contains the Clang C++ compiler, the xcode IDE and other Apple development tools which are required for building C++ applications on OS X. If you are installing xcode for the first time, or have just installed a new version then you will need to agree to the license before you can do command-line builds:

sudo xcodebuild -license accept

Our OS X builds require you to install the Homebrew package manager for installing external dependencies. Here's how to uninstall Homebrew, if you ever want to start again from scratch.

We now have a "one button" script which installs all required external dependencies on macOS and on numerous Linux distros. This used to a multi-step manual process:

./scripts/install_deps.sh
Command-line build

From the project root:

mkdir build
cd build
cmake ..
make -j4             (or different value, depending on your number of CPU cores)
Install your own build

You can also use the same Makefile to install your own build globally on your machine:

make install

This will install binaries into /usr/local/ and /usr/bin/.

Generate xcode project

From the project root:

mkdir build_xc
cd build_xc
cmake -G Xcode ..

This will generate an Xcode project file called cpp-ethereum.xcodeproj, which you can then open with xcode and build/debug/run.

Building for FreeBSD

NOTE - Once the packages are in the FreeBSD main ports this guide should be changed to something much more simple

Install the ports manually

For some of this steps you must require a root access to modify the ports directory.

The webthree-umbrella depends on [libjson-rpc-cpp.shar](https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/libjson-rpc-cpp.shar) that is also not in the ports system.

First you need to download the shar file and place it on your ports directory under the "devel" session, usually /usr/ports/devel

curl https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/libjson-rpc-cpp.shar > /usr/ports/devel/libjson-rpc-cpp.shar

Now we execute the script with:

cd /usr/ports/devel
sh libjson-rpc-cpp.shar

This will create the libjson-rpc-cpp port. Now you should do the same for the webthree-umbrella port, we should get the [webthree-umbrella](https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/webthree-umbrella.shar) file and create the port under "net-p2p" directory.

curl https://raw.githubusercontent.com/enriquefynn/webthree-umbrella-port/master/webthree-umbrella.shar> /usr/ports/net-p2p/webthree-umbrella.shar
cd /usr/ports/net-p2p
sh webthree-umbrella.shar
Build and Install

Now you can navigate to the webthree-umbrella directory and install the port:

cd /usr/ports/net-p2p/webthree-umbrella
make install clean
Building for Android

We don't currently have a working Android build, though that is on the roadmap for doublethinkco. Android uses the Linux kernel, but has a different API than the ARM Linux cross-builds, meaning that specific binaries will be required.

ARM Linux distros use the GLIBC runtime library, where Android uses bionic.

Building for iOS

We don't currently have a working iOS build, though that is on the roadmap for doublethinkco. iOS is a UNIX-like operating system based on Darwin (BSD) using ARM chips. This is a different API than the ARM Linux cross-builds, meaning that specific binaries will be required.

Building for Raspberry Pi Model A, B+, Zero, 2 and 3

EthEmbedded maintain build scripts for all Raspberry Mi models. They are on Github in the Raspi-Eth-Install repository. It is also possible to cross-build for these platforms.

Building for Odroid XU3/XU4

EthEmbedded maintain build scripts for both of these Odroid models. Support for a broader range of Odroid devices is likely in the future. They are on Github in the OdroidXU3-Eth-Install repository. It is also possible to cross-build for these platforms.

Building for BeagleBone Black

EthEmbedded maintain build scripts for BBB on Github in the BBB-Eth-Install repository. It is also possible to cross-build for this platform.

Building for WandBoard

EthEmbedded maintain build scripts for the WandBoard on Github in the WandBoard-Eth-Install repository. It is also possible to cross-build for this platform.

Building for Linux for ARM (cross builds)

doublethinkco maintain a Docker-based cross-build infrastructure which is hosted on Github in the cpp-ethereum-cross repository.

At the time of writing, these cross-built binaries have been successfully used on the following devices:

  • Jolla Phone (Sailfish OS)
  • Nexus 5 (Sailfish OS)
  • Meizu MX4 Ubuntu Edition (Ubuntu Phone)
  • Raspberry Pi Model B+, Rpi2 (Raspbian)
  • Odroid XU3 (Ubuntu MATE)
  • BeagleBone Black (Debian)
  • Wandboard Quad (Debian)
  • C.H.I.P. (Debian)

Still TODO:

  • Tizen
  • Android
  • iOS
Installing binaries

The cpp-ethereum development team and the broader Ethereum community publish binary releases in many different forms for a variety of platforms. This aims to be a complete list of those releases.

If you are aware of other third-party packaging efforts, please let us know on the cpp-ethereum gitter channel, and we will add them to this list.

Docker

We are hosting latest development snapshots (and in the future also releases) at docker hub. You can run these images as follows:

Preparation

Before running the image, you should pull the latest version and prepare the data directories:

# get the lastest version from dockerhub (redo for updates).
docker pull ethereum/client-cpp
# create mountable datadirs; blockchain/account data will be stored there
mkdir -p ~/.ethereum ~/.web3

These steps need to be done only once. For upgrading to a new version do the docker pull ... again.

Execution

The simplest version is to run:

docker run --rm -it \
    -p 127.0.0.1:8545:8545 \
    -p 0.0.0.0:30303:30303 \
    -v ~/.ethereum:/.ethereum \
    -v ~/.web3:/.web3 \
    -e HOME=/ \
    --user $(id -u):$(id -g) \
    ethereum/client-cpp

This will write data to ~/.ethereum and ~/.web3/ on your host and run the client with your user's permissions. For most cases this should be sufficient and the client should behave exactly as if run from a local build.

If you want the rpc port reachable from the network (not recommended, never do this if you have valuable data or private keys on your machine), replace -p 127.0.0.1:8545:8545 by -p 0.0.0.0:8545:8545.

For convenience, you can create the file /usr/local/bin/docker-eth with the following content:

#!/usr/bin/env sh
mkdir -p ~/.ethereum ~/.web3
if ! id -nG $(whoami)|grep -qw "docker"; then SUDO='sudo'; else SUDO=''; fi
$SUDO docker run --rm -it \
    -p 127.0.0.1:8545:8545 \
    -p 0.0.0.0:30303:30303 \
    -v ~/.ethereum:/.ethereum \
    -v ~/.web3:/.web3 \
    -e HOME=/ \
    --user $(id -u):$(id -g) \
    ethereum/client-cpp $@

And make it executable with chmod +x /usr/local/bin/docker-eth. Now you can start the client with:

docker-eth

Note: The docker-eth command will accept the same flags as the raw eth command.

If you want to attach to the node, you can either just use mist (it will detect the node automatically), use geth attach ipc:/$HOME/.ethereum/geth.ipc or ethereum-console as described in Running.

Advanced usage:

Due to https://github.com/docker/libnetwork/issues/552 multicast is not working yet without --net=host. You can still run the client with network isolation and use -p 127.0.0.1:8545:8545 -p 30303:30303 -p 30303:30303/udp for publishing the rpc, discovery and p2p ports. If you want to be discoverable from the outside, you will need to

  • add your public ip address with the --public-ip flag,
  • create a port forwarding with your NAT

(syncing will still work without it).

Ubuntu snap

In any of the supported Linux distros:

sudo snap install cpp-ethereum --edge --devmode
cpp-ethereum.eth

(Note that this is an experimental and unstable release, at the moment)

Ubuntu PPA (Personal Package Archive)

NOTE - At the time of writing (31st August 2016), the PPAs are broken, following significant repository reorganizations and a change of automation process. We have not hooked the PPA generation steps back together yet, though this will happen in the very near future. In the meantime, please follow the Building for Linux instructions, or install the snap (currently in testing).

We have set up PPA instances for the following Ubuntu versions:

We only support 64-bit builds. It may be possible to get the client working for Ubuntu 32-bit, by building from source and disabling EVMJIT and maybe other features too. We might accept pull-requests to add such support, but we will not put any of our development time into supporting Ubuntu 32-bit builds.

For the latest stable version:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install cpp-ethereum

If you want to use the cutting edge developer version:

sudo apt-get install software-properties-common
sudo add-apt-repository ppa:ethereum/ethereum
sudo add-apt-repository ppa:ethereum/ethereum-dev
sudo apt-get update
sudo apt-get install cpp-ethereum
Windows Chocolatey NuGet packages

We aren't generating Chocolatey packages at the time of writing, though we have done so in the past.

For anybody who isn't already familiar with the technology, this is essentially apt-get for Windows - a global silent installer for tools.

We would like to support Chocolatey again in the near future for all the same reasons we support Homebrew on OS X and have PPAs for Ubuntu. For technically competent users, doing command-line operations like so would be very convenient:

choco install cpp-ethereum
choco update cpp-ethereum
OS X Homebrew packages

We generate Homebrew packages within our automated build system for the following OS X / Mac versions:

We only support 64-bit builds.

If your system does not support these OS X versions then you are out of luck. Sorry!

All OS X builds require you to install the Homebrew package manager before doing anything else. Here's how to uninstall Homebrew, if you ever want to start again from scratch.

To install the Ethereum C++ components from Homebrew, execute these commands:

brew update
brew upgrade
brew tap ethereum/ethereum
brew install cpp-ethereum
brew linkapps cpp-ethereum

Here is the Homebrew Formula which details all the supported command-line options.

Raspberry Pi, Odroid, BeagleBone Black, Wandboard

John Gerryts of EthEmbedded builds binary images for a variety of SBCs at major milestones, in addition to testing and maintaining build scripts for these devices. EthEmbedded was a devgrant recipient in May 2015. He builds binaries for both eth and geth.

Here are the Homestead binaries from EthEmbedded

Linux ARM cross-builds for mobile, wearables, SBCs

Bob Summerwill, of doublethinkco cross-builds ARM binaries which work on a very broad variety of hardware, from mobile and wearables Linux distros (Sailfish OS, Tizen OS, Ubuntu Touch) to the same SBCs which EthEmbedded target - and more. doublethinkco was a BlockGrantX recipient in Feb 2016.

See the cpp-ethereum-cross README for a full matrix of platforms and known status.

Here are the cross-build binaries from doublethinkco: RELEASED – Cross-build eth binaries for Homestead.

ArchLinux User Repository (AUR)

Arch Linux packages are community maintained by Afri Schoedon.

Check out the following packages on aur.archlinux.org.

To build and install the package, follow the AUR installing package instructions:

  • Acquire the tarball which contains the PKGBUILD
  • Extract the tarball
  • Run makepkg -sri as simple user in the directory where the files are saved
  • Install the resulting package with pacman -U as superuser

You can also use AUR helpers like yaourt or pacaur to install the packages directly on your system.

Mageia Cauldron (6) RPMs

Luis Daniel Lucio Quiroz has created RPMs for Mageia Cauldron (6).

cpp-ethereum is available in the non-free repository of Mageia 6. You will need to enable it. Once this is done, to install you just need to run the URPMI command (or RPMDRAKE if you are using GUI):

urpmi cpp-ethereum
Contributing

Help in whatever form is always more than welcome.

You can just start by Building from source and familiarizing yourself with the Architecture. If something strange happens, please report an issue (see below).

Once you get to know the technology, you can try to answer questions from other users (we do not always have time for that) either on cpp-ethereum gitter, stackexchange or just comment on issues.

If you are a C++ developer, you can help by submitting pull requests (see below).

We try to keep a list of good tasks to start with. Please get in contact on gitter if you have any questions or suggestions.

The backlog is kept in github issues with an overview in our waffle board.

The waffle board is also useful to keep track of pull requests pending reviews (if you switch the filter on the top right to "pull requests only").

How to Report Issues

Please report issues against the specific projects using GitHub Issues:

Try to mention which version of the software you used and on which platform (Windows, MacOS, Linux, ...), how you got into the situation (what did you do), what did you expect to happen and what actually happened.

How to Submit Pull Requests / Workflow

Set up your workspace using the Building from source instructions. To contribute you will need to fork/clone the repositories.

Please also respect the Coding Standards.

If you encounter any problems, please ask on gitter.

Create pull requests against the develop branch of the repository you made changes in. Try not to include any merges with the pull request and rebase if necessary. If you can set labels on a pull request, set it to please review and also ask for a review in gitter.

You can also do reviews on others' pull requests. In this case either comment with "looks good" or set the label if you can. If at least one core developer apart from the author is confident about the change, it can be merged. If the reviewer thinks that corrections are necessary, they put he label got issues. If the author addressed all comments, they again put please review or comment appropriately.

Automation runs on Appveyor and TravisCI.

Thanks for helping and have fun!

Architecture
_images/dependency_graph.svg
  • bench: trie benchmarking
  • cmake: cmake files for build system, contains specification of inter-dependencies
  • eth A command-line Ethereum full-node that can be controlled via RPC.
  • ethkey: stand-alone key management
  • ethminer: stand-alone ethash miner
  • ethvm: stand-alone EVM execution utility
  • evmjit: library for the EVM just-in-time compiler
  • libdevcore: data structures, utilities, rlp, trie, memory db
  • libdevcrypto: crypto primitives. Depends on libsecp256k1 and libcrypto++.
  • libp2p: core peer to peer networking implementation (excluding specific sub-protocols)
  • libethash: ethash mining POW algorithm implementation
  • libethash-cl: ethash mining code for GPU mining (OpenCL)
  • libethashseal: generic wrapper around the POW block seal engine. Also contains the genesis states for all ethash-based chains.
  • libethcore: collection of core data structures and concepts
  • libethereum: main consensus engine (minus EVM). Includes the State and BlockChain classes.
  • libevm: Ethereum Virtual Machine implementation (interpreter).
  • libevmasm: EVM assembly tools, also contains the optimizer.
  • libevmcore: elementary data structures of the EVM, opcodes, gas costs, ...
  • libweb3jsonrpc: json-rpc server-side endpoint, provides http and IPC (unix socket, windows pipe) connectors
  • libwebthree: service connectors for ethereum, swarm/ipfs and whisper.
  • libwhisper: whisper implementation
  • rlp: stand-alone rlp en-/decoder
  • testeth: tests for the modules formerly within the libethereum repo
  • testweb3core: tests for the modules formerly within the libweb3core repo
  • testweb3: tests for the modules formerly within the webthree repo
  • utils/json_spirit: JSON parser written for Boost's Spirit library.
  • utils/libscrypt: scrypt implementation
  • utils/secp256k1: implementation of the SECP 256k1 ECDSA signing algorithm.
Portability

The Ethereum C++ client code is exceedingly portable, and is being successfully used on a huge range of different operating systems and devices.

We continue to expand our range and are very open to pull-requests which add support for additional operating systems, compilers or devices.

Operating systems verified as working
  • Linux
    • Alpine Linux
    • Arch Linux
    • Debian 8 (Jessie and Stretch)
    • Fedora 20
    • Fedora 21
    • Fedora 22
    • openSUSE Leap 42.1
    • PureOS 2.1
    • Raspbian
    • Sailfish OS 2.0
    • Ubuntu 14.04 (Trusty)
    • Ubuntu 14.10 (Utopic)
    • Ubuntu 15.04 (Vivid)
    • Ubuntu 15.10 (Wily)
    • Ubuntu 16.04 (Xenial)
    • Ubuntu Touch
    • Ubuntu 15.04 MATE
  • BSD
    • FreeBSD
  • OS X
    • OS X Yosemite (10.10)
    • OS X El Capitan (10.11)
    • OS X 10.10 (Yosemite Server 4.0)
    • OS X 10.11 (Yosemite Server 5.0)
    • OS X 10.11 (Yosemite Server 5.1)
  • Windows
    • Windows 7
    • Windows 8
    • Windows 8.1
    • Windows 10
    • Windows Server 2012 R2
Operating systems - work in progress
  • Linux
    • Maemo
    • MeeGo
    • Tizen
  • BSD
    • iOS
    • tvOS
    • WatchOS
  • Android
Devices verified as working
  • All varieties of desktop and laptop devices (Windows, OS X, Desktop Linux)
    • 64-bit (with rebuilt binaries)
    • 32-bit (not official supported, but they work)
  • Smartphones
    • Linux
      • Jolla Phone
      • Meizu MX4 Ubuntu Edition
      • Nexus 5 (SailfishOS 2.0)
  • SBCs
    • Linux
      • BeagleBone Black
      • Odroid XU3
      • Project C.H.I.P.
      • Raspberry Pi Model A
      • Raspberry Pi Model B+
      • Raspberry Pi Zero
      • Raspberry Pi 2
      • Raspberry Pi 3
      • Wandboard Quad
Devices - work in progress
  • Smartwatches
    • Linux
      • Samsung Gear S2
    • BSD
      • Apple Watch
  • Smartphones
    • Linux
      • Nokia N9 (MeeGo)
      • Nokia N900 (Meemo)
      • Samsung Z1
      • Samsung Z3
    • Android
      • Samsung Galaxy S3
      • Samsung Galaxy S4
    • BSD
      • iPhone 3GS
      • iPhone 5
  • Developer phones
    • Linux
      • Samsung RD-210
      • Samsung RD-PQ
      • Samsung TM1
  • Tablets
    • Android
      • Samsung Galaxy Tab S 10.5
      • Nexus 7
    • BSD
      • iPad Air 2
  • SBCs
    • Linux
      • DragonBoard 410c
      • Intel Curie
      • Intel Edison
      • Intel NUC
      • Minnowboard Max
      • Odroid XU4
Running

Running eth without any argument will synchronise your node to the public blockchain. It is also possible to create or synchronise to another blockchain (see custom blockchain using eth).

Interacting with your node can be done using either geth or the ethereum console:

Using geth

> geth attach //attach geth to a running eth node.

Using the ethereum console

The ethereum console is a node.js application which connect to a running eth/geth node and provide access to the web3 object.

注解

https://github.com/ethereum/ethereum-console

It can be installed using npm:

注解

> npm install -g ethereum-console
> ethconsole

注解

Usage:
ethconsole [javascript file] [ipc socket]
Connects to an ethereum node via ipc in order to control it remotely
through global variable web3 (web3.admin is also present).
If no arguments are given, connects to the default ipc socket
and drops into interactive mode.
Arguments:
<ipc socket path> connect to the given ipc socket (use ipc://<path> if it does not end with .ipc)
<javascript file> execute the given javascript file that has to end in .js non-interactively.
The script has to call process.exit() in order to terminate the console.

go-ethereum

go-ethereum客户端通常被称为 geth ，它是个命令行界面，使用GO语言实现的完整以太坊节点。 通过安装和运行geth，可以参与到以太坊前台实时网络并进行以下操作：

  • 挖掘真的以太币
  • 在不同地址间转移资金
  • 创建合约，发送交易
  • 探索区块历史
  • 及很多很多其他

链接:

pyethapp

Pyethapp 是基于python的客户端，实现以太坊加密经济状态机。python实现旨在提供一个更容易删节和扩展的代码库。

Pyethapp使用了两个以太坊核心组件来实现客户端：

  • pyethereum - 核心库，包含区块链、以太坊模拟机和挖矿为特征
  • pydevp2p - 点对点网络库，包含节点发现和通过复用和加密连接传输多个服务

链接:

ethereumjs-lib

如 黄皮书 中所描述的， ethereumjs-lib 是核心`以太坊 <http://ethereum.org/>`_ 功能的javascript库。 这是个简单的元模块，提供以下模块。大部分JS模块都在`ethereumjs <https://github.com/ethereumjs>`_ 上都有跟踪。

  • VM - 以太坊虚拟机和状态处理功能
  • 区块链 - 区块链管理
  • 区块 - 区块模式定义与验证
  • 交易 - 交易模式定义与验证
  • 账户 - 账户模式定义和验证
  • rlp - 循环长度前缀序列化
  • Trie - 改良的Merkle Patricia树
  • Ethash - 以太坊工作量证明算法
  • utils - 多样辅助功能
  • devp2p - 网络协议
  • devp2p-dpt - 争议节点列表

链接:

Ethereum(J)

Ethereum(J) 是以太坊协议的纯Java实现。它作为可以嵌入任何Java/Scala项目的库提供， 并为以太坊协议及附属服务提供完全支持。 Ethereum(J)期初是由`Roman Mandeleil <https://github.com/romanman>`_ 开发， 目前由`<ether.camp> <http://www.ether.camp>`_ 资助开发。

Ethereum(J)支持CPU挖矿。目前它由纯Java实现，可用于私人和测试网络。 你甚至可以在实时以太坊网络上挖矿，尽管这样做并不划算。

链接:

ethereumH

该包提供了一个使用Haskell编写的工具用于连接以太网区块链。

链接:

Parity

Parity 声称是世界上最快速、最轻便的以太坊客户端。它用Rust语言编写，改善了可靠性、性能和代码清晰度。 Parity由`Parity Technologies (f.k.a. Ethcore) <https://paritytech.io/>`_ ，开发。 Ethcore由几个以太坊基金会的会员创建。

Arch Linux程序包由 Afri Schoedon 进行维护。

已经有报告在树莓派2上成功运行Parity。

ruby-ethereum

ruby-ethereum 是 以太坊虚拟机 的Ruby实现.

链接:

相关阅读:

连接到以太坊客户端

通过 JSON-RPC ，在应用程序中与以太坊客户端进行交互可以有多种方法。 然而，通过JSON-RPC直接交互会给应用程序开发者带来许多负担，例如：

  • JSON-RPC协议实现
  • 新建和操作智能合约时的二进制编/解码
  • 256位数据类型
  • 管理员命令支持 - 例如，新建/管理地址，签名操作

为解决以上的这些问题，开发人员开发了一系列库。在这些库的帮助下，开发人员可以专注于实现他们的应用程序， 而不必实现与以太坊客户端和其生态系统进行交互的底层内容。

库 语言 项目页面
web3.js JavaScript https://github.com/ethereum/web3.js
web3j Java https://github.com/web3j/web3j
Nethereum C# .NET https://github.com/Nethereum/Nethereum
ethereum-ruby Ruby https://github.com/DigixGlobal/ethereum-ruby
web3.py Python https://github.com/ethereum/web3.py

库的详细信息可参见如下内容：

web3.js

web3.js

这是一个以太坊兼容的 JavaScript API ， 这个API实现了 Generic JSON RPC 标准。 它作为一个node模块可从npm中获取，作为可嵌入js和meteor.js包模块。

链接:

web3j

web3j

web3j是一个轻量级的Java库，用于在Ethereum网络上集成客户端（节点）。

核心特性：
  • 通过Java类型的JSON-RPC与Ethereum客户端进行交互
  • 支持所有的JSON-RPC方法类型
  • 支持所有Geth和Parity方法，用于管理账户和签署交易
  • 同步或异步的发送客户端请求
  • 可从Solidity ABI文件自动生成Java只能合约功能包

目前，支持 go-ethereum 和 Parity 客户端。

Links:

Nethereum

Nethereum

Nethereum是一个Ethereum的.Net集成库，该库可以通过RPC与Ethereum客户端（如: go-ethereum, cpp-ethereum 或 Parity ）进行交互。

这个库与 Javascript Etherum Web3 RPC 客户端库的功能相近。

在新版客户端中出现的所有的JSON RPC/IPC方法都被实现了。

geth客户端经过了紧密的支持和测试，包括它的管理员、个性化、调试、挖矿的管理扩展。

与合约进行交互进行了简化，以适应部署，功能调用，交互，事件过滤和主题译码。

库已经在所有的平台中经过了测试，包括.Net Core, Mono, Linux, iOS, Android, Raspberry PI, Xbox以及Windows。

Links:

ethereum-ruby

ethereum-ruby 是一个pure-Ruby JSON-RPC包装，用于和以太坊节点交流。 要使用这个库，你需要有运行的以太坊节点和可行的IPC支持（默认）。目前支持 go-ethereum 客户端。

Links:

web3.py

web3.py 是一个纯Python JSON-RPC 打包，用于与Ethereum节点进行通信。如需使用这个库，则需要一个运行中的Ethereum节点，并启用HTTP 或 IPC。

Links:

通过web3.js库新建和操作智能合约与交易的简介，可参见 Accessing Contracts and Transactions 。

账户管理

账户

账户在以太坊中发挥着中心作用。共有两种账户类型：外部账户 （EOAs）和 合约账户 。 我们这里重点讲一下外部账户，以下会简称为 账户 。合约账户简称为 合约 ，在 合约章节 具体讨论。 把外部账户和合约账户都归入到帐户的一般概念是合理的，因为这些实体都是所谓的 状态对象 。 这些实体都有状态：账户有余额，合约既有余额也有合约储存。所有账户的状态正是以太坊网络的状态，以太坊网络和每个区块一起更新， 网络需要达成关于以太坊的共识。对于用户通过交易和以太坊区块链互动来说，账户是必不可少的。

如果我们把以太坊限制为只有外部账户，只允许外部账户之间进行交易，我们就会进入到"代币"系统，"代币"系统不如比特币本身有力，只能用于转移以太币。

账户代表着外部代理人（例如人物角色，挖矿节点 ，或是自动代理人）的身份。账户运用公钥加密图像来签署交易以便以太坊虚拟机可以安全地验证交易发送者身份。

钥匙文件

每个账户都由一对钥匙定义，一个私钥和一个公钥。账户以 地址 为索引，地址由公钥衍生而来，取公钥的最后 20个字节。 每对私钥/地址都编码在一个 钥匙文件 里。钥匙文件是JSON文本文件，可以用任何文本编辑器打开和浏览。 钥匙文件的关键部分，账户私钥，通常用你创建帐户时设置的密码进行加密。钥匙文件可以在以太坊节点数据目录的 keystore 子目录下找到。 确保经常给钥匙文件备份！查看 账号备份和恢复 章节了解更多。

创建钥匙和创建帐户是一样的。

  • 不必告诉任何人你的操作。
  • 不必和区块链同步。
  • 不必运行客户端。
  • 甚至不必连接到网络。

当然新账户不包含任何以太币。但它将会是你的，你大可放心，没有你的钥匙和密码，没有人能进入。

在以太坊节点间转换整个目录或任何个人钥匙文件都是安全的。

警告

请注意万一你从一个不同的节点向另一个节点添加钥匙文件，账户的顺序可能发生改变。确保不要回复或改变手稿中的索引或代码片段。

创建账号

警告

记住密码并 备份钥匙文件。为了从账号发送交易，包括发送以太币，

你必须同时有钥匙文件和密码。确保钥匙文件有个备份并牢记密码，尽可能安全地存储它们。 这里没有逃亡路径，如果钥匙文件丢失或忘记密码，就会丢失所有的以太币。 没有密码不可能进入账号，也没有忘记密码选项。所以一定不要忘记密码。

使用 geth account new

一旦安装了geth客户端，创建账号只需要在终端执行 geth account new 指令的问题了。

注意不必运行geth客户端或者和区块链同步来使用 geth account 指令。

$ geth account new

  Your new account is locked with a password. Please give a password. Do not forget this password.
  Passphrase:
  Repeat Passphrase:
  Address: {168bc315a2ee09042d83d7c5811b533620531f67}

对于非交互式使用，你可以提供纯文本密码文件作为 --password 标志的变量。文件中的数据包含密码的原始字节，后面可选择单独跟着新的一行。

$ geth --password /path/to/password account new

警告

用 --password 标志只是为了测试或在信任的环境中自动操作。不建议将密码保存在文件中或以任何其他方式暴露。如果 --password 标志的变量是密码文件，要确保文件只对你自己可阅读和列表。你可以在 Mac/Linux系统中通过以下指令实现：

touch /path/to/password
chmod 600 /path/to/password
cat > /path/to/password
>I type my pass

要列出目前在你的 keystore 文件夹中的钥匙文件的所有账号，使用 geth account 指令的 list 子指令：

$ geth account list

account #0: {a94f5374fce5edbc8e2a8697c15331677e6ebf0b}
account #1: {c385233b188811c9f355d4caec14df86d6248235}
account #2: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d}

钥匙文件的文件名格式为 UTC--<created_at UTC ISO8601>-<address hex> 。账号列出时是按字母顺序排列，但是由于时间戳格式，实际上它是按创建顺序排列。

使用geth控制台

为了用geth创建新账号，我们必须先在控制台模式开启geth（或者可以用 geth attach 将控制台依附在已经运行着的实例上）：

> geth console 2>> file_to_log_output
instance: Geth/v1.4.0-unstable/linux/go1.5.1
coinbase: coinbase: [object Object]
at block: 865174 (Mon, 18 Jan 2016 02:58:53 GMT)
datadir: /home/USERNAME/.ethereum

控制台使你能够通过发出指令与本地节点互相作用。比如，试一下这个列出账号的指令：

> eth.accounts

{
code: -32000,
message: "no keys in store"
}

这表示你没有账号，你也可以从控制台创建一个账号：

> personal.newAccount()
Passphrase:
Repeat passphrase:
"0xb2f69ddf70297958e582a0cc98bce43294f1007d"

注解

记得用一个安全性强、随机生成的密码。

我们刚刚创建了第一个账号。如果我们再次试着列出账号，就可以看到新创建的账号了：

> eth.accounts
["0xb2f69ddf70297958e582a0cc98bce43294f1007d"]

使用Mist以太坊钱包

对于命令行的反面，现在有一个基于GUI的选项可以用来创建账号："官方"Mist以太坊钱包。 Mist以太坊钱包，和它的父项目Mist, 是在以太坊基金会的赞助下开发，因此是"官方"地位。钱包应用有Linux, Mac OS X和Windows可用的版本。

警告

Mist钱包是试用软件，使用需风险自担。

用GUI Mist以太坊钱包创建账号再容易不过了。事实上，第一个账号在应用安装期间就创建出来了。

  1. 根据你的操作程序 下载钱包应用最新版本 。由于你实际上会运行一个完整的geth节点，打开钱包应用就会开始同步复制你电脑上的整个以太坊区块链。
  2. 解压下载的文件，运行以太坊钱包可执行文件。
downloading-mist
  1. 等待区块链完全同步，按照屏幕上的说明操作，第一个账号就创建出来了。
  2. 第一次登录Mist 以太坊钱包，你会看到自己在安装过程中创建的账号。它会被默认命名为主账号（ETHERBASE）。
opening-screen
  1. 再另外创建账号很容易；只需点击应用主界面上的添加账号，输入所需的密码即可。

注解

Mist钱包仍在开发中，以上列出的具体步骤可能会随着更新有所变更。

在Mist创建多签名钱包

Mist以太坊钱包有个选项是可以用多签名钱包使钱包里的余额更安全。用多签名钱包的好处是它需要多个账号共同批准才能够从余额中提取大额资金。创建多签名钱包之前，需要创建多个账号。

在Mist创建账号文件很容易。在 账号 菜单下点击 添加账号 。选择一个安全性高又容易记住的密码（记住没有密码找回选项），确认，账号创建就完成了。创建至少 2个账号。如果你愿意，第二个账号可以在另一台有Mist运行的电脑上创建（理论上这样可以使多签名更加安全）。你只需要第二个账号的公钥（存款地址）来创建多签名钱包（复制/粘贴，不要手动输入）。因为需要第一个账号来创建多签名钱包合约，所以第一个账号必须是在你创建多签名钱包的电脑上。

既然已经创建了账号，保持安全并进行备份（如果不备份，电脑系统崩溃，余额就会丢失）。点击菜单顶端的 备份 。选择 keystore 文件夹，反向点击 / 选择 复制`（不要选择 `剪切 ，否则结果会很糟糕）。回到桌面，在空白区域反击，选择"粘贴"。你可能会想把这个"keystore"文件夹重命名为"以太坊－keystore－备份－年－月－日"，这样以后就能很快辨认出来。这时候你就能把文件夹内容添加到压缩文件里（如果是在线备份，最好用另外一个安全性高又容易记住的密码对档案进行密码保护 ），复制到U盘，刻录到CD/DVD ，或者上传到在线存储设备（ Dropbox/Google Drive等）。

你现在应该添加大约不到 0.02以太币到第一个账号里（那个用来创建多签名钱包的账号）。这是创建多签名钱包所需的交易费用。另外再需要1以太币（或者更多），因为 Mist现在需要这样做来确保钱包合约交易有足够的"gas"来正常执行……所以对新人来说，总共需要不到 1.02以太币。

创建多签名钱包的时候，你会进入到附属在它上面所有账号的完整地址。我推荐把每个地址复制/粘贴到简单的文本编辑器上（notepad / kedit等），到Mist每个账号的详情页以后，从右侧按键栏里选择"复制地址"选项。不要手动输入地址，或者冒着输入错误的风险，你可能会把交易发送到错误的地址，因此丢失余额。

我们现在准备好了创建多签名钱包。在"钱包合约"下，选择"增加钱包合约"。起个名字，选择第一个账号持有人，选择"多签名钱包合约"。你会看到出现这样的文字：

"这是由X个持有人共同控制的联合账号。每天最多可以发送X个以太币。任何超过每日限额的交易都需要 X个持有人确认。"

设置附属在这个多签名钱包上的持有人(账号)数量，每日提款限额(这只要求一个账号提出这些钱款，以及允许多少持有人(账号)批准超过每日限额的提款。

现在加入之前复制/粘贴在文本编辑器中的账号地址，确认所有的设置正确后，点击底部的"创建"按钮。然后需要输入密码发送交易。在"钱包合约"部分，会显示出新的钱包，告诉你"创建"。

钱包创建完成后，就能在屏幕上看到合约地址。选择整个地址，复制/粘贴到文本编辑器的新文件里，保存至桌面，命名为"以太坊-钱包-地址.txt"或其他名称。

现在只需用备份合约文件的方式来备份"以太坊-钱包-地址.txt"，接着就能用这个地址在ETH装载新的多签名钱包。

如果你要从备份中恢复，只需要复制"以太坊–keystore–备份"文件夹里的文件到这个攻略第一部分里提到的"keystore"文件夹。如果是在从未安装过Mist的机器上安装（第一次创建账号的同时就会建立文件夹），可能需要创建"keystore"文件夹。如果要恢复多签名钱包，不要像我们创建之前一样选择"多签名钱包合约"，只选择"导入钱包"就可以了。

故障排查：

  • Mist不能同步。一个有用的解决方案是将个人电脑硬件时钟与NTP服务器同步，确保时间无误后重启。
  • Mist同步后启动，但出现了白屏。有可能是因为你在基于Linux的操作系统上运行了 "xorg" 视频驱动器（Ubuntu, Linux Mint等），试试安装制造商的视频驱动器。
  • 提示"密码错误"。在现在的Mist版本上，这有可能是个错误的提示。重启Mist，问题就能解决（如果你输入的确实是正确密码）。

使用Eth

与使用geth的可用钥匙管理相关的每个选项都同样适用于eth。

以下是与"账号"相关的选项：

> eth account list  // List all keys available in wallet.
> eth account new   // Create a new key and add it to the wallet.
> eth account update [<uuid>|<address> , ... ]  // Decrypt and re-encrypt given keys.
> eth account import [<uuid>|<file>|<secret-hex>] // Import keys from given source and place in wallet.

以下是与"钱包"有关的选项：

> eth wallet import <file> //Import a presale wallet.

注解

"账号导入"选项只能用于导入一般的钥匙文件。"钱包导入"选项只能用于导入预售钱包。

也可以从综合控制台进入钥匙管理（用内置控制台或者geth附件）：

> web3.personal
{
      listAccounts: [],
      getListAccounts: function(callback),
      lockAccount: function(),
      newAccount: function(),
      unlockAccount: function()
}

使用EthKey （弃用）

Ethkey是C++实现的CLI工具，可以让你和以太坊钱包互动。你可以用它罗列、检查、创建、删除和修改钥匙，以及检查、创建和签署交易。

我们假定你还没有运行过客户端，比如eth或者Aleth系列的任何客户端。如果你运行过，可以略过这一章节。

要创建钱包，用 creatwallet 指令运行 ethkey ：

> ethkey createwallet

请输入管理员密码来保护keystore（设一个安全性高的！）：会问你要一个"管理员"密码。这能保护你的隐私，并且它会默认为你任何钥匙的密码。你需要再次输入同一文本来进行确认。

注解

使用安全性高的、随机生成的密码。

我们可以通过使用列表指令简单地列出钱包内的钥匙：

> ethkey list

No keys found.

我们还没创建任何钥匙，它也是这样告诉我们的！我们来创建一个吧。

要创建钥匙，我们需要用 new 指令，需要通过一个名字——这也是我们要给钱包里账号的名字。我们称之为"测试"：

> ethkey new test

输入密码来保护这个账号（或者用管理员密码就不用输入了）。这会促使你输入密码来保护这个钥匙。如果你只点击回车，就会使用默认的"管理员"密码。这意味着，当你想用账号的时候，不必输入钥匙密码（因为它记住了管理员密码）。总体来说，你应该试着为每个钥匙设置一个不同的密码，因为这样能防止一个密码被盗用而导致其他账号也被入侵。然而为了方便你可能会决定让低安全性的账号使用同一个密码。

在这里，我们用一个极富想象力的密码123（永远不要用这么简单的密码，除非是暂时的测试账号）。输入密码后，它就会让你再次输入确认。再次输入123。由于你设置了它的密码，它会让你提供一个密码提示，每次进入的时候都会显示密码提示。提示会储存在钱包里，由管理员密码保护。我们来输入糟糕的密码提示321倒序。

> ethkey new test

Enter a passphrase with which to secure this account (or nothing to use the master passphrase):
Please confirm the passphrase by entering it again:
Enter a hint to help you remember this passphrase: 321 backwards
Created key 055dde03-47ff-dded-8950-0fe39b1fa101
  Name: test
  Password hint: 321 backwards
  ICAP: XE472EVKU3CGMJF2YQ0J9RO1Y90BC0LDFZ
  Raw hex: 0092e965928626f8880629cec353d3fd7ca5974f

所有正常（或者说直接）的 ICAP地址都以XE开头，这样就很容易辨认。请注意这个钥匙在创建的钥匙后有另外一个标识符，被称为UUID。这是个特有的钥匙标识符，和账号本身毫无关系。知道了它对攻击者发现你在网上的身份毫无帮助。它刚好也是钥匙的文件名，你可以在~/.web3/keys (Mac或Linux)或者$HOME/AppData/Web3/keys (Windows)中发现。让我们通过列出钱包里的钥匙来确认它在正常运行：

> ethkey list
055dde03-47ff-dded-8950-0fe39b1fa101 0092e965… XE472EVKU3CGMJF2YQ0J9RO1Y90BC0LDFZ  test

它每行会报告一个钥匙（这里总共只有一个钥匙）。在这个例子里，钥匙被储存在055dde... 文件，有个以XE472EVK...开头的ICAP地址。这不容易记住，所以有个专有名称会很有帮助，还是叫test吧。

导入预售钱包

使用Mist以太坊钱包

用GUI Mist以太坊钱包导入预售钱包非常简便。实际上，在应用安装期间你会被问到是否要导入预售钱包。

警告

Mist钱包是试用软件。使用风险自担。

安装Mist以太坊钱包的说明在 Creating an account: Using Mist Ethereum wallet 章节给出。

只需要把 .json 预售钱包文件拖放到指定区域，输入密码，导入预售钱包。

presale-import

如果你选择不在应用安装期间导入预售钱包，以后你可以随时导入，只需选择应用菜单栏下方的 账号 菜单，然后选择 导入预售账号 。

注解

Mist钱包仍在开发中，以上列出的具体步骤可能会随着更新有所变更。

使用geth

如果你单独安装geth，导入预售钱包可以通过在终端执行以下操作完成：

geth wallet import /path/to/my/presale-wallet.json

这会提示你输入密码。

更新账号

你可以把钥匙文件更新到最新的钥匙文件格式并且/或者升级钥匙文件密码。

使用geth

你可以在命令行用 更新 子命令更新现在的账号，可以使用账号地址或者索引作为参数。记住账号索引反映了创建顺序（按字母顺序排列的钥匙文件名包含了创建时间）。

geth account update b0047c606f3af7392e073ed13253f8f4710b08b6

或

geth account update 2

例如:

$ geth account update a94f5374fce5edbc8e2a8697c15331677e6ebf0b

Unlocking account a94f5374fce5edbc8e2a8697c15331677e6ebf0b | Attempt 1/3
Passphrase:
0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b
account 'a94f5374fce5edbc8e2a8697c15331677e6ebf0b' unlocked.
Please give a new password. Do not forget this password.
Passphrase:
Repeat Passphrase:
0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b

账户以加密的形式储存在最新版本，它会提示你需要一个密码来解锁账户，另一个密码来保存更新的文件。同一个指令还可以用在将弃用格式的账户变成最新版本或者改变账户密码。

对于非交互式使用，密码可以用 --password 标志详细说明：

geth --password <passwordfile> account update a94f5374fce5edbc8e2a8697c15331677e6ebf0bs

由于只能给出一个密码，所以只能执行格式更新，修改密码只在交互式的情况下才有可能。

注解

账号更新有个副作用就是会引起账号顺序变化。更新成功后，同一钥匙所有之前的格式/版本都会被移除！

账号备份和恢复

手动备份/恢复

要从账号发送交易，需要有账号钥匙文件。钥匙文件可以在以太坊节点数据目录的钥匙商店（keystore）子目录下找到。默认数据目录的位置与平台相关：

  • Windows: %appdata%\Ethereum\keystore
  • Linux: ~/.ethereum/keystore
  • Mac: ~/Library/Ethereum/keystore

要备份钥匙文件（账号），在 keystore 子目录中复制单独的钥匙文件或复制整个 keystore 文件夹。

要恢复钥匙文件（账号），将钥匙文件重新复制到 keystore 子目录，即其原始地址。

导入未加密私钥

导入未加密私钥由 geth 支持

geth account import /path/to/<keyfile>

这个指令从纯文本文件 <keyfile> 导入未加密私钥并创建新账号和打印地址。钥匙文件被假定包含未加密私钥作为编码到十六进制的标准EC原始字节。账号以加密的形式储存，会提示你输入密码。你需要记住密码用于以后解锁账号。

下面给出一个例子，详细说明数据目录。如果 --datadir 标志没有使用，新账户就会被创建在默认数据目录里，即钥匙文件会被放在数据目录的 keystore 子目录里。

$ geth --datadir /someOtherEthDataDir  account import ./key.prv
The new account will be encrypted with a passphrase.
Please enter a passphrase now.
Passphrase:
Repeat Passphrase:
Address: {7f444580bfef4b9bc7e14eb7fb2a029336b07c9d}

对于非交互式使用，密码可以用 --password 标志详细说明：

geth --password <passwordfile> account import <keyfile>

注解

因为你可以直接把加密账户复制到另一个以太坊事例中，在节点之间转移账号的时候就不需要这个导入/导出机制了。

警告

当你往已存在节点的 keystore 里复制钥匙的时候，你习惯的账户顺序可能会改变。因此要保证你不依赖于账户顺序，否则就要进行复核并更新脚本中使用的索引。

Ether

以太币是什么?

以太币是以太坊中使用的货币名称，用于在以太坊虚拟机内支付计算。这通过为以太币购买gas间接实现，详见 gas 。

面额

以太坊有一个面额的度量体系，用作以太币单位。每个面额都有自己独特的名字（有的是在计算机科学与加密经济学演进过程中发挥开创性作用的人物的姓）。最小的面额也就是以太币 基础单位 ，叫做Wei。下面的列表是面额名称以及Wei的价值转换。以太币遵循惯例（尽管有些模棱两可），指定了货币单位（1e18或者百万的三次方Wei）。注意很多人误以为货币叫以太坊，但以太坊并不是货币单位。

Unit Wei Value Wei
wei 1 wei 1
Kwei (babbage) 1e3 wei 1,000
Mwei (lovelace) 1e6 wei 1,000,000
Gwei (shannon) 1e9 wei 1,000,000,000
microether (szabo) 1e12 wei 1,000,000,000,000
milliether (finney) 1e15 wei 1,000,000,000,000,000
ether 1e18 wei 1,000,000,000,000,000,000

获取以太币

请参见 该页面.

发送以太币

以太坊钱包 支持通过图像界面发送以太币。

以太币也可以用 geth 控制台转换。

> var sender = eth.accounts[0];
> var receiver = eth.accounts[1];
> var amount = web3.toWei(0.01, "ether")
> eth.sendTransaction({from:sender, to:receiver, value: amount})

了解更多以太币转移交易，请参考 Account Types, Gas, and Transactions 。

以太坊在加密货币领域是独一无二的，原因在于以太币作为加密燃料具有实用价值，通常被称作"gas"。除交易费用外，gas是每个网络请求的中心部分，需要发送者为消费的运算资源付费。Gas成本是基于请求规模和复杂性的动态计算，乘以现在的gas价格。它作为加密燃料的价值能够增加以太币和以太坊作为一个整体的稳定性和长期需求。了解更多信息，请参考 Account Types, Gas, and Transactions 。

Gas和以太币

Gas被认为是网络资源/使用的固定成本。想要发送交易的真实成本保持一致，所以不希望gas发行，一般来说货币是不稳定的。

因此我们发行以太币，它的价值会变动，但也会根据以太币来执行gas价格换算。如果以太币价格上升，gas价格换算成以太币会下降，以此来保持gas的真实花费相同。

gas有多个相关词汇：gas成本，gas限制和gas费用。gas背后遵循的原则是使以太坊网络上每个交易或计算成本保持稳定的价值。

  • gas成本是静态值，是以gas为单位的计算成本，目的是保持gas的真实价值不变，所以这个成本会一直稳定。
  • gas价格是以另一货币或代币比如说以太币为单位的gas成本。为了保持gas价值稳定，gas价格是浮动值，如果代币或货币成本波动，gas价格也会变化以保持同样的真实价值。Gas价格的设定是根据多少用户愿意花费和多少进程节点愿意接受的平衡价格。
  • Gas限制是每个区块能使用的gas最大限额，被视为计算工作量，交易量和区块大小的最大值，矿工可以随着时间慢慢改变这个值。
  • gas费用是运行一个特别的交易或程序（被称作合约）所需的gas。 一个区块的gas费用可以用来暗示计算工作量，交易量和区块大小。gas费用支付给矿工（或PoS中的担保承包人） 。

以太坊网络

Network info.

Connecting to the Network

This section

The Ethereum network

The basis for decentralised consensus is the peer-to-peer network of participating nodes which maintain and secure the blockchain. See 挖矿.

Ethereum network stats

EthStats.net is a dashboard of live statistics of the Ethereum network. This dashboard displays important information such as the current block, hash difficulty, gas price, and gas spending. The nodes shown on the page are only a selection of actual nodes on the network. Anyone is allowed to add their node to the EthStats dashboard. The Eth-Netstats README on Github describes how to connect.

EtherNodes.com displays current and historical data on node count and other information on both the Ethereum mainnet and Morden testnet.

Distribution of client implementations on the current live network - Realtime stats on EtherChain.

Public, private, and consortium blockchains

Most Ethereum projects today rely on Ethereum as a public blockchain, which grants access to a larger audience of users, network nodes, currency, and markets. However, there are often reasons to prefer a private blockchain or consortium blockchain (among a group of trusted participants). For example, a number of companies in verticals, like banking, are looking to Ethereum as a platform for their own private blockchains.

Below is an excerpt from the blog post On Public and Private Blockchains that explains the difference between the three types of blockchains based on permissioning:

  • Public blockchains: a public blockchain is a blockchain that anyone in the world can read, anyone in the world can send transactions to and expect to see them included if they are valid, and anyone in the world can participate in the consensus process – the process for determining what blocks get added to the chain and what the current state is. As a substitute for centralized or quasi-centralized trust, public blockchains are secured by cryptoeconomics – the combination of economic incentives and cryptographic verification using mechanisms such as proof of work or proof of stake, following a general principle that the degree to which someone can have an influence in the consensus process is proportional to the quantity of economic resources that they can bring to bear. These blockchains are generally considered to be “fully decentralized”.
  • Consortium blockchains: a consortium blockchain is a blockchain where the consensus process is controlled by a pre-selected set of nodes; for example, one might imagine a consortium of 15 financial institutions, each of which operates a node and of which 10 must sign every block in order for the block to be valid. The right to read the blockchain may be public, or restricted to the participants, and there are also hybrid routes such as the root hashes of the blocks being public together with an API that allows members of the public to make a limited number of queries and get back cryptographic proofs of some parts of the blockchain state. These blockchains may be considered “partially decentralized”.
  • Private blockchains: a fully private blockchain is a blockchain where write permissions are kept centralized to one organization. Read permissions may be public or restricted to an arbitrary extent. Likely applications include database management, auditing, etc internal to a single company, and so public readability may not be necessary in many cases at all, though in other cases public auditability is desired.

While these private/consortium blockchains may not have any connection to the public blockchain, they still contribute to the overall Ethereum ecosystem by investing in Ethereum software development. Over time, this translates into software improvements, shared knowledge, and job opportunities.

How to connect

Geth continuously attempts to connect to other nodes on the network until it has peers. If you have UPnP enabled on your router or run Ethereum on an Internet-facing server, it will also accept connections from other nodes.

Geth finds peers through something called the discovery protocol. In the discovery protocol, nodes are gossipping with each other to find out about other nodes on the network. In order to get going initially, geth uses a set of bootstrap nodes whose endpoints are recorded in the source code.

Checking connectivity and ENODE IDs

To check how many peers the client is connected to in the interactive console, the net module has two attributes that give you info about the number of peers and whether you are a listening node.

> net.listening
true

> net.peerCount
4

To get more information about the connected peers, such as IP address and port number, supported protocols, use the peers() function of the admin object. admin.peers() returns the list of currently connected peers.

> admin.peers
[{
      ID: 'a4de274d3a159e10c2c9a68c326511236381b84c9ec52e72ad732eb0b2b1a2277938f78593cdbe734e6002bf23114d434a085d260514ab336d4acdc312db671b',
      Name: 'Geth/v0.9.14/linux/go1.4.2',
      Caps: 'eth/60',
      RemoteAddress: '5.9.150.40:30301',
      LocalAddress: '192.168.0.28:39219'
 }, {
      ID: 'a979fb575495b8d6db44f750317d0f4622bf4c2aa3365d6af7c284339968eef29b69ad0dce72a4d8db5ebb4968de0e3bec910127f134779fbcb0cb6d3331163c',
      Name: 'Geth/v0.9.15/linux/go1.4.2',
      Caps: 'eth/60',
      RemoteAddress: '52.16.188.185:30303',
      LocalAddress: '192.168.0.28:50995'
 }, {
      ID: 'f6ba1f1d9241d48138136ccf5baa6c2c8b008435a1c2bd009ca52fb8edbbc991eba36376beaee9d45f16d5dcbf2ed0bc23006c505d57ffcf70921bd94aa7a172',
      Name: 'pyethapp_dd52/v0.9.13/linux2/py2.7.9',
      Caps: 'eth/60, p2p/3',
      RemoteAddress: '144.76.62.101:30303',
      LocalAddress: '192.168.0.28:40454'
 }, {
  ID: 'f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0',
  Name: '++eth/Zeppelin/Rascal/v0.9.14/Release/Darwin/clang/int',
  Caps: 'eth/60, shh/2',
  RemoteAddress: '129.16.191.64:30303',
  LocalAddress: '192.168.0.28:39705'
 } ]

To check the ports used by geth and also find your enode URI run:

> admin.nodeInfo
{
  Name: 'Geth/v0.9.14/darwin/go1.4.2',
  NodeUrl: 'enode://3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694@[::]:30303',
  NodeID: '3414c01c19aa75a34f2dbd2f8d0898dc79d6b219ad77f8155abf1a287ce2ba60f14998a3a98c0cf14915eabfdacf914a92b27a01769de18fa2d049dbf4c17694',
  IP: '::',
  DiscPort: 30303,
  TCPPort: 30303,
  Td: '2044952618444',
  ListenAddr: '[::]:30303'
}

Download the blockchain faster

When you start an Ethereum client, the Ethereum blockchain is automatically downloaded. The time it takes to download the Ethereum blockchain can vary based on client, client settings, connection speed, and number of peers available. Below are some options for more quickly obtaining the Ethereum blockchain.

Using geth

If you are using the geth client, there are some things you can do to speed up the time it takes to download the Ethereum blockchain. If you choose to use the --fast flag to perform an Ethereum fast sync, you will not retain past transaction data.

注解

You cannot use this flag after performing all or part of a normal sync operation, meaning you should not have any portion of the Ethereum blockchain downloaded before using this command. See this Ethereum Stack.Exchange answer for more information.

Below are some flags to use when you want to sync your client more quickly.

--fast

This flag enables fast syncing through state downloads rather than downloading the full block data. This will also reduce the size of your blockchain dramatically. NOTE: --fast can only be run if you are syncing your blockchain from scratch and only the first time you download the blockchain for security reasons. See this Reddit post for more information.

--cache=1024

Megabytes of memory allocated to internal caching (min 16MB / database forced). Default is 16MB, so increasing this to 256, 512, 1024 (1GB), or 2048 (2GB) depending on how much RAM your computer has should make a difference.

--jitvm

This flag enables the JIT VM.

Full example command with console:

geth --fast --cache=1024 --jitvm console

For more discussion on fast syncing and blockchain download times, see this Reddit post.

Exporting/Importing the blockchain

If you already have a full Ethereum node synced, you can export the blockchain data from the fully synced node and import it into your new node. You can accomplish this in geth by exporting your full node with the command geth export filename and importing the blockchain into your node using geth import filename. see this link

Static Nodes, Trusted Nodes, and Boot Nodes

Geth supports a feature called static nodes if you have certain peers you always want to connect to. Static nodes are re-connected on disconnects. You can configure permanent static nodes by putting something like the following into <datadir>/static-nodes.json (this should be the same folder that your chaindata and keystore folders are in)

[
      "enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303",
      "enode://pubkey@ip:port"
]

You can also add static nodes at runtime via the Javascript console using admin.addPeer()

> admin.addPeer("enode://f4642fa65af50cfdea8fa7414a5def7bb7991478b768e296f5e4a54e8b995de102e0ceae2e826f293c481b5325f89be6d207b003382e18a8ecba66fbaf6416c0@33.4.2.1:30303")
Common problems with connectivity

Sometimes you just can't get connected. The most common reasons are:

  • Your local time might be incorrect. An accurate clock is required to participate in the Ethereum network. Check your OS for how to resync your clock (example sudo ntpdate -s time.nist.gov) because even 12 seconds too fast can lead to 0 peers.
  • Some firewall configurations can prevent UDP traffic from flowing. You can use the static nodes feature or admin.addPeer() on the console to configure connections by hand.

To start geth without the discovery protocol, you can use the --nodiscover parameter. You only want this if you are running a test node or an experimental test network with fixed nodes.

Test Networks

Morden testnet

Morden is a public Ethereum alternative testnet. It is expected to continue throughout the Frontier and Homestead milestones of the software.

Usage
eth (C++ client)

This is supported natively on 0.9.93 and above. Pass the --morden argument in when starting any of the clients. e.g.:

> eth --morden
PyEthApp (Python client)

PyEthApp supports the morden network from v1.0.5 onwards:

> pyethapp --profile morden run
geth (Go client)
> geth --testnet
Details

All parameters are the same as the main Ethereum network except:

  • Network Name: Morden
  • Network Identity: 2
  • genesis.json (given below);
  • Initial Account Nonce (IAN) is 2^20 (instead of 0 in all previous networks).
    • All accounts in the state trie have nonce >= IAN.
    • Whenever an account is inserted into the state trie it is initialised with nonce = IAN.
  • Genesis generic block hash: 0cd786a2425d16f152c658316c423e6ce1181e15c3295826d7c9904cba9ce303
  • Genesis generic state root: f3f4696bbf3b3b07775128eb7a3763279a394e382130f27c21e70233e04946a9
Morden's genesis.json
{
                "nonce": "0x00006d6f7264656e",
                "difficulty": "0x20000",
                "mixhash": "0x00000000000000000000000000000000000000647572616c65787365646c6578",
                "coinbase": "0x0000000000000000000000000000000000000000",
                "timestamp": "0x00",
                "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
                "extraData": "0x",
                "gasLimit": "0x2FEFD8",
                "alloc": {
                                "0000000000000000000000000000000000000001": { "balance": "1" },
                                "0000000000000000000000000000000000000002": { "balance": "1" },
                                "0000000000000000000000000000000000000003": { "balance": "1" },
                                "0000000000000000000000000000000000000004": { "balance": "1" },
                                "102e61f5d8f9bc71d0ad4a084df4e65e05ce0e1c": { "balance": "1606938044258990275541962092341162602522202993782792835301376" }
                }
}
Getting Morden testnet ether

Because of decreased mining difficulty on the testnet, ether can easily mined using your CPU/GPU (see 挖矿).

Setting up a local private testnet

eth (C++ client)

It is possible to connect to or create a new network by using the --genesis and --config.

> eth --private "customChain" --config config.json --genesis genesis.json

It is possible to use both --config and --genesis.

In that case, the genesis block description provided by --config will be overwritten by the --genesis option.

--private //defines the name of the custom chain (optional).

--config <filename>

注解

<filename> contains a JSON description of the network:

  • sealEngine (engine use to mine block)

    "Ethash" is the Ethereum proof of work engine (used by the live network).

    "NoProof" no proof of work is needed to mine a block.

  • params (general network information like minGasLimit, minimumDifficulty, blockReward, networkID)

  • genesis (genesis block description)

  • accounts (setup an original state that contains accounts/contracts)

Here is a Config sample (used by the Olympic network):

{
    "sealEngine": "Ethash",
    "params": {
            "accountStartNonce": "0x00",
            "frontierCompatibilityModeLimit": "0xffffffff",
            "maximumExtraDataSize": "0x0400",
            "tieBreakingGas": false,
            "minGasLimit": "125000",
            "gasLimitBoundDivisor": "0x0400",
            "minimumDifficulty": "0x020000",
            "difficultyBoundDivisor": "0x0800",
            "durationLimit": "0x08",
            "blockReward": "0x14D1120D7B160000",
            "registrar": "5e70c0bbcd5636e0f9f9316e9f8633feb64d4050",
            "networkID" : "0x0"
    },
    "genesis": {
            "nonce": "0x000000000000002a",
            "difficulty": "0x20000",
            "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "author": "0x0000000000000000000000000000000000000000",
            "timestamp": "0x00",
            "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
            "extraData": "0x",
            "gasLimit": "0x2fefd8"
    },
    "accounts": {
            "0000000000000000000000000000000000000001": { "wei": "1", "precompiled": { "name": "ecrecover", "linear": { "base": 3000, "word": 0 } } },
            "0000000000000000000000000000000000000002": { "wei": "1", "precompiled": { "name": "sha256", "linear": { "base": 60, "word": 12 } } },
            "0000000000000000000000000000000000000003": { "wei": "1", "precompiled": { "name": "ripemd160", "linear": { "base": 600, "word": 120 } } },
            "0000000000000000000000000000000000000004": { "wei": "1", "precompiled": { "name": "identity", "linear": { "base": 15, "word": 3 } } },
            "dbdbdb2cbd23b783741e8d7fcf51e459b497e4a6": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "e6716f9544a56c530d868e4bfbacb172315bdead": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "b9c015918bdaba24b4ff057a92a3873d6eb201be": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "1a26338f0d905e295fccb71fa9ea849ffa12aaf4": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "2ef47100e0787b915105fd5e3f4ff6752079d5cb": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "cd2a3d9f938e13cd947ec05abc7fe734df8dd826": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "6c386a4b26f73c802f34673f7248bb118f97424a": { "wei": "1606938044258990275541962092341162602522202993782792835301376" },
            "e4157b34ea9615cfbde6b4fda419828124b70c78": { "wei": "1606938044258990275541962092341162602522202993782792835301376" }
    }
}

--genesis <filename> (optional if the config option is provided and contains the genesis description).

注解

<filename> contains a JSON description of the genesis block:

The content is the same as the genesis field provided by the 'config' parameter:

{
              "nonce": "0x000000000000002a",
              "difficulty": "0x20000",
              "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
              "author": "0x0000000000000000000000000000000000000000",
              "timestamp": "0x00",
              "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
              "extraData": "0x",
              "gasLimit": "0x2fefd8"
}

geth (Go client)

You either pre-generate or mine your own ether on a private testnet. It is a much more cost effective way of trying out Ethereum and you can avoid having to mine or find Morden test ether.

The things that are required to specify in a private chain are:
  • Custom Genesis File
  • Custom Data Directory
  • Custom NetworkID
  • (Recommended) Disable Node Discovery
The genesis file

The genesis block is the start of the blockchain - the first block, block 0, and the only block that does not point to a predecessor block. The protocol ensures that no other node will agree with your version of the blockchain unless they have the same genesis block, so you can make as many private testnet blockchains as you'd like!

CustomGenesis.json

{
    "config": { }, "nonce": "0x0000000000000042",     "timestamp": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "extraData": "0x00",     "gasLimit": "0x8000000",     "difficulty": "0x400",
    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x3333333333333333333333333333333333333333",     "alloc": {     }
}

Save a file called CustomGenesis.json. You will reference this when starting your geth node using the following command:

geth init /path/to/CustomGenesis.json

注解

By default geth will use the same directory for network related files as for the public mainnet. Thus you are advised to set a custom --datadir to keep the public network's chaindata from bing reset.

Command line parameters for private network

There are some command line options (also called “flags”) that are necessary in order to make sure that your network is private. We already covered the genesis flag, but we need a few more. Note that all of the commands below are to be used in the geth Ethereum client.

--nodiscover

Use this to make sure that your node is not discoverable by people who do not manually add you. Otherwise, there is a chance that your node may be inadvertently added to a stranger's blockchain if they have the same genesis file and network id.

--maxpeers 0

Use maxpeers 0 if you do not want anyone else connecting to your test chain. Alternatively, you can adjust this number if you know exactly how many peers you want connecting to your node.

--rpc

This will enable RPC interface on your node. This is generally enabled by default in Geth.

--rpcapi "db,eth,net,web3"

This dictates what APIs that are allowed to be accessed over RPC. By default, Geth enables the web3 interface over RPC.

IMPORTANT: Please note that offering an API over the RPC/IPC interface will give everyone access to the API who can access this interface (e.g. dapp's). Be careful which API's you enable. By default geth enables all API's over the IPC interface and only the db,eth,net and web3 API's over the RPC interface.

--rpcport "8080"

Change 8000 to any port that is open on your network. The default for geth is 8080.

--rpccorsdomain "http://chriseth.github.io/browser-solidity/"

This dictates what URLs can connect to your node in order to perform RPC client tasks. Be very careful with this and type a specific URL rather than the wildcard (*) which would allow any URL to connect to your RPC instance.

--datadir "/home/TestChain1"

This is the data directory that your private chain data will be stored in (under the nubits . Choose a location that is separate from your public Ethereum chain folder.

--port "30303"

This is the "network listening port", which you will use to connect with other peers manually.

--identity "TestnetMainNode"

This will set up an identity for your node so it can be identified more easily in a list of peers. Here is an example of how these identities show up on the network.

Launching geth

After you have created your custom genesis block JSON file and created a directory for your blockchain data, type the following command into your console that has access to geth:

geth --identity "MyNodeName" --rpc --rpcport "8080" --rpccorsdomain "*" --datadir "C:\chains\TestChain1" --port "30303" --nodiscover --rpcapi "db,eth,net,web3" --networkid 1999 init /path/to/CustomGenesis.json

注解

Please change the flags to match your custom settings.

This will initialize your genesis block. To interact with geth through the console enter:

geth --identity "MyNodeName" --rpc --rpcport "8080" --rpccorsdomain "*" --datadir "C:\chains\TestChain1" --port "30303" --nodiscover --rpcapi "db,eth,net,web3" --networkid 1999 console

You will need to start your geth instance with your custom chain command every time you want to access your custom chain. If you just type "geth" in your console, it will not remember all of the flags you have set.

The full list of methods available through the javascript console is available on the geth wiki on github

If you already have a geth node running, you can attach another geth instance to it using:

geth attach

Now you'll need to initialize a new account on the testnest, and set it as your etherbase (the address that will receive mining rewards).

In the javascript console type

personal.newAccount("password")

注解

Replace with the password of your choice

Now we'll set it as the etherbase:

miner.setEtherbase(personal.listAccounts[0])

If successful, the console will print "true"

Finally, you are ready to start mining test ether:

miner.start()
Pre-allocating ether to your account

A difficulty of "0x400" allows you to mine Ether very quickly on your private testnet chain. If you create your chain and start mining, you should have hundreds of ether in a matter of minutes which is way more than enough to test transactions on your network. If you would still like to pre-allocate Ether to your account, you will need to:

  1. Create a new Ethereum account after you create your private chain
  2. Copy your new account address
  3. Add the following command to your Custom_Genesis.json file:
"alloc":
{
        "<your account address e.g. 0x1fb891f92eb557f4d688463d0d7c560552263b5a>":
        { "balance": "20000000000000000000" }
}

注解

Replace 0x1fb891f92eb557f4d688463d0d7c560552263b5a with your account address.

Save your genesis file and rerun your private chain command. Once geth is fully loaded, close it by .

We want to assign an address to the variable primary and check its balance.

Run the command geth account list in your terminal to see what account # your new address was assigned.

> geth account list
Account #0: {d1ade25ccd3d550a7eb532ac759cac7be09c2719}
Account #1: {da65665fc30803cb1fb7e6d86691e20b1826dee0}
Account #2: {e470b1a7d2c9c5c6f03bbaa8fa20db6d404a0c32}
Account #3: {f4dd5c3794f1fd0cdc0327a83aa472609c806e99}

Take note of which account # is the one that you pre-allocated ether to. Alternatively, you can launch the console with geth console (keep the same parameters as when you launched geth first). Once the prompt appears, type

> eth.accounts

This will return the array of account addresses you possess.

> primary = eth.accounts[0]

注解

Replace 0 with your account's index. This console command should return your primary Ethereum address.

Type the following command:

> balance = web3.fromWei(eth.getBalance(primary), "ether");

This should return 7.5 indicating you have that much ether in your account. The reason we had to put such a large number in the alloc section of your genesis file is because the "balance" field takes a number in wei which is the smallest denomination of the Ethereum currency ether (see Ether).

挖矿

简介

挖矿这个词源于对加密货币与黄金的类比。黄金或贵金属很稀有，电子代币也是，增加总量的唯一方法就是挖矿。以太坊也是这样，发行的唯一办法就是挖矿。但是不像其他例子，挖矿也是通过在区块链中创建、验证、发行和传播区块来保护网络的方法。

  • 挖以太币 = 保护网络 = 验证计算

什么是挖矿?

以太坊，和所有区块链技术一样，使用激励驱动的安全模式。共识基于选择具有最高总难度的区块。矿工创造区块，其他人检测有效性。区块只有在包含特定 难度 的 工作量 (POW)时才有效，还有其他合格性条件。请注意到以太坊Serenity里程碑，可能就会被取代（参考 proof of stake model ）。

以太坊区块链在很多方面与比特币区块链类似，但也有些不同。在区块链架构方面，以太坊和比特币之间最主要的的区别是，不像比特币，以太坊区块不仅包含交易列表也包含最近状态（merkle patricia trie结构的根hash编码在状态中更精确）除此之外，另外两个值，区块数和难度，也储存在区块中。

使用的工作量证明算法叫 Ethash （ Dagger-Hashimoto algorithm 的改良版本），包括找到算法的 随机数 输入以使结果低于特定的难度阈值。工作量证明算法的意义在于，要找到这样一个随机数，没有比列举可能性更好的策略，而解决方法的验证琐碎又廉价。由于输出有均匀分布（是散表功能应用的结果），我们可以保证，平均而言，需要找到这样一个随机数的时间取决于难度阈值。这使得只通过操纵难度来控制找到新区块的时间成为可能。

正如协议中所描述的，难度动态调整的方式是每15秒整个网络会产生一个区块。我们说网络用 15秒区块时间 生产一个区块链。这个"心跳"基本上主要强调系统状态同步，保证不可能维持一个分叉（允许double spend）或被恶意分子重写历史，除非攻击者有半数以上的网络挖矿能力（即所谓的 51% 攻击）。

任何参与到网络的节点都可能是矿工，预期的挖矿收益和他们的（相对）挖矿能力或者说 hashrate 成正比，比如被网络总散表率标准化的，每秒尝试的随机数数量。

Ethash工作量证明是 内存难解 的，这使它能 抵抗ASIC 。内存难解性由工作量证明算法实现，需要选择依靠随机数和区块标题的固定资源的子集合。这个资源（几十亿字节大小的数据）叫做 DAG 。每3000个区块的 DAG 完全不同，125小时的窗口叫做 **epoch**（大约5.2天），需要一点时间来生成。由于DAG只由区块高度决定，它可以被事先生成，如果没有被事先生成，客户端需要等到进程最后来生产区块。如果客户端没有预生成并提前缓存DAG，网络可能会在每个epoch过渡经历大规模区块延迟。注意不必要生成DAG以验证工作量证明，它可以在低CPU和小内存的状态下被验证。

在特殊情况下，从零开始创建节点的时候，只有在为现存epoch创建DAG的时候才会开始挖矿。

挖矿奖励

获奖区块的成功工作量证明矿工会获得：

  • "获胜"区块的 静态区块奖 ，包含5.0个以太币
  • 区块内支出的gas成本 — 一定数量的以太币，取决于当前gas价格
  • 叔伯块的额外奖励，形式是每个叔伯块包含额外的1/32

在区块中执行所有交易所消费的、由获胜矿工提交的gas都由每个交易的发送者支付。已发生的gas成本归到矿工账户作为共识协议的一部分。随着时间变化，这会使数据区块奖变得矮小。

叔伯块 是稳定的区块，比如说，和包含先前区块（最多回6个区块）的父区块。有效的叔伯块会受到奖励以中和网络滞后给挖矿奖励带来的影响，因而提升安全性（这叫做GHOST协议）。叔伯块由成功工作量证明矿工形成的区块中所包含的叔伯块接收7/8的数据区块奖励（=4.375以太币）。每个区块最多允许2个叔伯块。

挖矿的成功取决于设定的区块难度。区块难度动态调整每个区块，以规定网络散列能力来创造12秒区块时间。找到区块的机会因此由与难度相关的散列率产生。

Ethash DAG

Ethash将 DAG*（有向非循环图）用于工作量证明算法，这是为每个 *epoch 生成，例如，每3000个区块（125个小时，大约5.2天）。DAG要花很长时间生成。如果客户端只是按需要生成它，那么在找到新epoch第一个区块之前，每个epoch过渡都要等待很长时间。然而，DAG只取决于区块数量，所以可以预先计算来避免在每个epoch过渡过长的等待时间。 Geth 和 ethminer 执行自动的DAG生成，每次维持2个DAG以便epoch过渡流畅。挖矿从控制台操控的时候，自动DAG生成会被打开和关闭。如果 geth 用 --mine 选项启动的时候，也会默认打开。注意客户端分享DAG资源，如果你运行任何客户端的多个实例，确保自动的DAG生成只在一个实例中打开。

为任意epoch生成DAG：

geth makedag <block number> <outputdir>

例如 geth makedag 360000 ~/.ethash 。请注意ethash为DAG使用 ~/.ethash (Mac/Linux) 或 ~/AppData/Ethash (Windows)，这样它可以在不同的客户端实现以及多个运行实例中分享。

算法

我们的算法， Ethash （之前被称为Dagger-Hashimoto），是基于一个大的、瞬时的、任意生成的、形成DAG（Dagger-part）的资料组规定，尝试解决它一个特定的约束，部分通过区块标题散列来决定。

它被设计用于在一个只有慢CPU的环境中来散列快速验证时间，但在被提供大量高带宽内存时，为挖矿提供大量的加速。大量内存需求意味着大规模矿工获得相对少的超线性利益。高带宽需求意味着从堆在很多超速处理单元、分享同样内存的加速在每个单独的单元给出很少的利益。没有节点验证的利益因而阻碍中心化，这在挖矿中很重要。

外部挖矿应用和以太坊工作规定和报送的后台程序之间的交流通过JSON-RPC API发生。提供两个RPC功能； eth_getWork 和 eth_submitWork 。

这些被正式记录在维基百科文章 miner 的 JSON-RPC API 条目下。

为了挖矿你需要一个完全同步的、能够挖矿的以太坊客户端和至少一个以太坊账户。这个账户用于发送挖矿奖励，通常被称为 货币基 或 以太基 。查看 "创建账号" 章节，学习如何创建帐户。

警告

开始挖矿前，确保区块链和主链完全同步，否则就不能在主链上挖矿。

CPU 挖矿

你可以用电脑的中央处理器（CPU）挖以太币。自从GPU矿工的效率高出两个数量级，它就不再盈利了。然而你可以用CPU挖掘在Morden测试网或私有链上挖矿，以便创建你测试合约和交易所需要的以太币， 而无需花费实时网络上的真实以太币。

注解

测试网以太币除了用于测试目的外没有其他价值（查看 Test Networks ）。

使用geth

用 geth 启动以太坊节点时，并不是默认挖掘。在CPU挖掘模式开启，你会用 --mine 命令行选项 。 --minerthreads 参数可以用于设置平行于挖掘线程的数量（默认为处理器核心的总数）。

geth --mine --minerthreads=4

你也可以在执行期间用 console 开启或停止CPU挖掘。 miner.start 取一个矿工线程数量的可选参数。

> miner.start(8)
true
> miner.stop()
true

注意挖掘真实以太币只有在你与网络同步时才有意义（由于你是在共识区块顶部挖矿）。因此以太区块链下载器/同步器会延迟挖掘直到同步完成，此后挖掘自动开始，除非你用 miner.stop() 取消挖矿。

为了赚取以太币，你必须有 etherbase （或 coinbase ）地址集。这个etherbase默认为你的第一个账户。如果你没有etherbase地址， ``geth --mine``就不会开启。

你可以在命令行重新设置etherbase：

geth --etherbase 1 --mine  2>> geth.log // 1 is index: second account by creation order OR
geth --etherbase '0xa4d8e9cae4d04b093aac82e6cd355b6b963fb7ff' --mine 2>> geth.log

你也可以在控制台重新设置etherbase：

miner.setEtherbase(eth.accounts[2])

注意你的etherbase不必是本地账户地址，只要是现存的就可以。

有一个给你挖掘过的区块 添加额外数据 （只有32字节）的选项。按照惯例，它被解释为统一码字符串，你可以设置短期虚荣标签。

miner.setExtra("ΞTHΞЯSPHΞЯΞ")
...
debug.printBlock(131805)
BLOCK(be465b020fdbedc4063756f0912b5a89bbb4735bd1d1df84363e05ade0195cb1): Size: 531.00 B TD: 643485290485 {
NoNonce: ee48752c3a0bfe3d85339451a5f3f411c21c8170353e450985e1faab0a9ac4cc
Header:
[
...
        Coinbase:           a4d8e9cae4d04b093aac82e6cd355b6b963fb7ff
        Number:             131805
        Extra:              ΞTHΞЯSPHΞЯΞ
...
}

你可以用 miner.hashrate 检查算力，结果用H/s表示（每秒hash操作）。

> miner.hashrate
712000

成功挖掘一些区块以后，你可以检查etherbase账户中的以太币余额。现在假定你的etherbase是个本地账户：

> eth.getBalance(eth.coinbase).toNumber();
'34698870000000'

为了花费你赚的gas来交易，你需要解锁账户。

> personal.unlockAccount(eth.coinbase)
Password
true

你可以在控制台上用以下代码片段，检查哪个区块被特殊的矿工（地址）挖掘过：

function minedBlocks(lastn, addr) {
  addrs = [];
  if (!addr) {
    addr = eth.coinbase
  }
  limit = eth.blockNumber - lastn
  for (i = eth.blockNumber; i >= limit; i--) {
    if (eth.getBlock(i).miner == addr) {
      addrs.push(i)
    }
  }
  return addrs
}
// scans the last 1000 blocks and returns the blocknumbers of blocks mined by your coinbase
// (more precisely blocks the mining reward for which is sent to your coinbase).
minedBlocks(1000, eth.coinbase);
//[352708, 352655, 352559]

请注意，发现一个区块但是不能把它变成典型链会经常发生。这意味着你在当地把挖过的区块包括在内，当前的状态会显示归于你账户的挖矿奖励，然而不久后，会发现更好的链，我们转换到不包含你区块的链，因而不会记入任何挖矿奖励。因此很有可能矿工监控coinbase余额的时候会发现，它发生了相当程度的浮动。

GPU挖矿

硬件

算法是内存难解的，为了使DAG适合内存，每个GPU需要1-2GB内存，如果你得到错误提示： Error GPU mining. GPU memory fragmentation? 说明你没有足够的内存。GPU挖矿软件是基于OpenCL实现的，AMD GPU会比同一水准的NVIDIA GPU“更快”。ASIC和FPGA相对低效因而被阻拦。要给芯片集成平台获取openCL，尝试：

Ubuntu Linux设置

对于这个快速指南，你会需要Ubuntu 14.04或15.04以及fglrx图像驱动器。你也可以使用NVidia驱动器和其他平台，但是你必须要找到自己的方式来获得有效的OpenCL安装，比如 Genoil's ethminer fork 。

如果你在用15.04，转到"软件与更新 > 额外的驱动器"设置为"从fglrx为AMD图形加速器使用视频驱动器"。

如果你在用14.04，转到"软件与更新 > 额外的驱动器"设置为"从fglrx为AMD图形加速器使用视频驱动器"。很遗憾，对于一些人来说，这种方法可能不管用，因为Ubuntu 14.04.02中有个已知的程序错误会阻止你转换到GPU挖矿所必须的专属图形驱动器。

所以，如果你遇到这个程序错误，先到"软件与更新 > 更新"选择"预发行的可靠更新提议"。然后，回到"软件与更新 > 额外的驱动器"设置为"从fglrx为AMD图形加速器使用视频驱动器"。重启之后，值得检查一下现在确实正确安装了驱动器（例如通过再到"额外驱动器"）。

不管做什么，如果你在用14.04.02，一旦安装之后，就不要改变驱动器或者驱动器配置。例如，aticonfig –-initial的使用（尤其是-f, –-force选项）会"破坏"你的设置。如果你偶然改变了配置，会需要卸载驱动器，重启，再次安装驱动器并重启。

Mac设置

wget http://developer.download.nvidia.com/compute/cuda/7_0/Prod/local_installers/cuda_7.0.29_mac.pkg
sudo installer -pkg ~/Desktop/cuda_7.0.29_mac.pkg -target /
brew update
brew tap ethereum/ethereum
brew reinstall cpp-ethereum --with-gpu-mining --devel --headless --build-from-source

查看冷却状态：

aticonfig --adapter=0 --od-gettemperature

Windows设置

下载最新的Eth++安装包 ，在安装界面的"选择组件"页面选择ethminer。

_images/eth_miner_setup.png

用geth使用ethminer

geth account new // Set-up ethereum account if you do not have one
geth --rpc --rpccorsdomain localhost 2>> geth.log &
ethminer -G  // -G for GPU, -M for benchmark
tail -f geth.log

ethminer 在端口8545（geth的默认RPC端口）和geth沟通。你可以通过给 geth --rpcport 选项来改变这种情况。ethminer会在任何端口发现geth。注意你需要用 --rpccorsdomain localhos 设置CORS标题。你也可以用 --Fhttp://127.0.0.1:3301 在 ethminer 设置端口。如果你想要在同一个电脑上挖几个实例，设置端口是必需的，尽管有些没有意义。如果你在私有链上测试，我们推荐你用CPU挖掘代替。

注解

你 不需要 把 --mine 选项给 geth ，或者在控制台开启挖矿，除非你想要在GPU挖掘顶端做CPU挖掘。

如果 ethminer 的默认无效，试试用 --opencl-device X 来规定OpenCL装置，其中X是{0, 1, 2,…}。用 -M （基础测试程序）运行 ethminer 时，你会看到如下的提示：

Benchmarking on platform: { "platform": "NVIDIA CUDA", "device": "GeForce GTX 750 Ti", "version": "OpenCL 1.1 CUDA" }


Benchmarking on platform: { "platform": "Apple", "device": "Intel(R) Xeon(R) CPU E5-1620 v2 @ 3.70GHz", "version": "OpenCL 1.2 " }

调试 geth :

geth  --rpccorsdomain "localhost" --verbosity 6 2>> geth.log

调试挖矿:

make -DCMAKE_BUILD_TYPE=Debug -DETHASHCL=1 -DGUI=0
gdb --args ethminer -G -M

注解

GPU挖矿时，散列率信息在 geth 上不可用。

用 ethminer 检查散列率， miner.hashrate 总会报告0。

用eth使用ethminer

在单独的GPU上挖矿

为了在单独的GPU上挖矿，只需要用以下参数运行eth：

eth -v 1 -a 0xcadb3223d4eebcaa7b40ec5722967ced01cfc8f2 --client-name "OPTIONALNAMEHERE" -x 50 -m on -G
  • -v 1 将冗长的信息设置为1。不要被信息刷屏。
  • -a YOURWALLETADDRESS 设置挖矿奖励会去的coinbase。以上地址只是一个例子。这一参数十分重要，确保不要在钱包地址出错，否则会接收不到以太币支出。
  • --client-name "OPTIONAL" 设置可选择的客户端名称，在网络上确定身份。
  • -x 50 请求大量的端点。帮助在开始找到端点。
  • -m on 在挖矿开启的状态下实际启动。
  • -G 打开GPU挖掘。

客户端运行时，你可以用geth附属或 ethconsole 和它互动。

在多个GPU上挖矿

用多个GPU和eth挖矿与用geth和多个GPU挖矿十分相似。确保eth节点和正确设置的coinbase地址一起运行：

eth -v 1 -a 0xcadb3223d4eebcaa7b40ec5722967ced01cfc8f2 --client-name "OPTIONALNAMEHERE" -x 50 -j

注意我们也添加了-j参数以使客户端有可用的JSON-RPC服务器与ethminer实例沟通。此外由于ethminer可以为我们挖矿，我们移除了与挖矿相关的参数。每个GPU都会执行一个不同的ethminer实例：

ethminer --no-precompute -G --opencl-device X

X是索引号码，与你想ethminer用{0, 1, 2,…}的OpenCL装置一致。为了轻松获取OpenCL装置列表，你可以执行 ethminer --list-devices ，它会提供一个OpenCL可以检测到的所有装置，以及每个装置的一些附加信息。

下面是一个示例输出：

[0] GeForce GTX 770
    CL_DEVICE_TYPE: GPU
    CL_DEVICE_GLOBAL_MEM_SIZE: 4286345216
    CL_DEVICE_MAX_MEM_ALLOC_SIZE: 1071586304
    CL_DEVICE_MAX_WORK_GROUP_SIZE: 1024

最终 --no-precompute 参数请求ethiminers不要提前创建下一个epoch的DAG。尽管不推荐这样，因为每次epoch过渡的时候，你都会有一个挖矿中断。

基准测试程序

挖矿能力通常以内存带宽衡量。我们的实现写在OpenCL上，很典型地在NVidia上被AMD GPU支持得更好。实验证据确认了在价格方面，AMD GPU比对应的NVidia挖矿表现更好。

用基准程序测试单一装置设置，你可以在基准测试程序模式下通过-M使用ethminer。

ethminer -G -M

如果你有很多装置，你会喜欢分别用基准程序测试，可以用 –opencl-device 选项，与之前章节相似:

ethminer -G -M --opencl-device X

用 ethminer --list-devices 来列出可能的数字替代X {0, 1, 2,…}。

开始在Windows上挖矿，首先要 下载geth windows binary 。

  • 解压缩Geth (单击右键选择打开)，启用命令提示符。用cd导航到Geth数据文件夹的位置(例如 cd / 到 C: 盘)。
  • 输入 geth --rpc 开启geth。

进入以后，以太坊区块链会开始下载。有时候防火墙肯能会阻止同步进程（阻止时会有提示）。如果被阻止，点击"允许进入"。

  • 首先 下载安装ethminer ， C++挖矿软件 (防火墙或Windows本身可能会有反应，允许进入)。
  • 打开另一个命令提示符 (保持第一个运行！)输入 cd/Program\ Files/Ethereum(++)/release 改变目录。
  • 确保 geth 完成区块链同步。如果同步不再进行，就可以在命令提示符输入 ethminer -G 开启挖矿进程。

此时可能会出现一些问题。如果有错误发生， 可以输入 Ctrl+C 来中断矿工。如果错误显示(提示）"内存不足"，就说明没有足够的GPU内存来挖以太币。

矿池挖矿

矿池挖矿是旨在通过联合参与矿工的挖矿力来解决预期收益问题的合作社（挖矿的矿工的算力来解决预期收益问题的合作组织）。作为回报，通常收取0-5%的挖矿奖励。挖矿池从中央账户用工作量证明提交区块并按照参与人贡献的挖矿力比例来重新分配奖励。

警告

大多数挖矿池包含第三方，中心组件，意味着他们是不需信任的。换言之，挖矿池操作人可以把你的收入拿走。谨慎操作。有很多具备开源数据库、不需信任的、去中心化的挖矿池。

警告

挖矿池只会外包工作量证明运算，他们不会使区块生效或运行虚拟机来检查执行交易带来的状态过渡。 这能有效地使挖矿池在安全方面像单个节点一样表现，他们的增长会造成`51% 攻击 <https://learncryptography.com/cryptocurrency/51-attack>`_ 的中心化威胁。确保遵守网络能力分配，不要让挖矿池长得太大。

矿池

合约与交易

Account Types, Gas, and Transactions

EOA vs contract accounts

There are two types of accounts in Ethereum
  • Externally Owned Accounts
  • Contracts Accounts

This distinction might be eliminated in Serenity.

Externally owned accounts (EOAs)

An externally controlled account

  • has an ether balance,
  • can send transactions (ether transfer or trigger contract code),
  • is controlled by private keys,
  • has no associated code.
Contract accounts

A contract

  • has an ether balance,
  • has associated code,
  • code execution is triggered by transactions or messages (calls) received from other contracts.
  • when executed - perform operations of arbitrary complexity (Turing completeness) - manipulate its own persistent storage, i.e., can have its own permanent state - can call other contracts

All action on the Ethereum block chain is set in motion by transactions fired from externally owned accounts. Every time a contract account receives a transaction, its code is executed as instructed by the input parameters sent as part of the transaction. The contract code is executed by the Ethereum Virtual Machine on each node participating in the network as part of their verification of new blocks.

This execution needs to be completely deterministic, its only context is the position of the block on the blockchain and all data available. The blocks on the blockchain represent units of time, the blockchain itself is a temporal dimension and represents the entire history of states at the discrete time points designated by the blocks on the chain.

All ether balances and values are denominated in units of wei: 1 ether is 1e18 wei.

注解

"Contracts" in Ethereum should not be seen as something that should be "fulfilled" or "complied with"; rather, they are more like "autonomous agents" that live inside of the Ethereum execution environment, always executing a specific piece of code when "poked" by a message or transaction, and having direct control over their own ether balance and their own key/value store to store their permanent state.

What is a transaction?

The term "transaction" is used in Ethereum to refer to the signed data package that stores a message to be sent from an externally owned account to another account on the blockchain.

Transactions contain:
  • the recipient of the message,
  • a signature identifying the sender and proving their intention to send the message via the blockchain to the recipient,
  • VALUE field - The amount of wei to transfer from the sender to the recipient,
  • an optional data field, which can contain the message sent to a contract,
  • a STARTGAS value, representing the maximum number of computational steps the transaction execution is allowed to take,
  • a GASPRICE value, representing "Wei per gas". One Wei corresponds to 0.000000000000000001 Ether.

What is a message?

Contracts have the ability to send "messages" to other contracts. Messages are virtual objects that are never serialized and exist only in the Ethereum execution environment. They can be conceived of as function calls.

A message contains:
  • the sender of the message (implicit).
  • the recipient of the message
  • VALUE field - The amount of wei to transfer alongside the message to the contract address,
  • an optional data field, that is the actual input data to the contract
  • a STARTGAS value, which limits the maximum amount of gas the code execution triggered by the message can incur.

Essentially, a message is like a transaction, except it is produced by a contract and not an external actor. A message is produced when a contract currently executing code executes the CALL or DELEGATECALL opcodes, which produces and executes a message. Like a transaction, a message leads to the recipient account running its code. Thus, contracts can have relationships with other contracts in exactly the same way that external actors can.

What is gas?

Ethereum implements an execution environment on the blockchain called the Ethereum Virtual Machine (EVM). Every node participating in the network runs the EVM as part of the block verification protocol. They go through the transactions listed in the block they are verifying and run the code as triggered by the transaction within the EVM. Each and every full node in the network does the same calculations and stores the same values. Clearly Ethereum is not about optimising efficiency of computation. Its parallel processing is redundantly parallel. This is to offer an efficient way to reach consensus on the system state without needing trusted third parties, oracles or violence monopolies. But importantly they are not there for optimal computation. The fact that contract executions are redundantly replicated across nodes, naturally makes them expensive, which generally creates an incentive not to use the blockchain for computation that can be done offchain.

When you are running a decentralized application (dapp), it interacts with the blockchain to read and modify its state, but dapps will typically only put the business logic and state that are crucial for consensus on the blockchain.

When a contract is executed as a result of being triggered by a message or transaction, every instruction is executed on every node of the network. This has a cost: for every executed operation there is a specified cost, expressed in a number of gas units.

Gas is the name for the execution fee that senders of transactions need to pay for every operation made on an Ethereum blockchain. The name gas is inspired by the view that this fee acts as cryptofuel, driving the motion of smart contracts. Gas is purchased for ether from the miners that execute the code. Gas and ether are decoupled deliberately since units of gas align with computation units having a natural cost, while the price of ether generally fluctuates as a result of market forces. The two are mediated by a free market: the price of gas is actually decided by the miners, who can refuse to process a transaction with a lower gas price than their minimum limit. To get gas you simply need to add ether to your account. The Ethereum clients automatically purchase gas for your ether in the amount you specify as your maximum expenditure for the transaction.

The Ethereum protocol charges a fee per computational step that is executed in a contract or transaction to prevent deliberate attacks and abuse on the Ethereum network. Every transaction is required to include a gas limit and a fee that it is willing to pay per gas. Miners have the choice of including the transaction and collecting the fee or not. If the total amount of gas used by the computational steps spawned by the transaction, including the original message and any sub-messages that may be triggered, is less than or equal to the gas limit, then the transaction is processed. If the total gas exceeds the gas limit, then all changes are reverted, except that the transaction is still valid and the fee can still be collected by the miner. All excess gas not used by the transaction execution is reimbursed to the sender as Ether. You do not need to worry about overspending, since you are only charged for the gas you consume. This means that it is useful as well as safe to send transactions with a gas limit well above the estimates.

Estimating transaction costs

The total ether cost of a transaction is based on 2 factors:

gasUsed is the total gas that is consumed by the transaction

gasPrice price (in ether) of one unit of gas specified in the transaction

Total cost = gasUsed * gasPrice

gasUsed

Each operation in the EVM was assigned a number of how much gas it consumes. gasUsed is the sum of all the gas for all the operations executed. There is a spreadsheet which offers a glimpse to some of the analysis behind this.

For estimating gasUsed, there is an estimateGas API that can be used but has some caveats.

gasPrice

A user constructs and signs a transaction, and each user may specify whatever gasPrice they desire, which can be zero. However, the Ethereum clients launched at Frontier had a default gasPrice of 0.05e12 wei. As miners optimize for their revenue, if most transactions are being submitted with a gasPrice of 0.05e12 wei, it would be difficult to convince a miner to accept a transaction that specified a lower, or zero, gasPrice.

Example transaction cost

Let’s take a contract that just adds 2 numbers. The EVM OPCODE ADD consumes 3 gas.

The approximate cost, using the default gas price (as of January 2016), would be:

3 * 0.05e12 = 1.5e11 wei

Since 1 ether is 1e18 wei, the total cost would be 0.00000015 Ether.

This is a simplification since it ignores some costs, such as the cost of passing the 2 numbers to contract, before they can even be added.

Operation Name Gas Cost Remark
step 1 default amount per execution cycle
stop 0 free
suicide 0 free
sha3 20  
sload 20 get from permanent storage
sstore 100 put into permanent storage
balance 20  
create 100 contract creation
call 20 initiating a read-only call
memory 1 every additional word when expanding memory
txdata 5 every byte of data or code for a transaction
transaction 500 base fee transaction
contract creation 53000 changed in homestead from 21000

Account interactions example - betting contract

As previously mentioned, there are two types of accounts:

  • Externally owned account (EOAs): an account controlled by a private key, and if you own the private key associated with the EOA you have the ability to send ether and messages from it.
  • Contract: an account that has its own code, and is controlled by code.

By default, the Ethereum execution environment is lifeless; nothing happens and the state of every account remains the same. However, any user can trigger an action by sending a transaction from an externally owned account, setting Ethereum's wheels in motion. If the destination of the transaction is another EOA, then the transaction may transfer some ether but otherwise does nothing. However, if the destination is a contract, then the contract in turn activates, and automatically runs its code.

The code has the ability to read/write to its own internal storage (a database mapping 32-byte keys to 32-byte values), read the storage of the received message, and send messages to other contracts, triggering their execution in turn. Once execution stops, and all sub-executions triggered by a message sent by a contract stop (this all happens in a deterministic and synchronous order, ie. a sub-call completes fully before the parent call goes any further), the execution environment halts once again, until woken by the next transaction.

Contracts generally serve four purposes:

  • Maintain a data store representing something which is useful to either other contracts or to the outside world; one example of this is a contract that simulates a currency, and another is a contract that records membership in a particular organization.
  • Serve as a sort of externally-owned account with a more complicated access policy; this is called a "forwarding contract" and typically involves simply resending incoming messages to some desired destination only if certain conditions are met; for example, one can have a forwarding contract that waits until two out of a given three private keys have confirmed a particular message before resending it (ie. multisig). More complex forwarding contracts have different conditions based on the nature of the message sent. The simplest use case for this functionality is a withdrawal limit that is overrideable via some more complicated access procedure. A wallet contract is a good example of this.
  • Manage an ongoing contract or relationship between multiple users. Examples of this include a financial contract, an escrow with some particular set of mediators, or some kind of insurance. One can also have an open contract that one party leaves open for any other party to engage with at any time; one example of this is a contract that automatically pays a bounty to whoever submits a valid solution to some mathematical problem, or proves that it is providing some computational resource.
  • Provide functions to other contracts, essentially serving as a software library.

Contracts interact with each other through an activity that is alternately called either "calling" or "sending messages". A "message" is an object containing some quantity of ether, a byte-array of data of any size, the addresses of a sender and a recipient. When a contract receives a message, it has the option of returning some data, which the original sender of the message can then immediately use. In this way, sending a message is exactly like calling a function.

Because contracts can play such different roles, we expect that contracts will be interacting with each other. As an example, consider a situation where Alice and Bob are betting 100 GavCoin that the temperature in San Francisco will not exceed 35ºC at any point in the next year. However, Alice is very security-conscious, and as her primary account uses a forwarding contract which only sends messages with the approval of two out of three private keys. Bob is paranoid about quantum cryptography, so he uses a forwarding contract which passes along only messages that have been signed with Lamport signatures alongside traditional ECDSA (but because he's old fashioned, he prefers to use a version of Lamport sigs based on SHA256, which is not supported in Ethereum directly).

The betting contract itself needs to fetch data about the San Francisco weather from some contract, and it also needs to talk to the GavCoin contract when it wants to actually send the GavCoin to either Alice or Bob (or, more precisely, Alice or Bob's forwarding contract). We can show the relationships between the accounts thus:

_images/contract_relationship.png

When Bob wants to finalize the bet, the following steps happen:

  1. A transaction is sent, triggering a message from Bob's EOA to his forwarding contract.
  2. Bob's forwarding contract sends the hash of the message and the Lamport signature to a contract which functions as a Lamport signature verification library.
  3. The Lamport signature verification library sees that Bob wants a SHA256-based Lamport sig, so it calls the SHA256 library many times as needed to verify the signature.
  4. Once the Lamport signature verification library returns 1, signifying that the signature has been verified, it sends a message to the contract representing the bet.
  5. The bet contract checks the contract providing the San Francisco temperature to see what the temperature is.
  6. The bet contract sees that the response to the messages shows that the temperature is above 35ºC, so it sends a message to the GavCoin contract to move the GavCoin from its account to Bob's forwarding contract.

Note that the GavCoin is all "stored" as entries in the GavCoin contract's database; the word "account" in the context of step 6 simply means that there is a data entry in the GavCoin contract storage with a key for the bet contract's address and a value for its balance. After receiving this message, the GavCoin contract decreases this value by some amount and increases the value in the entry corresponding to Bob's forwarding contract's address. We can see these steps in the following diagram:

_images/contract_relationship2.png

Signing transactions offline

[ Maybe add this to the FAQ and point to the ethkey section of turboethereum guide? ]

Contracts

What is a contract?

A contract is a collection of code (its functions) and data (its state) that resides at a specific address on the Ethereum blockchain. Contract accounts are able to pass messages between themselves as well as doing practically Turing complete computation. Contracts live on the blockchain in a Ethereum-specific binary format called Ethereum Virtual Machine (EVM) bytecode.

Contracts are typically written in some high level language such as Solidity and then compiled into bytecode to be uploaded on the blockchain.

参见

Other languages also exist, notably Serpent and LLL, which are described further in the Ethereum high level languages section of this documentation.

Dapp development resources lists the integrated development environments, developer tools that help you develop in these languages, offering testing, and deployment support among other features.

Ethereum high level languages

Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode) that is executed by the Ethereum Virtual Machine (EVM). However, contracts are typically written in a higher level language and then compiled using the EVM compiler into byte code to be deployed to the blockchain.

Below are the different high level languages developers can use to write smart contracts for Ethereum.

Solidity

Solidity is a language similar to JavaScript which allows you to develop contracts and compile to EVM bytecode. It is currently the flagship language of Ethereum and the most popular.

Serpent

Serpent is a language similar to Python which can be used to develop contracts and compile to EVM bytecode. It is intended to be maximally clean and simple, combining many of the efficiency benefits of a low-level language with ease-of-use in programming style, and at the same time adding special domain-specific features for contract programming. Serpent is compiled using LLL.

LLL

Lisp Like Language (LLL) is a low level language similar to Assembly. It is meant to be very simple and minimalistic; essentially just a tiny wrapper over coding in EVM directly.

Mutan (deprecated)

Mutan is a statically typed, C-like language designed and developed by Jeffrey Wilcke. It is no longer maintained.

Writing a contract

No language would be complete without a Hello World program. Operating within the Ethereum environment, Solidity has no obvious way of "outputting" a string. The closest we can do is to use a log event to place a string into the blockchain:

contract HelloWorld {
        event Print(string out);
        function() { Print("Hello, World!"); }
}

This contract will create a log entry on the blockchain of type Print with a parameter "Hello, World!" each time it is executed.

参见

Solidity docs has more examples and guidelines to writing Solidity code.

Compiling a contract

Compilation of solidity contracts can be accomplished via a number of mechanisms.

注解

More information on solc and compiling Solidity contract code can be found here.

Setting up the solidity compiler in geth

If you start up your geth node, you can check which compilers are available.

> web3.eth.getCompilers();
["lll", "solidity", "serpent"]

This command returns an array of strings indicating which compilers are currently available.

注解

The solc compiler is installed with cpp-ethereum. Alternatively, you can build it yourself.

If your solc executable is in a non-standard location you can specify a custom path to the solc executable using th --solc flag.

$ geth --solc /usr/local/bin/solc

Alternatively, you can set this option at runtime via the console:

> admin.setSolc("/usr/local/bin/solc")
solc, the solidity compiler commandline interface
Version: 0.2.2-02bb315d/.-Darwin/appleclang/JIT linked to libethereum-1.2.0-8007cef0/.-Darwin/appleclang/JIT
path: /usr/local/bin/solc
Compiling a simple contract

Let's compile a simple contract source:

> source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"

This contract offers a single method multiply which is called with a positive integer a and returns a * 7.

You are ready to compile solidity code in the geth JS console using eth.compile.solidity():

> contract = eth.compile.solidity(source).test
{
  code: '605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056',
  info: {
    language: 'Solidity',
    languageVersion: '0',
    compilerVersion: '0.9.13',
    abiDefinition: [{
      constant: false,
      inputs: [{
        name: 'a',
        type: 'uint256'
      } ],
      name: 'multiply',
      outputs: [{
        name: 'd',
        type: 'uint256'
      } ],
      type: 'function'
    } ],
    userDoc: {
      methods: {
      }
    },
    developerDoc: {
      methods: {
      }
    },
    source: 'contract test { function multiply(uint a) returns(uint d) { return a * 7; } }'
  }
}

注解

The compiler is also available via RPC and therefore via web3.js to any in-browser Ðapp connecting to geth via RPC/IPC.

The following example shows how you interface geth via JSON-RPC to use the compiler.

$ geth --datadir ~/eth/ --loglevel 6 --logtostderr=true --rpc --rpcport 8100 --rpccorsdomain '*' --mine console  2>> ~/eth/eth.log
$ curl -X POST --data '{"jsonrpc":"2.0","method":"eth_compileSolidity","params":["contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"],"id":1}' http://127.0.0.1:8100

The compiler output for one source will give you contract objects each representing a single contract. The actual return value of eth.compile.solidity is a map of contract name to contract object pairs. Since our contract's name is test, eth.compile.solidity(source).test will give you the contract object for the test contract containing the following fields:

code
The compiled EVM bytecode
info
Additional metadata output from the compiler
source
The source code
language
The contract language (Solidity, Serpent, LLL)
languageVersion
The contract language version
compilerVersion
The solidity compiler version that was used to compile this contract.
abiDefinition
The Application Binary Interface Definition
userDoc
The NatSpec Doc for users.
developerDoc
The NatSpec Doc for developers.

The immediate structuring of the compiler output (into code and info) reflects the two very different paths of deployment. The compiled EVM code is sent off to the blockchain with a contract creation transaction while the rest (info) will ideally live on the decentralised cloud as publicly verifiable metadata complementing the code on the blockchain.

If your source contains multiple contracts, the output will contain an entry for each contract, the corresponding contract info object can be retrieved with the name of the contract as attribute name. You can try this by inspecting the most current GlobalRegistrar code:

contracts = eth.compile.solidity(globalRegistrarSrc)

Create and deploy a contract

Before you begin this section, make sure you have both an unlocked account as well as some funds.

You will now create a contract on the blockchain by sending a transaction to the empty address with the EVM code from the previous section as data.

注解

This can be accomplished much easier using the online Solidity realtime compiler or the Mix IDE program.

var primaryAddress = eth.accounts[0]
var abi = [{ constant: false, inputs: { name: 'a', type: 'uint256' } }]
var MyContract = eth.contract(abi)
var contract = MyContract.new(arg1, arg2, ..., {from: primaryAddress, data: evmByteCodeFromPreviousSection})

All binary data is serialised in hexadecimal form. Hex strings always have a hex prefix 0x.

注解

Note that arg1, arg2, ... are the arguments for the contract constructor, in case it accepts any. If the contract does not require any constructor arguments then these arguments can be omitted.

It is worth pointing out that this step requires you to pay for execution. Your balance on the account (that you put as sender in the from field) will be reduced according to the gas rules of the EVM once your transaction makes it into a block. After some time, your transaction should appear included in a block confirming that the state it brought about is a consensus. Your contract now lives on the blockchain.

The asynchronous way of doing the same looks like this:

MyContract.new([arg1, arg2, ...,]{from: primaryAccount, data: evmCode}, function(err, contract) {
  if (!err && contract.address)
    console.log(contract.address);
});

Interacting with a contract

Interaction with a contract is typically done using an abstraction layer such as the eth.contract() function which returns a javascript object with all of the contract functions available as callable functions in javascript.

The standard way to describe the available functions of a contract is the ABI definition. This object is an array which describles the call signature and return values for each available contract function.

var Multiply7 = eth.contract(contract.info.abiDefinition);
var myMultiply7 = Multiply7.at(address);

Now all the function calls specified in the ABI are made available on the contract instance. You can just call those methods on the contract instance in one of two ways.

> myMultiply7.multiply.sendTransaction(3, {from: address})
"0x12345"
> myMultiply7.multiply.call(3)
21

When called using sendTransaction the function call is executed via sending a transaction. This will cost ether to send and the call will be recorded forever on the blockchain. The return value of calls made in this manner is the hash of the transaction.

When called using call the function is executed locally in the EVM and the return value of the function is returned with the function. Calls made in this manner are not recorded on the blockchain and thus, cannot modify the internal state of the contract. This manner of call is referred to as a constant function call. Calls made in this manner do not cost any ether.

You should use call if you are interested only in the return value and use sendTransaction if you only care about side effects on the state of the contract.

In the example above, there are no side effects, therefore sendTransaction only burns gas and increases the entropy of the universe.

Contract metadata

In the previous sections we explained how you create a contract on the blockchain. Now we will deal with the rest of the compiler output, the contract metadata or contract info.

When interacting with a contract you did not create you might want documentation or to look at the source code. Contract authors are encouraged to make such information available by registering it on the blockchain or through a third party service, such as EtherChain. The admin API provides convenience methods to fetch this bundle for any contract that chose to register.

// get the contract info for contract address to do manual verification
var info = admin.getContractInfo(address) // lookup, fetch, decode
var source = info.source;
var abiDef = info.abiDefinition

The underlying mechanism that makes this work is is that:

  • contract info is uploaded somewhere identifiable by a URI which is publicly accessible
  • anyone can find out what the URI is only knowing the contracts address

These requirements are achieved using a 2 step blockchain registry. The first step registers the contract code (hash) with a content hash in a contract called HashReg. The second step registers a url with the content hash in the UrlHint contract. These registry contracts were part of the Frontier release and have carried on into Homestead.

By using this scheme, it is sufficient to know a contract's address to look up the url and fetch the actual contract metadata info bundle.

So if you are a conscientious contract creator, the steps are the following:

  1. Deploy the contract itself to the blockchain
  2. Get the contract info json file.
  3. Deploy contract info json file to any url of your choice
  4. Register codehash ->content hash -> url

The JS API makes this process very easy by providing helpers. Call admin.register to extract info from the contract, write out its json serialisation in the given file, calculates the content hash of the file and finally registers this content hash to the contract's code hash. Once you deployed that file to any url, you can use admin.registerUrl to register the url with your content hash on the blockchain as well. (Note that in case a fixed content addressed model is used as document store, the url-hint is no longer necessary.)

source = "contract test { function multiply(uint a) returns(uint d) { return a * 7; } }"
// compile with solc
contract = eth.compile.solidity(source).test
// create contract object
var MyContract = eth.contract(contract.info.abiDefinition)
// extracts info from contract, save the json serialisation in the given file,
contenthash = admin.saveInfo(contract.info, "~/dapps/shared/contracts/test/info.json")
// send off the contract to the blockchain
MyContract.new({from: primaryAccount, data: contract.code}, function(error, contract){
  if(!error && contract.address) {
    // calculates the content hash and registers it with the code hash in `HashReg`
    // it uses address to send the transaction.
    // returns the content hash that we use to register a url
    admin.register(primaryAccount, contract.address, contenthash)
    // here you deploy ~/dapps/shared/contracts/test/info.json to a url
    admin.registerUrl(primaryAccount, hash, url)
  }
});

Testing contracts and transactions

Often you need to resort to a low level strategy of testing and debugging contracts and transactions. This section introduces some debug tools and practices you can use. In order to test contracts and transactions without real-word consequences, you best test it on a private blockchain. This can be achieved with configuring an alternative network id (select a unique integer) and/or disable peers. It is recommended practice that for testing you use an alternative data directory and ports so that you never even accidentally clash with your live running node (assuming that runs using the defaults. Starting your geth with in VM debug mode with profiling and highest logging verbosity level is recommended:

geth --datadir ~/dapps/testing/00/ --port 30310 --rpcport 8110 --networkid 4567890 --nodiscover --maxpeers 0 --vmdebug --verbosity 6 --pprof --pprofport 6110 console 2>> ~/dapp/testint/00/00.log

Before you can submit any transactions, you need set up your private test chain. See Test Networks.

// create account. will prompt for password
personal.newAccount();
// name your primary account, will often use it
primary = eth.accounts[0];
// check your balance (denominated in ether)
balance = web3.fromWei(eth.getBalance(primary), "ether");

// assume an existing unlocked primary account
primary = eth.accounts[0];

// mine 10 blocks to generate ether

// starting miner
miner.start(4);
// sleep for 10 blocks (this can take quite some time).
admin.sleepBlocks(10);
// then stop mining (just not to burn heat in vain)
miner.stop();
balance = web3.fromWei(eth.getBalance(primary), "ether");

After you create transactions, you can force process them with the following lines:

miner.start(1);
admin.sleepBlocks(1);
miner.stop();

You can check your pending transactions with:

// shows transaction pool
txpool.status
// number of pending txs
eth.getBlockTransactionCount("pending");
// print all pending txs
eth.getBlock("pending", true).transactions

If you submitted contract creation transaction, you can check if the desired code actually got inserted in the current blockchain:

txhash = eth.sendTansaction({from:primary, data: code})
//... mining
contractaddress = eth.getTransactionReceipt(txhash);
eth.getCode(contractaddress)

Accessing Contracts and Transactions

RPC

In previous sections we have seen how contracts can be written, deployed and interacted with. Now it's time to dive in the details of communicating with the Ethereum network and smart contracts.

An Ethereum node offers a RPC interface. This interface gives Ðapp's access to the Ethereum blockchain and functionality that the node provides, such as compiling smart contract code. It uses a subset of the JSON-RPC 2.0 specification (no support for notifications or named parameters) as serialisation protocol and is available over HTTP and IPC (unix domain sockets on linux/OSX and named pipe's on Windows).

If you are not interested in the details but are looking for an easy to use javascript library you can skip the following sections and continue with Using Web3.

Conventions

The RPC interface uses a couple of conventions that are not part of the JSON-RPC 2.0 specification:

  • Numbers are hex encoded. This decision was made because some languages have no or limited support for working with extremly large numbers. To prevent these type of errors numbers are hex encoded and it is up to the developer to parse these numbers and handle them appropriately. See the hex encoding section on the wiki for examples.
  • Default block number, several RPC methods accept a block number. In some cases it's not possible to give a block number or not very convenient. For these cases the default block number can be one of these strings ["earliest", "latest", "pending"]. See the wiki page for a list of RPC methods that use the default block parameters.

Deploy contract

We will go through the different steps to deploy the following contract using only the RPC interface.

contract Multiply7 {
   event Print(uint);
   function multiply(uint input) returns (uint) {
      Print(input * 7);
      return input * 7;
   }
}

The first thing to do is make sure the HTTP RPC interface is enabled. This means for geth we supply the --rpc flag on startup and for eth the -j flag. In this example we use the geth node on a private development chain. Using this approach we don't need ether on the real network.

> geth --rpc --dev --mine --minerthreads 1 --unlock 0 console 2>>geth.log

This will start the HTTP RPC interface on http://localhost:8545.

注解

geth supports CORS, see the --rpccorsdomain flag for more information.

We can verify that the interface is running by retrieving the coinbase address and balance using curl. Please note that data in these examples will differ on your local node. If you want to try these command replace the request params accordingly.

> curl --data '{"jsonrpc":"2.0","method":"eth_coinbase", "id":1}' -H "Content-Type: application/json" localhost:8545
{"id":1,"jsonrpc":"2.0","result":["0x9b1d35635cc34752ca54713bb99d38614f63c955"]}

> curl --data '{"jsonrpc":"2.0","method":"eth_getBalance", "params": ["0x9b1d35635cc34752ca54713bb99d38614f63c955", "latest"], "id":2}' -H "Content-Type: application/json" localhost:8545
{"id":2,"jsonrpc":"2.0","result":"0x1639e49bba16280000"}

Remember when we said that numbers are hex encoded? In this case the balance is returned in wei as a hex string. If we want to have the balance in ether as a number we can use web3 from the geth console.

> web3.fromWei("0x1639e49bba16280000", "ether")
"410"

Now that we have some ether on our private development chain we can deploy the contract. The first step is to compile the Multiply7 contract to byte code that can be sent to the EVM. Follow these these instructions to install solc, the solidity compiler.

The next step is to compile the Multiply7 contract to byte code that can be send to the EVM.

> echo 'pragma solidity ^0.4.16; contract Multiply7 { event Print(uint); function multiply(uint input) public returns (uint) { Print(input * 7); return input * 7; } }' | solc --bin
======= <stdin>:Multiply7 =======
Binary:
6060604052341561000f57600080fd5b60eb8061001d6000396000f300606060405260043610603f576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063c6888fa1146044575b600080fd5b3415604e57600080fd5b606260048080359060200190919050506078565b6040518082815260200191505060405180910390f35b60007f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da600783026040518082815260200191505060405180910390a16007820290509190505600a165627a7a7230582040383f19d9f65246752244189b02f56e8d0980ed44e7a56c0b200458caad20bb0029

Now that we have the compiled code we need to determine how much gas it costs to deploy it. The RPC interface has an eth_estimateGas method that will give us an estimate.

> curl --data '{"jsonrpc":"2.0","method": "eth_estimateGas", "params": [{"from": "0x9b1d35635cc34752ca54713bb99d38614f63c955", "data": "0x6060604052341561000f57600080fd5b60eb8061001d6000396000f300606060405260043610603f576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063c6888fa1146044575b600080fd5b3415604e57600080fd5b606260048080359060200190919050506078565b6040518082815260200191505060405180910390f35b60007f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da600783026040518082815260200191505060405180910390a16007820290509190505600a165627a7a7230582040383f19d9f65246752244189b02f56e8d0980ed44e7a56c0b200458caad20bb0029"}], "id": 5}' -H "Content-Type: application/json" localhost:8545
{"jsonrpc":"2.0","id":5,"result":"0x1c31e"}

And finally deploy the contract.

> curl --data '{"jsonrpc":"2.0","method": "eth_sendTransaction", "params": [{"from": "0x9b1d35635cc34752ca54713bb99d38614f63c955", "gas": "0x1c31e", "data": "0x6060604052341561000f57600080fd5b60eb8061001d6000396000f300606060405260043610603f576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063c6888fa1146044575b600080fd5b3415604e57600080fd5b606260048080359060200190919050506078565b6040518082815260200191505060405180910390f35b60007f24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da600783026040518082815260200191505060405180910390a16007820290509190505600a165627a7a7230582040383f19d9f65246752244189b02f56e8d0980ed44e7a56c0b200458caad20bb0029"}], "id": 6}' -H "Content-Type: application/json" localhost:8545
{"id":6,"jsonrpc":"2.0","result":"0xe1f3095770633ab2b18081658bad475439f6a08c902d0915903bafff06e6febf"}

The transaction is accepted by the node and a transaction hash is returned. We can use this hash to track the transaction.

The next step is to determine the address where our contract is deployed. Each executed transaction will create a receipt. This receipt contains various information about the transaction such as in which block the transaction was included and how much gas was used by the EVM. If a transaction creates a contract it will also contain the contract address. We can retrieve the receipt with the eth_getTransactionReceipt RPC method.

> curl --data '{"jsonrpc":"2.0","method": "eth_getTransactionReceipt", "params": ["0xe1f3095770633ab2b18081658bad475439f6a08c902d0915903bafff06e6febf"], "id": 7}' -H "Content-Type: application/json" localhost:8545
{"jsonrpc":"2.0","id":7,"result":{"blockHash":"0x77b1a4f6872b9066312de3744f60020cbd8102af68b1f6512a05b7619d527a4f","blockNumber":"0x1","contractAddress":"0x4d03d617d700cf81935d7f797f4e2ae719648262","cumulativeGasUsed":"0x1c31e","from":"0x9b1d35635cc34752ca54713bb99d38614f63c955","gasUsed":"0x1c31e","logs":[],"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","status":"0x1","to":null,"transactionHash":"0xe1f3095770633ab2b18081658bad475439f6a08c902d0915903bafff06e6febf","transactionIndex":"0x0"}}

We can see that our contract was created on 0x4d03d617d700cf81935d7f797f4e2ae719648262. If you got null instead of a receipt the transaction has not been included in a block yet. Wait for a moment and check if your miner is running and retry it.

Interacting with smart contracts

Now that our contract is deployed we can interact with it. There are 2 methods for this, sending a transaction or using call as previously explained. In this example we will be sending a transaction to the multiply method of the contract.

If we look at the documentation for the eth_sendTransaction we can see that we need to supply several arguments. In our case we need to specify the from, to and data arguments. From is the public address of our account and to the contract address. The data argument is a bit harder. It contains a payload that defines which method must be called and with which arguments. This is were the ABI comes into play. The ABI defines how to define and encode data for the EVM. You can read all the details about the ABI here.

The bytes of the payload is the function selector and defines which method is called. This is done by taking the first 4 bytes from the Keccak hash over the function name and its argument types and hex encode it. The multiply function accepts an uint which is an alias for uint256. This leaves us with:

> web3.sha3("multiply(uint256)").substring(0, 10)
"0xc6888fa1"

See for details this page.

The next step is to encode the arguments. We only have one uint256, lets assume we supply the value 6. The ABI has a section which specifies how to encode uint256 types.

int<M>: enc(X) is the big-endian two's complement encoding of X, padded on the higher-oder (left) side with 0xff for negative X and with zero bytes for positive X such that the length is a multiple of 32 bytes.

This encodes to 0000000000000000000000000000000000000000000000000000000000000006.

Combining the function selector and the encoded argument our data will be 0xc6888fa10000000000000000000000000000000000000000000000000000000000000006.

Lets try it:

> curl --data '{"jsonrpc":"2.0","method": "eth_sendTransaction", "params": [{"from": "0x9b1d35635cc34752ca54713bb99d38614f63c955", "to": "0x4d03d617d700cf81935d7f797f4e2ae719648262", "data": "0xc6888fa10000000000000000000000000000000000000000000000000000000000000006"}], "id": 8}' -H "Content-Type: application/json" localhost:8545
{"id":8,"jsonrpc":"2.0","result":"0x50905bea8043e1166703a2a72390f6e6eb4f23150c8e7d13094a6d82ce89a054"}

Since we sent a transaction we got the transaction hash returned. If we retrieve the receipt we can see something new:

{
  blockHash: "0x55262092dc46db5c7d3595decd4317780896c765c4db69cf2d5f650e46249b13",
  blockNumber: 6,
  contractAddress: null,
  cumulativeGasUsed: 22774,
  from: "0x9b1d35635cc34752ca54713bb99d38614f63c955",
  gasUsed: 22774,
  logs: [{
      address: "0x4d03d617d700cf81935d7f797f4e2ae719648262",
      blockHash: "0x55262092dc46db5c7d3595decd4317780896c765c4db69cf2d5f650e46249b13",
      blockNumber: 6,
      data: "0x000000000000000000000000000000000000000000000000000000000000002a",
      logIndex: 0,
      removed: false,
      topics: ["0x24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da"],
      transactionHash: "0x50905bea8043e1166703a2a72390f6e6eb4f23150c8e7d13094a6d82ce89a054",
      transactionIndex: 0
  }],
  logsBloom: "0x00000000000008000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000020800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  status: "0x1",
  to: "0x4d03d617d700cf81935d7f797f4e2ae719648262",
  transactionHash: "0x50905bea8043e1166703a2a72390f6e6eb4f23150c8e7d13094a6d82ce89a054",
  transactionIndex: 0
}

The receipt contains a log. This log was generated by the EVM on transaction execution and included in the receipt. If we look at the multipy function we can see that the Print event was raised with the input times 7. Since the argument for the Print event was a uint256 we can decode it according to the ABI rules which will leave us with the expected decimal 42.

> echo $((0x000000000000000000000000000000000000000000000000000000000000002a))
42

Apart from the data it is worth noting that topics can be used to determine which event created the log:

> web3.sha3("Print(uint256)")
"24abdb5865df5079dcc5ac590ff6f01d5c16edbc5fab4e195d9febd1114503da"

You can read more about events, topics and indexing in the Solidity tutorial.

This was just a brief introduction into some of the most common tasks. See for a full list of available RPC methods the RPC wiki page.

Web3.js

As we have seen in the previous example using the JSON-RPC interface can be quite tedious and error-prone, especially when we have to deal with the ABI. Web3.js is a javascript library that works on top of the Ethereum RPC interface. Its goal is to provide a more user friendly interface and reducing the chance for errors.

Deploying the Multiply7 contract using web3 would look like:

var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }';
var compiled = web3.eth.compile.solidity(source);
var code = compiled.Multiply7.code;
var abi = compiled.Multiply7.info.abiDefinition;

web3.eth.contract(abi).new({from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a", data: code}, function (err, contract) {
   if (!err && contract.address)
      console.log("deployed on:", contract.address);
   }
);

deployed on: 0x0ab60714033847ad7f0677cc7514db48313976e2

Load a deployed contract and send a transaction:

var source = 'contract Multiply7 { event Print(uint); function multiply(uint input) returns (uint) { Print(input * 7); return input * 7; } }';
var compiled = web3.eth.compile.solidity(source);
var Multiply7 = web3.eth.contract(compiled.Multiply7.info.abiDefinition);
var multi = Multiply7.at("0x0ab60714033847ad7f0677cc7514db48313976e2")
multi.multiply.sendTransaction(6, {from: "0xeb85a5557e5bdc18ee1934a89d8bb402398ee26a"})

Register a callback which is called when the Print event created a log.

multi.Print(function(err, data) { console.log(JSON.stringify(data)) })
{"address":"0x0ab60714033847ad7f0677cc7514db48313976e2","args": {"":"21"},"blockHash":"0x259c7dc07c99eed9dd884dcaf3e00a81b2a1c83df2d9855ce14c464b59f0c8b3","blockNumber":539,"event":"Print","logIndex":0, "transactionHash":"0x5c115aaa5418118457e96d3c44a3b66fe9f2bead630d79455d0ecd832dc88d48","transactionIndex":0}

See for more information the web3.js wiki page.

Console

The geth console offers a command line interface with a javascript runtime. It can connect to a local or remote geth or eth node. It will load the web3.js library that users can use. This allows users to deploy and interact with smart contract from the console using web3.js. In fact the examples in the Web3.js section can by copied into the console.

Viewing Contracts and Transactions

There are several online blockchain explorers available that will allow you to inspect the Ethereum blockchain. See for a list: Blockchain explorers.

Hosted blockchain explorers
Other Resources
  • EtherNodes - Geographic distribution of nodes and split by client
  • EtherListen - Realtime Ethereum transaction visualizer and audializer

Mix

The IDE Mix is intended to help you as a developer to create, debug and deploy contracts and dapps (both contracts backend and frontend).

WARNING - There are numerous reports of crash-at-boot issues for Mix on OS X. The issue is a Heisenbug which we have been chasing for a month or two. The best workaround we have for right now is to use the Debug configuration, like so:

cmake -DCMAKE_BUILD_TYPE=Debug ..

WARNING - A replacement for Mix called Remix is being worked on, so if you are experiencing issues with Mix, you might be better to look for alternatives until Remix is more mature.

Start by creating a new project that consists of

  • contracts
  • html files
  • JavaScript files
  • style files
  • image files

Project Editor

You can use projects to manage the creation and testing of a dapp. The project will contain data related to both backend and frontend as well as the data related to your scenarios (blockchain interaction) for debugging and testing. The related files will be created and saved automatically in the project directory.

Creating a new project

The development of a dapp start with the creation of a new project. Create a new project in the “edit” menu. Enter the project name, e.g. “Ratings” and select a path for the project file.

Editing backend contract file

By default, a new project contains a contract “Contract” for backend development on the blockchain using the Solidity language and the “index.html” for the frontend. Check the Solidity tutorial for references.

Edit the empty default contract “Contract”, e.g.

contract Rating {
        function setRating(bytes32 _key, uint256 _value) {
                ratings[_key] = _value;
        }
        mapping (bytes32 => uint256) public ratings;
}

Check the Solidity tutorial for help getting started with the solidity programming language.

Save changes

Editing frontend html files

Select default index.html file and enter the following code

 .... <script>

function getRating() {
  var param = document.getElementById(“query”).value;
  var res = contracts[“Rating”].contract.ratings(param);
  document.getElementById(“queryres”).innerText = res;
}

function setRating() {
        var key = document.getElementById("key").value;
        var value = parseInt(document.getElementById("value").value);
        var res = contracts["Rating"].contract.setRating(key, value);
}

</script>
    </head>
    <body bgcolor="#E6E6FA">
        <h1>Ratings</h1>
        <div>
            Store:
            <input type="string" id="key">
            <input type="number" id="value">
            <button onclick="setRating()">Save</button>
        </div>
        <div>
            Query:
            <input type="string" id="query" onkeyup='getRating()'>
            <div id="queryres"></div>
        </div>
    </body>
    </html>

Then it is possible to add many contract files as well as many HTML, JavaScript, css files

Scenarios Editor

Scenarios can be used to test and debug contracts.

A scenario is effectively a local blockchain where blocks can be mined without PoW – otherwise testing would be quite slow ;).

A scenario consists of a sequence of transactions. Usually, a scenario would start with the contract creation scenarios of the dapp. In addition, further transactions can be added to test and debug the dapp. Scenarios can be modified, i.e. transactions can be removed. Note that a scenario needs to be rebuilt for modifications to become effective. Further testing can be done using local JS calls via the JS API.

In case it’s not open, access the scenario and debugger pane by pressing F7 or Windows > Show right or the debug button in the upper right corner of the main window.

Creating and setting up a new scenario

When you launch Mix for the first time, an empty scenario, i.e. not containing any transactions, will be created. Add an account named “MyAccount” and set it’s initial balance to 1 ether. Click OK. Rename the scenario to “Deploy”.

Modifying initial ether balance of an account

Actually, we want to do a lot of tests Edit the Genesis block parameters and set your initial account balance to 1000 ether. Rebuild the scenario for the change to become effective.

Rebuilding a scenario

Each time a transaction is modified or an account added, the scenario has to be rebuilt for modifications to become effective. Note that if a scenario is rebuilt the web frontend (local storage) may also need to be reset (this is not done automatically be Mix).

Creating a transaction

Let’s get some ether sent to Bob. Create another account named “Bob” with zero ether balance. Create a new transaction in the scenario pane. Click “Add Tx…” and send 300 ether to Bob. Add a block.

Altering and reusing scenarios

Create a new scenario or start from a scenario with several transactions that you duplicate first

Rename the scenario

Modify scenario by specifying transactions that shall be removed

Rebuild the scenario

Display calls

A contract call is a function invokation. This is not a transaction as a contract call cannot change the state. A contract call is not part of the blockchain but for practical and ux design reason, it is convenient to display calls at the same functional level as a transaction. The JS icon warn you that this is not a transaction but a call. To show/hide call, click on the menu Scenario -> Display calls.

State Viewer

This panel is located below the block chain panel, in the scenario view. Once the blockchain has been run, this panel shows the state of the blockchain.

By state we mean all accounts balance (including contract and normal account), and the storage (global variable of all deployed contract). The content of this panel is not static, it depends on the selected transaction on the blockchain panel. The state shown here is the state resulting of the execution of the selected transaction.

image0

In that case, 2 contracts are deployed, the selected transaction (deployment of testCtr) is the last one. so the state view shows the storage of both TestCtr and BasicContract.

Transaction Explorer

Using the transaction pane

The transaction pane enables you to explore transactions receipts, including

  • Input parameters
  • Return parameters
  • Event logs

To display the transaction explorer, click on the down triangle icon which is on the right of each transaction, this will expand transaction details:

image0

Then you can either copy the content of this transaction in the clipboard, Edit the current transaction (you will have to rerun the blockchain then), or debug the transaction.

JavaScript console

Mix exposes the following objects into the global window context

web3 - Ethereum JavaScript API

contracts: A collection of contract objects. keys represents contracts name. values are is an objects containing the following properties:

  • contract: contract object instance (created as in web3.eth.contract)
  • address: contract address from the last deployed state (see below)
  • interface: contract ABI

Check the JavaScript API Reference for further information.

Using the JS console to add transactions and local calls

In case the name of the contract is “Sample” with a function named “set”, it is possible to make a transaction to call “set” by writing:

contracts["Sample"].contract.set(14)

If a call can be made this will be done by writing:

contracts["Sample"].contract.get.call()
It is also possible to use all properties and functions of the web3 object:
https://github.com/ethereum/wiki/wiki/JavaScript-API

Transaction debugger

Mix supports both Solidity and assembly level contract code debugging. You can toggle between the two modes to retrieve the relevant information you need.

At any execution point the following information is available:

VM stack – See Yellow Paper for VM instruction description

Call stack – Grows when contract is calling into another contract. Double click a stack frame to view the machine state in that frame

Storage – Storage data associated with the contract

Memory – Machine memory allocated up to this execution point

Call data – Transaction or call parameters

Accessing the debug mode

When transaction details are expanded, you can switch to the debugger view by clicking on the “Debug Transaction” button

Toggling between debug modes and stepping through transactions

This opens the Solidity debugging mode. Switch between Solidity and EVM debugging mode using the Menu button (Debug -> Show VM code)

  • Step through a transaction in solidity debugging mode
  • Step through a transaction in EVM debugging mode

Dapps deployment

This feature allows users to deploy the current project as a Dapp in the main blockchain.
This will deploy contracts and register frontend resources.

The deployment process includes three steps:

  • Deploy contract:
    This step will deploy contracts in the main blockchain.
  • Package dapp:
    This step is used to package and upload frontend resources.
  • Register:
    To render the Dapp, the Ethereum browser (Mist or AlethZero) needs to access this package. This step will register the URL where the resources are stored.

To Deploy your Dapp, Please follow these instructions:

Click on Deploy, Deploy to Network.
This modal dialog displays three parts (see above):
  • Deploy contract
  • Select Scenario

“Ethereum node URL” is the location where a node is running, there must be a node running in order to initiate deployment.

“Pick Scenario to deploy” is a mandatory step. Mix will execute transactions that are in the selected scenario (all transactions except transactions that are not related to contract creation or contract call). Mix will display all the transactions in the panel below with all associated input parameters.

“Gas Used”: depending on the selected scenario, Mix will display the total gas used.

  • Deploy Scenario

“Deployment account” allow selecting the account that Mix will use to execute transactions.

“Gas Price” shows the default gas price of the network. You can also specify a different value.

“Deployment cost”: depending on the value of the gas price that you want to use and the selected scenario. this will display the amount ether that the deployment need.

“Deployed Contract”: before any deployment this part is empty. This will be filled once the deployment is finished by all contract addresses that have been created.

“Verifications”. This will shows the number of verifications (number of blocks generated on top of the last block which contains the last deployed transactions). Mix keep track of all the transactions. If one is missing (unvalidated) it will be displayed in this panel.

  • Package dapp

The action “Generate Package” will create a new folder named 'www', this folder will contain all the resources and scripts will be mapped to the current deployed contract. In order to publish your dapp, you need to host the www folder in a webserver (to be replace soon by IPFS and SWARM). by default the library web3.js is not included. If you want to be able to use the dapp in a standard web browser, you wiil need to include this library.

Code Editor

This editor provides basic functionalities of a code editor.

  • In Solidity or JavaScript mode, an autocompletion plugin is available (Ctrl + Space).
  • Increasing/decreasing the font size (Ctrl +, Ctrl -)
  • In Solidity mode, you can display the gas estimation (Tools -> Display Gas Estimation). This will highlight all statements which requires a minimum amount of gas. Color turns to red if the gas required becomes important. It will also display the max execution cost of a transaction (for each function).

Dapps

A dapp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and storers in file storage). Ethereum dapps typically interface users via an HTML/Javascript web application using a Javascript API to communicate with the blockchain. Dapps would typically have their own suite of associated contracts on the blockchain which they use to encode business logic and allow persistent storage of their consensus-critical state. Remember that because of the redundant nature of computation on the Ethereum network, the gas costs of execution will always be higher than private execution offchain. This incentivizes dapp developers to restrict the amount of code they execute and amount of data they store on the blockchain.

Dapp directories

Dapps that use Ethereum are compiled to the following lists. They are listed in various stages of development (concept, working prototype, live/deployed). If you are developing a dapp, consider adding an entry to these listings:

The offered decentralised services listed cover a wide range of areas including finance, insurance, prediction markets, social networks, distributed computation and storage, gambling, marketplace, internet of things, governance, collaboration, development and games.

In the future, dapps are likely to be listed and distributed in dappstores integrated in dapp browsers.

Dapp browsers

Developer Tools

Dapp development requires an understanding of the Web3 Javascript API, the JSON RPC API, and the Solidity programming language.

注解

There are developer tools that help you develop, test, and deploy dapps in a way that automatically utilizes the resources listed below.

  • Web3 JavaScript API - This is the main JavaScript SDK to use when you want to interact with an Ethereum node.
  • JSON RPC API - This is the low level JSON RPC 2.0 interface to interface with a node. This API is used by the Web3 JavaScript API.
  • Solidity Docs - Solidity is the Ethereum developed Smart Contract language, which compiles to EVM (Ethereum Virtual Machine) opcodes.
  • Solium - Linter to identify and fix style and security issues in Solidity.
  • Solhint - Solidity linter that provides security, style guide and best practice rules for smart contract validation.
  • Test Networks - Test networks help developers develop and test Ethereum code and network interactions without spending their own ether on the main network. Test network options are listed below.
  • Dapp development resources. This assists you in developing, debugging, and deploying Ethereum applications.

Mix-IDE

Mix is the official Ethereum IDE that allows developers to build and deploy contracts and decentralized applications on top of the Ethereum blockchain. It includes a Solidity source code debugger. Mix (discontinued)

IDEs/Frameworks

Below are developer frameworks and IDEs used for writing Ethereum dapps.

  • Truffle - Truffle is a development environment, testing framework and asset pipeline for Ethereum.
  • Dapple - Dapple is a tool for Solidity developers to help build and manage complex contract systems on Ethereum-like blockchains.
  • Populus - Populus is a Smart Contract development framework written in python.
  • Eris-PM - The Eris Package Manager deploys and tests smart contract systems on private and public chains.
  • Embark - Embark is a Ðapp development framework written in JavaScript.
  • EtherScripter (obsolete, discontinued)
  • Resilience Raw Transaction Broadcaster

Ethereum-console

Command-line console for Ethereum nodes.

Ethconsole connects to an Ethereum node running in the background (tested with eth and geth) via IPC and provides an interactive javascript console containing the web3 object with admin additions.

Here you could find a list of available commands ethereum node control commands

To use this console you would need to start a local ethereum node with ipc communication socket enabled (file geth.ipc in data directory). By default ipc socket should be located at you local home directory in .ethereum after you started a node. You could also set --test option to use specific node test commands.

> eth --test
> ethconsole ipc://path/to/geth.ipc

In the console you could then type

> web3.eth.<command name> (arguments, function(){})

Here the defenition of --test mode node commands:

> web3.test.addBlock("[RLP]", function(){}) - Add a block from a string containing its hex RLP
> web3.test.rewindToBlock:("[int]", function(){}) - Reset the blockchain to specified block number
> web3.test.mineBlocks:("[int]", function(){}) - Mine a certain amount of NoProof blocks into chain
> web3.test.modifyTimestamp:("[int]", function(){}) - Set current block timestamp
> web3.test.setChainParams:("[json]", function(){}) - Reset the blockchain with given node configuration file

More information about node configuration file.

Base layer services

Swarm

Swarm is a distributed storage platform and content distribution service, a native base layer service of the Ethereum web 3 stack. The primary objective of Swarm is to provide a sufficiently decentralized and redundant store of Ethereum's public record, in particular to store and distribute dapp code and data as well as block chain data. From an economic point of view, it allows participants to efficiently pool their storage and bandwidth resources in order to provide the aforementioned services to all participants.

From the end user's perspective, Swarm is not that different from WWW, except that uploads are not to a specific server. The objective is to peer-to-peer storage and serving solution that is DDOS-resistant, zero-downtime, fault-tolerant and censorship-resistant as well as self-sustaining due to a built-in incentive system which uses peer to peer accounting and allows trading resources for payment. Swarm is designed to deeply integrate with the devp2p multiprotocol network layer of Ethereum as well as with the Ethereum blockchain for domain name resolution, service payments and content availability insurance.

ÐΞVcon talks on swarm
Ethereum Alarm Clock

A marketplace that facilitates scheduling transactions to occur at a later time. Serves a similar role to things like crontab in unix, or setTimeout in javascript.

Ethereum Computation Market

A marketplace that facilitates verifiable execution of computations off-chain. Allows for very expernsive computations to be used within the EVM without having to actually pay the high gas costs of executing them on-chain.

BTCRelay
BTCrelay

The EVM

The Ethereum Virtual Machine (EVM) is the runtime environment for smart contracts in Ethereum. It is not only sandboxed, but actually completely isolated, which means that code running inside the EVM has no access to network, filesystem, or other processes. Smart contracts even have limited access to other smart contracts.

Contracts live on the blockchain in an Ethereum-specific binary format (EVM bytecode). However, contracts are typically written in an Ethereum high level language, compiled into byte code using an EVM compiler, and finally uploaded on the blockchain using an Ethereum client.

Ethereum Tests

Ethereum Testing Docs have been moved to http://ethereum-tests.readthedocs.io/.

Web3 Base Layer Services

In addition to the Ethereum blockchain, more components are being developed that decentralise other important aspects of web applications.

_images/ethereum-protocols.png

Swarm - Decentralised data storage and distribution

Swarm is a peer to peer data sharing network in which files are addressed by the hash of their content. Similar to Bittorrent, it is possible to fetch the data from many nodes at once and as long as a single node hosts a piece of data, it will remain accessible everywhere. This approach makes it possible to distribute data without having to host any kind of server - data accessibility is location independent.

Other nodes in the network can be incentivised to replicate and store the data themselves, obviating the need for hosting services when the original nodes are not connected to the network.

Whisper - Decentralised messaging

A protocol for private, secure communication directly between nodes.

Furthermore, standard contracts are being created to make the development and usage of distributed applications easier:

Name registry

Because dapps can be stored anywhere, including the Swarm network, the name registry maps names to their content or location. This is a decentralised alternative to the Domain Name System (DNS).

See https://github.com/ethereum/EIPs/issues/26

Contract registry

To publish the source code of a specific contract, its address has to be mapped to it. The contract registry stores this mapping. Users can then look up this mapping and verify the contract byte code.

See * global registrar code * namereg API

Frequently Asked Questions

Questions

What is Ethereum?

Ethereum is a decentralized smart contracts platform that is powered by a cryptocurrency called Ether. A good starting point to learn more about its workings would be the "以太坊是什么？" page.

I have heard of Ethereum, but what are Geth, Mist, Ethminer, Mix?

  • Geth: This is the Go implementation of an Ethereum node, and is the basis for any interactions with the Ethereum blockchain. Running this locally will allow you to easily interact with the Ethereum blockchain. Read the go-ethereum installation instructions.
  • Mist: This is the equivalent of a web browser, but for the Ethereum platform. It acts as a GUI to display the accounts and contracts that you interact with. It also allows you to create and interact with contracts in a graphical user interface without ever touching the command line. If you are not a developer and just want to store ether and interact with Ethereum contracts, then Mist is the program to use. Downloads can be found on the Mist releases page.
  • Ethminer: A standalone miner. This can be used to mine or benchmark a mining set-up. It is compatible with eth, geth, and pyethereum. Check out the 挖矿 page for more information.
  • Mix: The integrated development environment for DApp authoring. Quickly prototype and debug decentralised applications on the Ethereum platform. More information can be found at the Mix GitHub Page.

How can I store big files on the blockchain?

In general you do not want to store large files or pieces of data in the Ethereum blockchain because of the high cost of storage. You will need to use a third party storage solution, such as Swarm or IPFS. Swarm is an Ethereum-specific project for distributed file storage. IPFS is an non-Ethereum project which has close ties to Ethereum; it will be used independently and may be used as an added layer underlying Swarm in the future. See this Ethereum StackExchange post on the topic for more information.

Is Ethereum based on Bitcoin?

Only in the sense that it uses a blockchain, which Bitcoin pioneered. Ethereum has a separate blockchain that has several significant technical differences from Bitcoin's blockchain. See this Ethereum StackExchange answer for a detailed explanation.

What's the future of Ethereum?

Ethereum developers are planning a switch from a Proof-of-Work consensus model to a Proof-of-Stake consensus model in the future. They are also investigating scalability solutions and how to store secrets on the blockchain.

What's the difference between account and "wallet contract"?

An account is your public / private key pair file that serves as your identity on the blockchain. See "account" in the glossary. A "wallet contract" is an Ethereum contract that secures your ether and identity with features such as multisignature signing and programmed deposit/withdrawal limits. A wallet contract can be easily created in the Mist Ethereum Wallet GUI client.

Are keyfiles only accessible from the computer you downloaded the client on?

No, you are welcome to export or move the keyfile, but always remember to backup your keyfiles and be aware of which computers you store your keyfile on.

How long should it take to download the blockchain?

The Ethereum blockchain is constantly growing, and is nearing 10GB as of March 2016. The amount of time it will take to download depends on the amount of peers you are able to connect to, your internet connection speed, and other factors. See the Download the blockchain faster section for tips on syncing the blockchain more quickly.

How do I get a list of transactions into/out of an address?

You would have to pull the transactions manually out of the blockchain to achieve this. Alternatively, you can rely on third party explorers' API's like Etherchain. For contract execution transactions however, you can filter the contract logs to achieve this.

Can a contract pay for its execution?

No this is not possible. The gas for the execution must be provided by the address submitting the execution request.

Can a transaction be sent by a third party? i.e can transaction broadcasting be outsourced

Technically yes, but there is an important restriction as opposed to bitcoin signed transactions: in ethereum the transaction has a nonce (more precisely, each account increases a counter when sending a transaction based on how many transactions total have been sent. If 3 transactions have ever been sent from the account, the account nonce would be 3).

Can Ethereum contracts pull data using third-party APIs?

No, Ethereum contracts cannot pull data from external information sources in this way. It is however possible to push data from external sites (e.g. weather sites, stock prices) to Ethereum contracts through transactions. There are "oracle" services that are compatible with the Ethereum network that will pull/push data to the Ethereum network for a fee.

Is the content of the data and contracts sent over the Ethereum network encrypted?

Data and contracts on the Ethereum network are encoded, but not encrypted. Everyone can audit the behavior of the contracts and the data sent to them. However, you are always free to encrypt data locally before broadcasting it to the network.

Can I store secrets or passwords on the Ethereum network?

All data on Ethereum is public. It is not possible to store secrets or passwords in Ethereum contracts without it being seen by all. There is work being done to make this a possibility through code obfuscation and other techniques. A good read would be "Privacy on the Blockchain" by Vitalik Buterin.

How will Ethereum combat centralisation of mining pools?

There are two primary ways that the Ethereum PoW based consensus algorithm combats mining centralisation (Source).

  • The first is by reducing losses due to orphaned blocks, which independent miners are more likely to experience.
    • This portion of the Ethereum mining algorithm, a technique referred to as GHOST, includes the headers only of recently orphaned blocks in return for a reduced reward to both the block producer and the includer of the (otherwise orphaned) block. These included orphans from "grandparent" or earlier blocks are frequently referred to as "uncle" blocks because the gender neutral term "ommer" isn't widely known or understood.
  • The second way that the Ethereum PoW consensus algorithm combats mining centralisation is by its use of a Proof of Work function that is ASIC resistant.
    • By preventing mining from becoming dominated by specially designed and produced hardware, independent miners are kept competitive or even given an advantage in terms of their profits and/or levels of hardware investment, because they can make use of readily available commodity hardware (i.e. consumer graphics cards).

How will Ethereum deal with ever increasing blockchain size?

There are many discussions around blockchain scalability. This questioned has been partially answered on this Ethereum StackExchange post and this blog post from Vitalik Buterin.

How will Ethereum ensure the network is capable of making 10,000+ transactions-per-second?

Ethereum is planning on implementing a proof-of-stake consensus protocol change during the Serenity phase of their development roadmap. More information on the likely Ethereum PoS candidate and how it may increase transactions-per-second can be found here.

术语表

Đ
Đ, D with stroke, is used in Old English, Middle English, Icelandic, and Faroese to stand for an uppercase letter "Eth". It is used in words like ĐEV or Đapp (decentralized application), where the Đ is the Norse letter "eth". The uppercase eth (Ð) is also used to symbolize the cryptocurrency Dogecoin.
decentralized application (= dapp)
Service that operates without a central trusted party. An application that enables direct interaction/agreements/communication between end users and/or resources without a middleman. See Dapps.
DAO
decentralized autonomous organization DAO is type of contract on the blockchain (or a suite of contracts) that is supposed to codify, enforce or automate the workings of an organization including governance, fund-raising, operations, spending and expansion.
identity
A set of cryptographically verifiable interactions that have the property that they were all created by the same person.
digital identity
The set of cryptographically verifiable transactions signed by the same public key define the digital identity's behavior. In many real world scenarios (voting) it is desireable that digital identities coincide with real world identities. Ensuring this without violence is an unsolved problem.
unique identity
A set of cryptographically verifiable interactions that have the property that they were all created by the same person, with the added constraint that one person cannot have multiple unique identities.
reputation
The property of an identity that other entities believe that identity to be either (1) competent at some specific task, or (2) trustworthy in some context, i.e., not likely to betray others even if short-term profitable.
escrow
If two mutually-untrusting entities are engaged in commerce, they may wish to pass funds through a mutually trusted third party and instruct that party to send the funds to the payee only when evidence of product delivery has been shown. This reduces the risk of the payer or payee committing fraud. Both this construction and the third party is called escrow.
deposit
Digital property placed into a contract involving another party such that if certain conditions are not satisfied that property is automatically forfeited and either credited to a counterparty as insurance against the conditions, or destroyed (= burnt = equally distributed) or donated to some charitable funds.
web of trust
The idea that if A highly rates B, and B highly rates C, then A is likely to trust C. Complicated and powerful mechanisms for determining the reliability of specific individuals in specific concepts can theoretically be gathered from this principle.
incentive compatibility
A protocol is incentive-compatible if everyone is better off "following the rules" than attempting to cheat, at least unless a very large number of people agree to cheat together at the same time (collusion).
collusion
In an incentivized protocol scenario, when a number of participants play together (conspire) to game the rules to their own benefit.
token system
A fungible virtual good that can be traded. More formally, a token system is a database mapping addresses to numbers with the property that the primary allowed operation is a transfer of N tokens from A to B, with the conditions that N is non-negative, N is not greater than A's current balance, and a document authorizing the transfer is digitally signed by A. Secondary "issuance" and "consumption" operations may also exist, transaction fees may also be collected, and simultaneous multi-transfers with many parties may be possible. Typical use cases include currencies, cryptographic tokens inside of networks, company shares and digital gift cards.
block
A block is a package of data that contains zero or more transactions, the hash of the previous block ("parent"), and optionally other data. The total set of blocks, with every block except for the initial "genesis block" containing the hash of its parent, is called the blockchain and contains the entire transaction history of a network. Note that some blockchain-based cryptocurrencies use the word "ledger" instead of blockchain; the two are roughly equivalent, although in systems that use the term "ledger" each block generally contains a full copy of the current state (e.g. currency balances, partially fulfilled contracts, registrations) of every account allowing users to discard outdated historical data.
dapp
Đapp Stands for "decentralized application". Some say it is pronounced Ethapp due to the use of the uppercase eth letter Ð.
address
An Ethereum address represents an account. For EOA, the address is derived as the last 20 bytes of the public key controlling the account, e.g., cd2a3d9f938e13cd947ec05abc7fe734df8dd826. This is a hexadecimal format (base 16 notation), which is often indicated explicitly by appending 0x to the address. Web3.js and console functions accept addresses with or without this prefix but for transparency we encourage their use. Since each byte of the address is represented by 2 hex characters, a prefixed address is 42 characters long. Several apps and APIs are also meant to implement the new checksum-enabled address scheme introduced in the Mist Ethereum wallet as of version 0.5.0.
hexadecimal
Common representation format for byte sequencing. Its advantage is that values are represented in a compact format using two characters per byte (the characters [0-9][a-f]).
ether
Ether is the name of the currency used within Ethereum. It is used to pay for computations within the EVM. Ambiguously, ether is also the name of a unit in the system;
EOA
Externally Owned Account. An account controlled by a private key. If you own the private key associated with the EOA you have the ability to send ether and messages from it. Contract accounts also have an address, see 账户. EOAs and contract accounts may be combined into a single account type during Serenity.
gas
Name for the cryptofuel that is consumed when code is executed by the EVM. The gas is paid for execution fee for every operation made on an Ethereum blockchain.
gas limit
Gas limit can apply to both individual transactions, see transaction gas limit and to blocks, block-gas-limit. For individual transactions, the gas limit represents the maximum amount of gas you indicate you are willing to pay for a contract execution transaction. It is meant to protect users from getting their ether depleted when trying to execute buggy or malicious contracts. The block gas limit represents the maximum cumulative gas used for all the transactions in a block. With the launch of Homestead, the block gas limit floor will increase from 3,141,592 gas to 4,712,388 gas (~50% increase).
gas price
Price in ether of one unit of gas specified in a transaction. With the launch of Homestead, the default gas price reduces from 50 shannon to 20 shannon (~60% reduction).
transaction
The signed data package that stores a message to be sent from an externally owned account. Simply put, a transaction describes a transfer of information from an EOA to another EOA or a contract account.
message
A data transfer mechanism contracts use to communicate with other contracts. Messages can also be described as virtual objects that are never serialized and exist only in the Ethereum execution environment.
Web3
The exact definition of the Web3 paradigm is still taking form, but it generally refers to the phenomenon of increased connectedness between all kinds of devices, decentralization of services and applications, semantic storage of information online and application of artificial intelligence to the web.
DAO
See Decentralized Autonomous Organization.
epoch
Epoch is the interval between each regeneration of the DAG used as seed by the PoW algorithm Ethash. The epoch in specified as 30000 blocks.
elliptic curve (cryptography)
Refers to an approach to public-key cryptography based on the algebraic structure of elliptic curves over finite fields. See elliptic curve cryptography.
wallet
A wallet, in the most generic sense, refers to anything that can store ether or any other crypto token. In the crypto space in general, the term wallet is used to mean anything from a single private/public key pair (like a single paper wallet) all the way to applications that manage multiple key pairs, like the Mist Ethereum wallet.
contract
A persistent piece of code on the Ethereum blockchain that encompasses a set of data and executable functions. These functions execute when Ethereum transactions are made to them with certain input parameters. Based on the input parameters, the functions will execute and interact with data within and outside of the contract.
suicide
See self-destruct. selfdestruct acts as an alias to the deprecated suicide terminology in accordance with EIP 6 - Renaming SUICIDE OPCODE.
selfdestruct
A global variable in the Solidity language that allows you to "destroy the current contract, sending its funds to the given address". selfdestruct acts as an alias to the deprecated suicide terminology in accordance with EIP 6 - Renaming SUICIDE OPCODE. It frees up space on the blockchain and prevents future execution of the contract. The contract's address will still persist, but ether sent to it will be lost forever. The possibility to kill a contract has to be implemented by the contract creator him/herself using the Solidity selfdestruct function.
transaction fee
Also known as gas cost, it is the amount of ether that the miners will charge for the execution of your transaction.
mining
The process of verifying transactions and contract execution on the Ethereum blockchain in exchange for a reward in ether with the mining of every block.
mining pool
The pooling of resources by miners, who share their processing power over a network, to split the reward equally, according to the amount of work they contributed to solving a block.
mining reward
The amount of cryptographic tokens (in this case ether) that is given to the miner who mined a new block.
state
Refers to a snapshot of all balances and data at a particular point in time on the blockchain, normally referring to the condition at a particular block.
blockchain
An ever-extending series of data blocks that grows as new transactions are confirmed as part of a new block. Each new block is chained to the existing blockchain by a cryptographic proof-of-work.
peer
Other computers on the network also running an Ethereum node (Geth) with an exact copy of the blockchain that you have.
signing
Producing a piece of data from the data to be signed using your private key, to prove that the data originates from you.
discovery (peer)
The process of 'gossiping' with other nodes in the network to find out the state of other nodes on the network.
gas price oracle
A helper function of the Geth client that tries to find an appropriate default gas price when sending transactions.
light client
A client program that allows users in low-capacity environments to still be able to execute and check the execution of transactions without needing to run a full Ethereum node (Geth).
etherbase
It is the default name of the account on your node that acts as your primary account. If you do mining, mining rewards will be credited to this account.
coinbase
Coinbase is analogous to etherbase, but is a more generic term for all cryptocurrency platforms.
balance
The amount of cryptocurrency (in this case) belonging to an account.
solidity
Solidity is a high-level language whose syntax is similar to that of JavaScript and it is designed to compile to code for the Ethereum Virtual Machine.
serpent
Serpent is a high-level language whose syntax is similar to that of Python and it is designed to compile to code for the Ethereum Virtual Machine.
EVM
Ethereum Virtual Machine, the decentralized computing platform which forms the core of the Ethereum platform.
virtual machine
In computing, it refers to an emulation of a particular computer system.
peer to peer network
A network of computers that are collectively able to perform functionalities normally only possible with centralized, server-based services.
decentralization
The concept of moving the control and execution of computational processes away from a central entity.
distributed hash table
A distributed hash table (DHT) is a class of a decentralized distributed system that provides a lookup service similar to a hash table: (key, value) pairs are stored in a DHT, and any participating node can efficiently retrieve the value associated with a given key.
NAT
Network address translation (NAT) is a methodology of remapping one IP address space into another by modifying network address information in Internet Protocol (IP) datagram packet headers while they are in transit across a traffic routing device.
nonce
Number Used Once or Number Once. A nonce, in information technology, is a number generated for a specific use, such as session authentication. Typically, a nonce is some value that varies with time, although a very large random number is sometimes used. In general usage, nonce means “for the immediate occasion” or “for now.” In the case of Blockchain Proof of Work scenarios, the hash value, found by a Miner, matching the network's Difficulty thus proving the Block Validity is called Nonce as well.
proof-of-work
Often seen in its abbreviated form "PoW", it refers to a mathematical value that can act as the proof of having solved a resource and time consuming computational problem.
proof-of-stake
An alternative method of mining blocks that require miners to demonstrate their possession of a certain amount of the currency of the network in question. This works on the principle that miners will be disincentivized to try to undermine a network in which they have a stake. PoS is less wasteful than PoW, but is still often used together with it to provide added security to the network.
CASPER
Casper is a security-deposit based economic consensus protocol. This means that nodes, so called “bonded validators”, have to place a security deposit (an action we call “bonding”) in order to serve the consensus by producing blocks. If a validator produces anything that Casper considers “invalid”, the deposit is forfeited along with the privilege of participating in the consensus process.
consensus
The agreement among all nodes in the network about the state of the Ethereum network.
homestead
Homestead is the second major version release of the Ethereum platform. Homestead includes several protocol changes and a networking change that makes possible further network upgrades: EIP-2 Main homestead hardfork changes; EIP-7 Hardfork EVM update (DELEGATECALL); EIP-8 devp2p forward compatibility. Homestead will launch when block 1,150,000 is reached on the Mainnet. On the Testnet, Homestead will launch at block 494,000.
metropolis
The third stage of Ethereum's release. This is the stage when the user interfaces come out (e.g. Mist), including a dapp store, and non-technical users should feel comfortable joining at this point.
serenity
The fourth stage of Ethereum's release. This is when things are going to get fancy: the network is going to change its mining process from Proof-of-Work to Proof-of-Stake.
frontier
Ethereum was planned to be released in four major steps with Frontier being the name for the first phase. The Frontier release went live on July 30th, 2015. The command line Frontier phase was mainly meant to get mining operations going with the full reward of 5 ether per block and also to promote the emergence of ether exchanges. Frontier surpassed earlier modest expectations and has nurtured tremendous growth of the ecosystem.
olympic
The Frontier pre-release, which launched on May 9th 2015. It was meant for developers to help test the limits of the Ethereum blockchain.
morden
Morden is the first Ethereum alternative testnet. It is expected to continue throughout the Frontier and Homestead era.
testnet
A mirror network of the production Ethereum network that is meant for testing. See Morden.
private chain
A fully private blockchain is a blockchain where write permissions are kept centralized to one organization.
consortium chain
A blockchain where the consensus process is controlled by a pre-selected set of nodes.
micropayment
A micropayment is a financial transaction involving a very small sum of money (<1 USD) and usually one that occurs online.
sharding
The splitting of the space of possible accounts (contracts are accounts too) into subspaces, for example, based on first digits of their numerical addresses. This allows for contract executions to be executed within 'shards' instead of network wide, allowing for faster transactions and greater scalability.
hash
A cryptographic function which takes an input (or 'message') and returns a fixed-size alphanumeric string, which is called the hash value (sometimes called a message digest, a digital fingerprint, a digest or a checksum). A hash function (or hash algorithm) is a process by which a document (i.e. a piece of data or file) is processed into a small piece of data (usually 32 bytes) which looks completely random, and from which no meaningful data can be recovered about the document, but which has the important property that the result of hashing one particular document is always the same. Additionally, it is crucially important that it is computationally infeasible to find two documents that have the same hash. Generally, changing even one letter in a document will completely randomize the hash; for example, the SHA3 hash of "Saturday" is c38bbc8e93c09f6ed3fe39b5135da91ad1a99d397ef16948606cdcbd14929f9d, whereas the SHA3 hash of "Caturday" is b4013c0eed56d5a0b448b02ec1d10dd18c1b3832068fbbdc65b98fa9b14b6dbf. Hashes are usually used as a way of creating a globally agreed-upon identifier for a particular document that cannot be forged.
crypto-fuel
Similar to 'gas', referring to the amount of cryptocurrency required to power a transaction.
cryptoeconomics
The economics of cryptocurrencies.
protocol
A standard used to define a method of exchanging data over a computer network.
block validation
The checking of the coherence of the cryptographic signature of the block with the history stored in the entire blockchain.
blocktime
The average time interval between the mining of two blocks.
network hashrate
The number of hash calculations the network can make per second collectively.
hashrate
The number of hash calculations made per second.
serialization
The process of converting a data structure into a sequence of bytes. Ethereum internally uses an encoding format called recursive-length prefix encoding (RLP), described in the RLP section of the wiki.
double spend
A deliberate blockchain fork, where a user with a large amount of mining power sends a transaction to purchase some produce, then after receiving the product creates another transaction sending the same coins to themselves. The attacker then creates a block, at the same level as the block containing the original transaction but containing the second transaction instead, and starts mining on the fork. If the attacker has more than 50% of all mining power, the double spend is guaranteed to succeed eventually at any block depth. Below 50%, there is some probability of success, but it is usually only substantial at a depth up to about 2-5; for this reason, most cryptocurrency exchanges, gambling sites and financial services wait until six blocks have been produced ("six confirmations") before accepting a payment.
SPV client
A client that downloads only a small part of the blockchain, allowing users of low-power or low-storage hardware like smartphones and laptops to maintain almost the same guarantee of security by sometimes selectively downloading small parts of the state without needing to spend megabytes of bandwidth and gigabytes of storage on full blockchain validation and maintenance. See light client.
uncle
Uncles are blockchain blocks found by a miner, when a different miner has already found another block for the corresponding place in the blockchain. They are called “stale blocks”. The parent of an Uncle is an ancestor of the inserting block, located at the tip of the blockchain. In contrast to the Bitcoin network, Ethereum rewards stale blocks as well in order to avoid to penalize miners with a bad connection to the network. This is less critical in the Bitcoin network, because the Block Time there is much higher (~10 minutes) than on the Ethereum network (aimed to ~15 seconds).
GHOST
Greedy Heaviest-Observed Sub-Tree is an alternative chain-selection method that is designed to incentivize stale blocks (uncles) as well, thus reducing the incentive for pool mining. In GHOST, even the confirmation given by stale blocks to previous blocks are considered valid, and the miners of the stale blocks are also rewarded with a mining reward.
merkle patricia tree
Merkle Patricia trees provide a cryptographically authenticated data structure that can be used to store all (key, value) bindings. They are fully deterministic, meaning that a Patricia tree with the same (key,value) bindings is guaranteed to be exactly the same down to the last byte and therefore have the same root hash, provide O(log(n)) efficiency for inserts, lookups and deletes, and are much easier to understand and code than more complex comparison-based alternatives like red-black trees.
DAG
DAG stands for Directed Acyclic Graph. It is a graph, a set of nodes and links between nodes, that has very special properties. Ethereum uses a DAG in Ethash, the Ethereum Proof of Work (POW) algorithm.The Ethash DAG takes a long time to be generated, which is done by a Miner node into a cache file for each Epoch. The file data is then used when a value from this graph is required by the algorithm.
uncle rate
The number of uncles produced per block.
issuance
The minting and granting of new cryptocurrency to a miner who has found a new block.
presale
Sale of cryptocurrency before the actual launch of the network.
static node
A feature supported by Geth, the Golang Ethereum client, which makes it possible to always connect to specific peers. Static nodes are re-connected on disconnects. For details, see the section on static nodes.
bootnode
The nodes which can be used to initiate the discovery process when running a node. The endpoints of these nodes are recorded in the Ethereum source code.
exchange
An online marketplace which facilitates the exchange of crypto or fiat currencies based on the market exchange rate.
compiler
A program that translates pieces of code written in high level languages into low level executable code.
genesis block
The first block in a blockchain.
network id
A number which identifies a particular version of the Ethereum network.
block header
The data in a block which is unique to its content and the circumstances in which it was created. It includes the hash of the previous block's header, the version of the software the block is mined with, the timestamp and the merkle root hash of the contents of the block.
pending transaction
A transaction that is not yet confirmed by the Ethereum network.
block propagation
The process of transmitting a confirmed block to all other nodes in the network.
sidechain
A blockchain that branches off a main blockchain and checks in periodically with the main blockchain. Besides that it runs independently from the main chain, and any security compromises in the sidechain will not affect the main chain.
pegging
Locking down the exchange rate of the coins/tokens in two chains (usually a main and a side chain) in a certain direction.
2-way pegging
Locking down the exchange rate of the coins/tokens in two chains (usually a main and a side chain) in both directions.
trustless
Refers to the ability of a network to trustworthily mediate transactions without any of the involved parties needing to trust anyone else.
faucet
A website that dispenses (normally testnet) cryptocurrencies for free.
checksum
A count of the number of bits in a transmission that is included with the unit so that the receiving end can verify that the entirety of the message has been transmitted.
ICAP
Interexchange Client Address Protocol, an IBAN-compatible system for referencing and transacting to client accounts aimed to streamline the process of transferring funds, worry-free between exchanges and, ultimately, making KYC and AML concerns a thing of the past.
private key
A private key is a string of characters known only to the owner, that is paired with a public key to set off algorithms for text encryption and decryption.
public key
A string of characters derived from a private key that can be made public. The public key can be used to verify the authenticity of any signature created using the private key.
encryption
Encryption is the conversion of electronic data into a form unreadable by anyone except the owner of the correct decryption key. It can further be described as a process by which a document (plaintext) is combined with a shorter string of data, called a key (e.g. c85ef7d79691fe79573b1a7064c19c1a9819ebdbd1faaab1a8ec92344438aaf4), to produce an output (ciphertext) which can be "decrypted" back into the original plaintext by someone else who has the key, but which is incomprehensible and computationally infeasible to decrypt for anyone who does not have the key.
digital signature
A mathematical scheme for demonstrating the authenticity of a digital message or documents.
port
A network port is a communication endpoint used by a one of the existing standards of establishing a network conversation (e.g. TCP, UDP).
RPC
Remote Procedure Call, a protocol that a program uses to request a service from a program located in another computer in a network without having to understand the network details.
IPC
Interprocess communication (IPC) is a set of programming interfaces that allow a programmer to coordinate activities among different program processes that can run concurrently in an operating system.
attach
The command used to initiate the Ethereum Javascript console.
daemon
A computer program that runs as a background process instead of in direct control by an interactive user.
system service
See base layer service
base layer service
Services such as SWARM and Whisper which are built into the Ethereum platform.
js
Javascript.
syncing
The process of downloading the entire blockchain.
fast sync
Instead of processing the entire block-chain one link at a time, and replay all transactions that ever happened in history, fast syncing downloads the transaction receipts along the blocks, and pulls an entire recent state database.
ASIC
Application-specific integrated circuit, in this case referring to an integrated circuit custom built for cryptocurrency mining.
memory-hard
Memory hard functions are processes that experience a drastic decrease in speed or feasibility when the amount of available memory even slightly decreases.
keyfile
Every account's private key/address pair exists as a single keyfile. These are JSON text files which contains the encrypted private key of the account, which can only be decrypted with the password entered during account creation.
ICAP format
The format of the IBANs defined using the Inter-exchange Client Address Protocol.
block(chain) explorer
A website that allows easy searching and extraction of data from the blockchain.
geth
Ethereum client implemented in the Golang programming language, based on the protocol as defined in the Ethereum Yellow Paper.
eth
Ethereum client implemented in the C++ programming language, based on the protocol as defined in the Ethereum Yellow Paper.
ethereumjs
Ethereum client implemented in the Javascript/Node programming language, based on the protocol as defined in the Ethereum Yellow Paper.
pyethereum
Ethereum client implemented in the Python programming language, based on the protocol as defined in the Ethereum Yellow Paper.
ethereumj
Ethereum client implemented in the Java programming language, based on the protocol as defined in the Ethereum Yellow Paper.
ethereumh
Ethereum client implemented in the Haskell programming language, based on the protocol as defined in the Ethereum Yellow Paper.
parity
Ethereum client implemented in the Rust programming language, based on the protocol as defined in the Ethereum Yellow Paper.
difficulty
In very general terms, the amount of effort required to mine a new block. With the launch of Homestead, the difficulty adjustment algorithm will change.
account
Accounts are a central part of the Ethereum network and are an essential part of any transaction or contract. In Ethereum, there are two types of accounts: Externally Owned accounts (EOA) and Contract accounts.
HLL (obsolete)
Acronym for Higher Level Language, which is what Serpent and Solidity are. HLL is what early Ðapp developers called Ethereum programming languages that did not touch the low level elements. This phrase has been phased out.
CLL (obsolete)
Acronym for C Like Language, which Mutan was. This acronym has been phased out.
ES1, ES2, and ES3 (obsolete)
"Ethereum Script" versions 1,2 and 3. There were early versions of what would become the Ethereum Virtual Machine (EVM).
log event
Contracts are triggered by transactions executed as part of the block verification. If conceived of as a function call, contract execution is asynchronous, and therefore they have no return value. Instead contracts communicate to the outside world with log events. The log events are part of the transaction receipt which is produced when the transaction is executed. The receipts are stored in the receipt trie, the integrity of which is guaranteed by the fact that the current root of the receipt trie is part of the block header alongside the roots of state and state-trie. In a broad sense from the external perspective receipts are part of the Ethereum system state except that they are not readable contracts internally.

The Homestead Documentation Initiative

Gitter

Purpose and Audience

This guide should serve to be an entry level for all Ethereum users and developers. The goal is to create documentation with information, short tutorials, and examples that will cover all of the basic and intermediate functionality of using Ethereum to interact with dapps or develop a dapp.

Any information that is overly specific, technical, or not necessary to accomplish the documentation's goal will remain on the Ethereum Github Wiki. It may be referenced in this guide if necessary.

Although much of the information will be similar between the Frontier Guide and the Homestead Guide, efforts need to be made to make sure the information ported over is still accurate. This document is client agnostic, and examples and tutorials may be based on any client that the author decides to write on, as long as a distinction is made as to what client is being used in the examples/tutorials.

Although overly specific and technical documentation will not be included in the first iterations of this guide, community use and popularity of this guide will dictate future decisions to move Github wiki documentation to this format.

Examples of overly specific and technical documentation include:

  • ETHash, CASPER, ABI, RLP, or other technical specs.
  • Full API specs for protocols. Caveat: If an example, information, or tutorial needs to reference API calls for a client or interface in order to fulfill its example it is acceptable to reference the specific call. Be sure to make a reference where the user can find remaining pieces of the specific documentation that may be on the GitHub Wiki.

Resources for Exemplary Documentation

Here are some examples of previous Ethereum documentation + good examples of documentation.

Restructured Text Markup, Sphinx

Compilation and Deployment

We use make with the autogenerated read-the-docs Makefile to build the doc.

git clone https://github.com/ethereum/homestead-guide
cd homestead-guide
make html

Processing Tips

Fix section delimiter lines (always use 80-long ones to have correct length, unless the title is greater than 80 chars in length)

for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\=+$/================================================================================/' > $f.o; mv $f.o $f; done; done
for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\*+$/********************************************************************************/' > $f.o; mv $f.o $f; done
for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\-+$/--------------------------------------------------------------------------------/' > $f.o; mv $f.o $f; done
for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\++$/++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++/' > $f.o; mv $f.o $f; done
for f in `ls source/*/*.rst`; do cat $f|perl -pe 's/\#+$/################################################################################/' > $f.o; mv $f.o $f; done

Referencing Old Documentation

old-docs-for-reference folder has all of the Frontier Gitbook and Ethereum Wiki doc. Feel free to copy/paste information from those documents that is still relevant.

Migrate and Convert Old Wiki Content Using Pandoc

If you still want to clone the absolute latest Ethereum Wiki and Frontier Guide docs:

git clone git@github.com:ethereum/go-ethereum.wiki.git
git clone git@github.com:ethereum/wiki.wiki.git

mkdir main-wiki.rst
mkdir go-ethereum-wiki.rst

for f in `ls wiki.wiki/*.md`; do pandoc $f -o main-wiki.rst/`basename $f .md`.rst; done
for f in `ls go-ethereum.wiki/*.md`; do pandoc $f -o go-ethereum-wiki.rst/`basename $f .md`.rst; done