Docs_(API).md
1 \--- weight: 10 title: API Introduction --- 2 3 1. Introduction 4 5 DOCUMENTATION STILL WORK IN PROGRESS 6 7 Welcome to the Status API\! Tread carefully, for you tread on the dreams 8 of a better web. 9 10 Status allows users to interact with a wide array of Decentralized 11 Applications (DApps) using the same intuitive chat interface (it also 12 does a bunch of other things, but we'll focus on this aspect for now). 13 In the near future, Status users will be able to have group chats where 14 most of the participants are DApp chatbots. All DApp developers will 15 benefit from this synergy, because a common chat interface for multiple 16 DApps makes using your specific DApp more convenient, and effectively 17 makes your DApp more powerful by giving it access to potentially far 18 wider and more powerful network effects. 19 20 In this guide, we’ll explore how you can use the Status API to develop 21 your DApp and create custom commands for your users that will work in a 22 beautifully-intuitive, mobile context. As a result of developing on 23 Status, you’ll have a DApp that your users can access on MetaMask, Mist, 24 and Status. It's really worth emphasising that using Status brings with 25 it access to mobile users with native mobile commands. With little extra 26 developer time invested, you’ll gain a mobile DApp. 27 28 1. Quickstart 29 30 If you already have a DApp with a web interface, then this will be the 31 quickest Quickstart ever (trademark pending). Simply open Status, 32 navigate to Console, hit the \`@browse\` command and type in the url 33 where your DApp is running. 34 35 Voila\! Users in Status can already see your DApp and interact with it 36 (on the Ropsten Test Network). Make some mobile optimizations of your 37 own and you're away. That is the power of decentralized, web3 38 technologies. Awesome, right? 39 40 OK, but what if \`(a)\` I don't have a DApp but want to learn how to 41 build one on Status, or \`(b)\` I want to use this awesome API to make 42 the most of an awesome, native mobile UX, or \`(c)\` I know what I'm 43 doing and want to create fully decentralized, chatbot functionality for 44 my DApp? 45 46 1. Examples 47 48 At Status, we eat our own dogfood\! All commands within Status are 49 written with our API, take a look at the 50 \[status-react/bots\](https://github.com/status-im/status-react/tree/develop/bots) 51 directory for examples. 52 53 \--- weight: 30 title: Status API Reference --- 54 55 1. status 56 (API) 57 58 <https://github.com/status-im/status-react/blob/develop/resources/status.js#L160> 59 60 1. 1. status 61 62 Remember, this is all about Ethereum. Anywhere. 63 64 Below you will find the formal API specification from which you can 65 glean all the information you need to make your DApp truly mobile, with 66 native mobile commands and an intuitive chat interface through which 67 users can actually see, interact with, and pay for the services you 68 offer. 69 70 1. 1. status.command 71 72 \> A really simple template: 73 74 \`\`\`js status.command({ 75 76 `name: "hello",` 77 `title: "HelloBot",` 78 `description: "Helps you say hello",` 79 `color: "#7099e6",` 80 `preview: function () {` 81 `return status.components.text({}, "you’re saying hello");` 82 `}` 83 84 }); \`\`\` 85 86 \> It is important to note that params are available for any 87 status.command(), including in params itself. For instance, if your user 88 sends /hello whatsup, the input "whatsup" will be available in your 89 command under params.hello. You can add additional params to - for 90 instance - preview like so: 91 92 \`\`\`js params: \[{ 93 94 `name: "hello",` 95 `type: status.types.TEXT` 96 `placeholder: "Why not say hello"` 97 98 }\], \`\`\` 99 100 \> The placeholder parameter above only applies if your users haven’t 101 input anything into the command, not even the name. You can use it to 102 include helpful guidance where necessary, i.e. "Type your password". 103 Alternatively, you can also include suggestions for your users’ input. 104 This should return a component to be rendered. For instance, if you are 105 using the Console DApp and you select the /faucet command, you’ll see 106 two suggestions to choose from. 107 108 \> Example validator function (this specific example will raise an error 109 if your user doesn’t input a string. Notice that you should return your 110 message inside one of the status.components): 111 112 \`\`\`js validator: function(params) { 113 114 `if (!params.hello) {` 115 ` return status.components.text({}, "Say hello");` 116 ` }` 117 `}` 118 ` ``` ` 119 120 \> Example of the request command to get a user send some amount of 121 Ether somewhere: 122 123 \`\`\`js handler: function (params) { 124 125 ` return {` 126 ` event: "request",` 127 ` params: [params.amount],` 128 ` request: {` 129 ` command: "send",` 130 ` params: {` 131 ` amount: params.amount` 132 ` }` 133 ` }` 134 ` };` 135 ` },` 136 137 \`\`\` 138 139 \> Full example of pretty much all the status.command stuff in action: 140 141 \`\`\`js status.command({ 142 143 ` name: "faucet",` 144 ` title: I18n.t('faucet_title'),` 145 ` description: I18n.t('faucet_description'),` 146 ` color: "#7099e6",` 147 ` registeredOnly: true,` 148 ` params: [{` 149 ` name: "url",` 150 ` type: status.types.TEXT,` 151 ` suggestions: faucetSuggestions,` 152 ` placeholder: I18n.t('faucet_placeholder')` 153 ` }],` 154 ` preview: function (params) {` 155 ` return {` 156 ` markup: status.components.text(` 157 ` {},` 158 ` params.url` 159 ` )` 160 ` };` 161 ` },` 162 ` shortPreview: function (params) {` 163 ` return {` 164 ` markup: status.components.text(` 165 ` {},` 166 ` I18n.t('faucet_title') + ": " + params.url` 167 ` )` 168 ` };` 169 ` },` 170 ` validator: function (params, context) {` 171 ` var f = faucets.map(function (entry) {` 172 ` return entry.url;` 173 ` });` 174 175 ` if (f.indexOf(params.url) == -1) {` 176 ` var error = status.components.validationMessage(` 177 ` I18n.t('faucet_incorrect_title'),` 178 ` I18n.t('faucet_incorrect_description')` 179 ` );` 180 181 ` return {markup: error};` 182 ` }` 183 ` }` 184 185 }); \`\`\` 186 187 1. 1. Parameters 188 189 Argument | Description --------- | ----------- name | What your users 190 will type in following a forward slash to invoke the command. For 191 instance, if you wrote \`name: "hello"\`, your user might invoke 192 \`/hello\`. There is an additional \`params\` object available on any of 193 the below commands, including in params itself. title | This is what 194 will appear in the list of suggestions when a user starts typing a 195 command. description | Appears below the \`title\` in the list of 196 suggestions and allows you to provide a description of the command. 197 validator | Allows you to check your users’ input before sending off the 198 command. It takes a function, which should return an error if the input 199 is invalid. color | Defines the background color of the name of your 200 command as it appears in the list of suggestions. Give commands 201 different colors to help your users distinguish commands easily, and to 202 harmonize with your DApp’s brand and color scheme. icon | Define which 203 icon will appear next to action messages, such as sending Ether or 204 requesting a location. Think an arrow for sending, a pin for location 205 etc. params | Defines all the possible inputs to your command. Requires 206 an array holding an object, with possible parameters \`name\`, 207 \`placeholder\`, \`suggestions\`, and one of the \`status.types\`, which 208 are: \`status.types.TEXT\`, \`status.types.NUMBER\`, 209 \`status.types.PHONE\`, and \`status.types.PASSWORD\`. preview | Defines 210 what your user will see as a result of \*their\* action, before any 211 other response. The preview parameter takes a function, which should 212 return a \`status.component\`. shortPreview | While \`preview\` controls 213 how your command appears within your DApp’s chat interface, 214 \`short-preview\` controls how your commands get shown in the list of 215 chats, before your users tap on your chat. \`short-prview\` expects two 216 params: \`icon\` and \`params\`. onSend | A self-explanatory param that 217 takes a function which will be executed when the user presses the "send" 218 button. It will return a map that should contain the markup value. If 219 you specify this function, there will be no way to send a command to the 220 chat and, in this case, the area (it’s called the \`result-box\`) with a 221 specified markup will be displayed instead. fullscreen | If your command 222 has suggestions, this param controls whether that list of suggestions 223 expands to fill the entire screen. See the interactive suggestion area 224 tutorial for more. request | This will allow you to request any action 225 from the user, such as a phone number, password, confirmation to send 226 Ether etc. Used with the \`executeImmediately\` option set to \`true\`, 227 it will create a message the user can tap on an execute immediately. 228 executeImmediately (Boolean) | If true, this means that the 229 \*\*response\*\* will be executed immediately when you press on it. For 230 instance, when you see a response in a chat, you don’t have to type 231 something — you just need to press on a response and it will be executed 232 right after that. sequentialParams (Boolean) | Specifies the way command 233 arguments will be "requested". The default approach (\`sequentialParams 234 = false\`) is to type a command this way: \`/send 0.1 ETH somebody\`, 235 where \`0.1\`, \`ETH\` and \`somebody\` are arguments. However, there 236 may be situations when you want to ask each argument separately. You can 237 see the difference by executing \`/password\` command; it asks you for a 238 password and, only after the user has provided one, requests 239 confirmation. Currently there is one limitation — you can use argument 240 types (\`type\` value) only for \`sequentialParams\`, and if you want to 241 (for example) hide the argument input, you should use 242 \`sequentialParams\` handler (\!= null) | Of course, you probably want 243 the command to do something when your users call it\! The \`handler\` 244 parameter takes a function to accomplish this. For instance, suppose 245 your user inputs \`/hello howdy\`. "Howdy" is a valid string, and will 246 pass the \`hello\` validator. From there, your handler could take over 247 to send this greeting to another user: \`handler: 248 web3.shh.post(params.hello)\`. 249 250 1. 1. status.response 251 252 \> An example response for a confirmation code sent via SMS: 253 254 \`\`\`js status.response({ 255 256 ` name: "confirmation-code",` 257 ` color: "#7099e6",` 258 ` description: I18n.t('confirm_description'),` 259 ` sequentialParams: true,` 260 ` params: [{` 261 ` name: "code",` 262 ` type: status.types.NUMBER` 263 ` }],` 264 ` validator: function (params) {` 265 ` if (!/^[\d]{4}$/.test(params.code)) {` 266 ` var error = status.components.validationMessage(` 267 ` I18n.t('confirm_validation_title'),` 268 ` I18n.t('confirm_validation_description')` 269 ` );` 270 271 ` return {markup: error};` 272 ` }` 273 ` }` 274 275 }); \`\`\` 276 277 Now that you’ve covered all the parameters for \`status.command()\`, you 278 can easily understand \`status.response()\`. This method takes the same 279 parameters that \`status.command()\` does. The difference is that, with 280 this method, you can actively ask a user to issue a command of their 281 own. 282 283 For example, the Status DApp Wallet allows you to \`/request\` money. In 284 that case, the person you’re requesting money from will see the result 285 of \`status.response(send)\`. In other words, they’ll be asked to give a 286 command, \`/send\`, in response to your \`/request\` command. Please 287 check line 77-158 288 \[here\](https://github.com/status-im/status-react/blob/30596f743f0a6ac0b7aec575cc1483dd306cc1ef/bots/wallet/bot.js\#L77) 289 for more code. 290 291 The Wallet example illustrates that, as a DApp developer, you may wish 292 to use \`status.command()\` and \`status.response()\` together to create 293 dialogues of commands. You can also just use \`status.response()\` by 294 itself to prompt your users to enter necessary information as part of 295 the onboarding process for your DApp. 296 297 Because \`status.command()\` and \`status.response()\` take the same 298 parameters, you can sometimes use nearly the same code for both of them. 299 You simply have to consider when you want to ask a user to issue a 300 command, and when you want to just make the command available. Most of 301 the time, you’ll use \`status.command()\`. 302 303 1. 1. status.on 304 305 \`\`\`js status.on("init", function(params, context) { 306 307 `status.sendMessage("Hello, man!");` 308 309 }); \`\`\` 310 311 This method allows your DApp to respond to events. It requires an event 312 name as a string, and a callback function. With the "init" option shown 313 here, your DApp will trigger \`status.sendMessage()\` when the Status 314 app loads your DApp — your DApp will greet your users even before they 315 have clicked on it. Other options include "text-change" and "message" 316 317 1. 1. status.addListener 318 319 \`\`\`js status.addListener("on-message-input-change", 320 321 `function (params, context) {` 322 ` return jsSuggestions({code: params.message}, context);` 323 324 }); \`\`\` 325 326 \`\`\`js status.addListener("init", 327 328 `function (params, context) {` 329 ` return {"text-message": "Hey, man!"};` 330 331 }); \`\`\` 332 333 \`\`\`js 334 status.addListener("on-message-send", 335 336 `function (params, context) {` 337 ` if (isNaN(params.message)) {` 338 ` return {"text-message": "Seems that you don't want to send money :("};` 339 ` }` 340 341 ` var balance = web3.eth.getBalance(context.from);` 342 ` var value = parseFloat(params.message);` 343 ` var weiValue = web3.toWei(value, "ether");` 344 ` if (bn(weiValue).greaterThan(bn(balance))) {` 345 ` return {"text-message": "No way man, you don't have enough money! :)"};` 346 ` }` 347 ` try {` 348 ` web3.eth.sendTransaction({` 349 ` from: context.from,` 350 ` to: context.from,` 351 ` value: weiValue` 352 ` });` 353 ` return {"text-message": "You are the hero, you sent " + value + " ETH to yourself!"};` 354 ` } catch (err) {` 355 ` return {"text-message": "Something went wrong :("};` 356 ` }` 357 358 }); \`\`\` 359 360 Listener | Description -------------------------- | ----------- 361 on-message-input-change | This is analogous to a \`text-change\` event, 362 except that it targets the chat’s input. You can find the jsSuggestions 363 that are passed in in the example 364 \[here\](https://github.com/status-im/status-react/blob/develop/bots/console/bot.js\#L312). 365 init | Is called once, when a new session begins ("session" is currently 366 taken to mean the interval between login and logout from a user's 367 account). In the example provided the bot will just send the "Hey, 368 man\!" message to the user, but it could also it could return \`markup\` 369 which will be shown in the suggestions area, etc. on-message-send | Will 370 be called when any (not command) message is sent. The example provided 371 shows you how to send ether to yourself as a neat way of testing the 372 functionality. 373 374 1. 1. status.localizeNumber 375 376 \`\`\`js preview: function (params, context) 377 { 378 379 ` return {` 380 ` markup: status.components.text(` 381 ` {},` 382 ` I18n.t('request_requesting') + " "` 383 ` + status.localizeNumber(params.amount, context.delimiter, context.separator)` 384 ` + " ETH"` 385 ` )` 386 ` };` 387 ` },` 388 ` ``` ` 389 390 A simple method to try and ensure that whatever number the user inputs, 391 is put into a usable format. The example provided shows it in use to 392 make sure the number requesting ETH is handled correctly. This is part 393 of a larger \`status.command()\` object that can be found 394 \[here\](https://github.com/status-im/status-react/blob/30596f743f0a6ac0b7aec575cc1483dd306cc1ef/bots/wallet/bot.js\#L182). 395 396 1. 1. status.types 397 398 \`\`\`js 399 400 ` types: {` 401 ` TEXT: 'text',` 402 ` NUMBER: 'number',` 403 ` PHONE: 'phone',` 404 ` PASSWORD: 'password'` 405 ` }` 406 407 \`\`\` 408 409 Types dictate what sort of data your users may input. The type you 410 specify will determine what kind of keyboard gets shown to the user (if 411 you have not already defined a custom one) so that they can input their 412 response easily. It is important to specify them for a smooth, easy, and 413 intuitive UI. 414 415 1. 1. status.types.TEXT 416 417 \`\`\`js 418 419 status.command({ 420 421 ` name: "faucet",` 422 ` title: I18n.t('faucet_title'),` 423 ` description: I18n.t('faucet_description'),` 424 ` color: "#7099e6",` 425 ` registeredOnly: true,` 426 ` params: [{` 427 ` name: "url",` 428 ` type: status.types.TEXT,` 429 ` suggestions: faucetSuggestions,` 430 ` placeholder: I18n.t('faucet_placeholder')` 431 ` }],` 432 433 \`\`\` 434 435 If you define a \`text\` input, when the user responds, it will pop up a 436 normal QWERTY keyboard. The example provided shows the first part of the 437 \`status.commnad()\` we use to interact with our faucet so that our 438 users can get some (test) ether to do interesting things with. 439 440 1. 1. status.types.NUMBER 441 442 \`\`\`js status.response({ 443 444 ` name: "confirmation-code",` 445 ` color: "#7099e6",` 446 ` description: I18n.t('confirm_description'),` 447 ` sequentialParams: true,` 448 ` params: [{` 449 ` name: "code",` 450 ` type: status.types.NUMBER` 451 ` }],` 452 453 \`\`\` 454 455 Defining \`number\` will result in the keyboard opening to it's number 456 section. The example provided shows the first part of the 457 \`status.response()\` object we use to request a confirmation code from 458 the user when syncing their phone contacts. 459 460 1. 1. status.types.PHONE 461 462 \`\`\`js var phoneConfig = { 463 464 ` name: "phone",` 465 ` registeredOnly: true,` 466 ` icon: "phone_white",` 467 ` color: "#5bb2a2",` 468 ` title: I18n.t('phone_title'),` 469 ` description: I18n.t('phone_description'),` 470 ` sequentialParams: true,` 471 ` validator: function (params) {` 472 ` return {` 473 ` validationHandler: "phone",` 474 ` parameters: [params.phone]` 475 ` };` 476 ` },` 477 ` params: [{` 478 ` name: "phone",` 479 ` type: status.types.PHONE,` 480 ` suggestions: phoneSuggestions,` 481 ` placeholder: I18n.t('phone_placeholder')` 482 ` }]` 483 484 }; \`\`\` Defining \`phone\` will result in the keyboard opening to it's 485 number section as well. One example should suffice to give you a general 486 idea of how this works, so we have provided an excerpt of how we do 487 phone cofirmation using the \`PHONE\` type. You can find the full code 488 \[here\](https://github.com/status-im/status-react/blob/develop/bots/console/bot.js\#L450) 489 490 1. 1. status.types.PASSWORD 491 492 \`\`\`js status.response({ 493 494 ` name: "password",` 495 ` color: "#7099e6",` 496 ` description: I18n.t('password_description'),` 497 ` icon: "lock_white",` 498 ` sequentialParams: true,` 499 ` params: [` 500 ` {` 501 ` name: "password",` 502 ` type: status.types.PASSWORD,` 503 ` placeholder: I18n.t('password_placeholder'),` 504 ` hidden: true` 505 ` },` 506 ` {` 507 ` name: "password-confirmation",` 508 ` type: status.types.PASSWORD,` 509 ` placeholder: I18n.t('password_placeholder2'),` 510 ` hidden: true` 511 ` }` 512 513 \`\`\` 514 515 Defining \`password\` will result in the keyboard opening to it's 516 variable character section. The example provided shows the first part of 517 the \`status.response()\` object we use to request and confirm a 518 password from our user when they are setting up their account. 519 520 1. 1. status.events 521 522 \`\`\`js 523 524 ` events: {` 525 ` SET_VALUE: 'set-value',` 526 ` SET_COMMAND_ARGUMENT: 'set-command-argument'` 527 ` }` 528 529 \`\`\` 530 531 Events are essentially the glue that allow you to commuicate with the 532 Status API effectively. 533 534 1. 1. status.events.SET_VALUE 535 536 \`\`\`js {onPress: 537 status.components.dispatch(\[status.events.SET_VALUE, entry\])}, \`\`\` 538 539 This method will completely update the content of text input. The full 540 function around the snippet example provided can be found 541 \[here\](https://github.com/status-im/status-react/blob/30596f743f0a6ac0b7aec575cc1483dd306cc1ef/bots/console/bot.js\#L560). 542 543 1. 1. status.events.SET_COMMAND_ARGUMENT 544 545 \`\`\`js {onPress: 546 status.components.dispatch(\[status.events.SET_COMMAND_ARGUMENT, \[0, 547 entry.url\]\])}, \`\`\` As opposed to \`SET_VALUE\`, this event will 548 only update a single argument which you define. The full function around 549 the snippet example provided can be found 550 \[here\](https://github.com/status-im/status-react/blob/30596f743f0a6ac0b7aec575cc1483dd306cc1ef/bots/console/bot.js\#L485). 551 552 1. 1. status.components 553 554 Create React Native Components yourself or use our pre-fabricated 555 components. 556 557 1. 1. status.components.view 558 559 \`\`\`js function faucetSuggestions(params) 560 { 561 562 ` var suggestions = faucets.map(function (entry) {` 563 ` return status.components.touchable(` 564 ` {onPress: status.components.dispatch([status.events.SET_COMMAND_ARGUMENT, [0, entry.url]])},` 565 ` status.components.view(` 566 ` suggestionContainerStyle,` 567 ` [status.components.view(` 568 ` suggestionSubContainerStyle,` 569 ` [` 570 ` status.components.text(` 571 ` {style: valueStyle},` 572 ` entry.name` 573 ` ),` 574 ` status.components.text(` 575 ` {style: descriptionStyle},` 576 ` entry.url` 577 ` )` 578 ` ]` 579 ` )]` 580 ` )` 581 ` );` 582 ` });` 583 584 \`\`\` 585 586 Standard RN component - please see 587 \[JSCoach\](https://js.coach/react-native) for more. Expects 2 arguments 588 - \`options\` and \`element\`. The example provided shows how we use the 589 \`view\` component (in combination with the \`text\` component) to 590 provide different suggestions about which faucets our users can call to 591 get some test ether. 592 593 1. 1. status.components.text 594 595 Standard RN component - please see 596 \[JSCoach\](https://js.coach/react-native) for more. Expects 2 arguments 597 - \`options\` and some array of strings \`s\`. 598 599 1. 1. status.components.slider 600 601 Standard RN component - please see 602 \[JSCoach\](https://js.coach/react-native) for more. Expects only one 603 argument - \`options\`. 604 605 Please see the \`defineSubscription\` method below for an example of 606 this component in action. 607 608 1. 1. status.components.image 609 610 Standard RN component - please see 611 \[JSCoach\](https://js.coach/react-native) for more. Expects only one 612 argument - \`options\`. 613 614 1. 1. status.components.touchable 615 616 \`\`\`js function jsSuggestions(params, context) 617 { 618 619 ` var suggestions = getJsSuggestions(params.code, context);` 620 ` var sugestionsMarkup = [];` 621 622 ` for (var i = 0; i < suggestions.length; i++) {` 623 ` var suggestion = suggestions[i];` 624 625 ` if (suggestion.title.indexOf('*') >= 0) {` 626 ` suggestion.title = createMarkupText(suggestion.title);` 627 ` }` 628 ` var suggestionMarkup = status.components.view(jsSuggestionContainerStyle,` 629 ` [status.components.view(jsSubContainerStyle,` 630 ` [` 631 ` status.components.text({style: jsValueStyle},` 632 ` suggestion.title),` 633 ` status.components.text({style: jsDescriptionStyle},` 634 ` suggestion.desc)` 635 ` ])]);` 636 ` if (suggestion.pressValue) {` 637 ` suggestionMarkup = status.components.touchable({` 638 ` onPress: status.components.dispatch([status.events.SET_VALUE, suggestion.pressValue])` 639 ` },` 640 ` suggestionMarkup` 641 ` );` 642 ` }` 643 ` sugestionsMarkup.push(suggestionMarkup);` 644 ` }` 645 646 ` if (sugestionsMarkup.length > 0) {` 647 ` var view = status.components.scrollView(jsSuggestionsContainerStyle(sugestionsMarkup.length),` 648 ` sugestionsMarkup` 649 ` );` 650 ` return {markup: view};` 651 ` }` 652 653 } \`\`\` 654 655 Standard RN component - please see 656 \[JSCoach\](https://js.coach/react-native) for more. Expects 2 arguments 657 - \`options\` and \`element\`. The example provided uses the 658 \`touchable\` component to make our suggestions that much more native 659 and-feeling and interactive. It's worth noting that \`touchable\` 660 components can only wrap \`view\` components, so any touchable text for 661 example needs to first be wrapped in a \`view\`. 662 663 1. 1. status.components.scrollView 664 665 \`\`\`js 666 667 ` var view = status.components.scrollView(` 668 ` suggestionsContainerStyle(ph.length),` 669 ` suggestions` 670 ` );` 671 672 ` return {markup: view};` 673 674 \`\`\` 675 676 Standard RN component - please see 677 \[JSCoach\](https://js.coach/react-native) for more. Expects 2 arguments 678 - \`options\` and \`elements\`. In the code snippet provided, we have 679 taken the suggestions from the example above to do \`components.view\` 680 and now want to inject it into a scrollView component for a better and 681 smoother UI that our users have more control over. 682 683 1. 1. status.components.webView 684 685 Standard RN component - please see 686 \[JSCoach\](https://js.coach/react-native) for more. Expects only 1 687 argument - \`url\` and is what we use to display - as expected - the 688 webView of a given DApp when browsing to it. 689 690 1. 1. status.components.validationMessage 691 692 \> An example of using validationMessage within the validator argument 693 being passed to status.command. 694 695 \`\`\`js validator: function (params, context) { 696 697 ` var f = faucets.map(function (entry) {` 698 ` return entry.url;` 699 ` });` 700 701 ` if (f.indexOf(params.url) == -1) {` 702 ` var error = status.components.validationMessage(` 703 ` I18n.t('faucet_incorrect_title'),` 704 ` I18n.t('faucet_incorrect_description')` 705 ` );` 706 707 ` return {markup: error};` 708 ` }` 709 710 } \`\`\` 711 712 This is the only custom Status component and it takes just two strings, 713 and will return them wrapped in text components inside a view. You can 714 find the full example 715 \[here\](https://github.com/status-im/status-react/blob/develop/bots/console/bot.js\#L550). 716 717 1. 1. status.components.bridgedWebview 718 719 Standard RN component - please see 720 \[JSCoach\](https://js.coach/react-native) for more. Expects only 1 721 argument - \`url\`. 722 723 1. 1. status.components.subscribe 724 725 A method that allows you to add a subscription in the markup and expects 726 just 1 argument - \`path\`. The added subscription will get the value 727 from the bot-db using your specifiied path. 728 729 1. 1. status.components.dispatch 730 731 \`\`\`js var view = \["view", 732 {}, 733 734 ` ["text", {}, "Balance " + balance + " ETH"],` 735 ` ["text", {}, ["subscribe", ["doubledValue"]]],` 736 ` ["slider", {` 737 ` maximumValue: ["subscribe", ["balance"]],` 738 ` value: defaultSliderValue,` 739 ` minimumValue: 0,` 740 ` onSlidingComplete: ["dispatch", ["set", "sliderValue"]],` 741 ` step: 0.05` 742 ` }],` 743 ` ['touchable',` 744 ` {onPress: ['dispatch', ["set-value-from-db", "roundedValue"]]},` 745 ` ["view", {}, ["text", {}, "Set value"]]` 746 ` ],` 747 ` ["text", {style: {color: "red"}}, ["subscribe", ["validationText"]]]` 748 ` ];` 749 750 \`\`\` 751 752 A method that allows you to specify an event that will be dispatched on 753 some other event that occurs inside the markup (like pressing button, 754 text change etc.). By 'markup', we mean - essentially - the view, or the 755 mobile equivalent of the DOM. In the example provided, the variable 756 \`view\` is what we mean by markup (and is, in this case, part of our 757 \`superSuggestion\` function found 758 \[here\](https://github.com/status-im/status-react/blob/2862af86c960b481ddf64ec1713e14908a366616/bots/demo_bot/bot.js\#L31)) 759 we specify that \`\["set", "sliderValue"\]\` will be dispatched on 760 \`onSlidingComplete\`. We can’t allow user to write a real js handler 761 here, so this is our workaround for now. 762 763 1. 1. status.setSuggestions 764 765 A method that allows you to set the suggestions that will appear in the 766 markup, whether this is something simple like sending a message, or 767 pretty much anything 768 769 1. 1. status.setDefaultDb and status.updateDb 770 771 \`\`\`js function superSuggestion(params, context) 772 { 773 774 ` var balance = parseFloat(web3.fromWei(web3.eth.getBalance(context.from), "ether"));` 775 ` var defaultSliderValue = balance / 2;` 776 777 ` var view = ["view", {},` 778 ` ["text", {}, "Balance " + balance + " ETH"],` 779 ` ["text", {}, ["subscribe", ["doubledValue"]]],` 780 ` ["slider", {` 781 ` maximumValue: ["subscribe", ["balance"]],` 782 ` value: defaultSliderValue,` 783 ` minimumValue: 0,` 784 ` onSlidingComplete: ["dispatch", ["set", "sliderValue"]],` 785 ` step: 0.05` 786 ` }],` 787 ` ['touchable',` 788 ` {onPress: ['dispatch', ["set-value-from-db", "roundedValue"]]},` 789 ` ["view", {}, ["text", {}, "Set value"]]` 790 ` ],` 791 ` ["text", {style: {color: "red"}}, ["subscribe", ["validationText"]]]` 792 ` ];` 793 794 ` status.setDefaultDb({` 795 ` sliderValue: defaultSliderValue,` 796 ` doubledValue: doubledValueLabel({value: defaultSliderValue})` 797 ` });` 798 799 ` var validationText = "";` 800 801 ` if (isNaN(params.message)) {` 802 ` validationText = "That's not a float number!";` 803 ` } else if (parseFloat(params.message) > balance) {` 804 ` validationText =` 805 ` "Input value is too big!" +` 806 ` " You have only " + balance + " ETH on your balance!";` 807 ` }` 808 809 ` status.updateDb({` 810 ` balance: balance,` 811 ` validationText: validationText` 812 ` });` 813 814 ` return {markup: view};` 815 816 }; \`\`\` 817 818 It is easiest to show you an example of these two methods at work in our 819 \[demo-bot\](https://github.com/status-im/status-react/blob/develop/bots/demo_bot/bot.js\#L31) 820 within a superSuggestions object we have created. 821 822 \`status.setDefaultDb\` is a method that can be used to add default 823 values to bot-db. These values will be applied to app-db only when 824 markup is rendered the first time. For instance, on each change in 825 command input suggestions handler for particular command's parameter is 826 called, and this handler returns some markup. If markup wasn't changed 827 between calls values passed to setDefaultDb will not be applied to 828 bot-db 829 830 \`status.updateDb\` is a method that updates the bot-db, even if the 831 markup doesn't contain any changes. It too expects just 1 argument - 832 \`map\` 833 834 1. 1. status.sendMessage 835 836 This has just been implemented in the latest nightlies\! Go and grab one 837 of those and you'll have access to this route, as demonstrated by our 838 updated \[demo 839 bot\](https://github.com/status-im/status-react/blob/develop/bots/demo_bot/bot.js\#L106). 840 The snippet provided also reveals how to work with the javascript 841 concept of \`localStorage\`. 842 843 \`\`\`js status.addListener("on-message-send", function (params, 844 context) 845 { 846 847 ` var cnt = localStorage.getItem("cnt");` 848 ` if(!cnt) {` 849 ` cnt = 0;` 850 ` }` 851 852 ` cnt++;` 853 854 ` localStorage.setItem("cnt", cnt);` 855 ` if (isNaN(params.message)) {` 856 ` return {"text-message": "Seems that you don't want to send money :(. cnt = " + cnt};` 857 ` }` 858 859 ` var balance = web3.eth.getBalance(context.from);` 860 ` var value = parseFloat(params.message);` 861 ` var weiValue = web3.toWei(value, "ether");` 862 ` if (bn(weiValue).greaterThan(bn(balance))) {` 863 ` return {"text-message": "No way man, you don't have enough money! :)"};` 864 ` }` 865 ` web3.eth.sendTransaction({` 866 ` from: context.from,` 867 ` to: context.from,` 868 ` value: weiValue` 869 ` }, function (error, hash) {` 870 ` if (error) {` 871 ` status.sendMessage("Something went wrong, try again :(");` 872 ` status.showSuggestions(demoSuggestions(params, context).markup);` 873 ` } else {` 874 ` status.sendMessage("You are the hero, you sent " + value + " ETH to yourself!")` 875 ` }` 876 ` });` 877 878 }); \`\`\` 879 880 1. 1. status.defineSubscription 881 882 \`\`\`js function round(n) { 883 884 ` return Math.round(n * 100) / 100;` 885 886 } 887 888 function doubledValueLabel(params) 889 { 890 891 ` var value = round(params.value);` 892 ` return "sliderValue = " + value +` 893 ` "; (2 * sliderValue) = " + (2 * value);` 894 895 } 896 897 status.defineSubscription( 898 899 ` // the name of subscription and the name of the value in bot-db` 900 ` // associated with this subscription` 901 ` "doubledValue",` 902 ` // the map of values on which subscription depends: keys are arbitrary names` 903 ` // and values are db paths to another value` 904 ` {value: ["sliderValue"]},` 905 ` // the function which will be called as reaction on changes of values above,` 906 ` // should be pure. Returned result will be associated with subscription in bot-db` 907 ` doubledValueLabel` 908 909 ); 910 911 status.defineSubscription( 912 913 ` "roundedValue",` 914 ` {value: ["sliderValue"]},` 915 ` function (params) {` 916 ` return round(params.value);` 917 ` }` 918 919 ); \`\`\` This method was added to allow a bot to react on changes in 920 the bot-db and add another calculated value to that bot-db in the 921 result. It expects 3 arguments: the name of subscription, a map of 922 values on which the subscription depends, and a callback function. 923 924 \--- weight: 20 title: Tutorials --- 925 926 1. Tutorials 927 928 <!-- end list --> 929 930 1. 1. Overview 931 932 Just before we get started, it's well worth acquainting yourself with 933 some of our terminology so you'll be able to make sense of it all. This 934 anatomy establishes the different sections of the chat interface and 935 establishes a common verbiage. The main components are: 936 937 - Message 938 - Input 939 - Keyboard 940 - Suggestions 941 942 \!\[Chat Anatomy\](images/chat-anatomy.png) 943 944 Please take some time to familiarize yourself with all the areas and the 945 different configurations possible depending on what you want to do. 946 Missing from the above is what we refer to throughout this documentation 947 as the 'markup', by which we mean the mobile equivalent of the 'view', 948 i.e. where the messages appear. 949 950 Creating all of these native setups is totally possible through the API 951 - just read on. 952 953 1. 1. Installing Status 954 955 OK, let's learn how to build our first DApp on Status (mobile-first 956 ftw\!). To progress further, you need to have Status running either: 957 958 - on a real phone, 959 960 <!-- end list --> 961 962 - in an Android simulator, or 963 964 <!-- end list --> 965 966 - in an iOS simulator. 967 968 You can go to [1](https://test.status.im)(https://test.status.im) to 969 download for Android. Or you can DM @jarradhope with your email in our 970 \[Slack\](status-im.slack) for ios Testflight. 971 972 <aside class="success"> 973 974 Please note that these documents are intended for the latest version of 975 "status-dev-cli" (^3.2.8) and the latest release of Status app (^0.9.8). 976 To update \`status-dev-cli\` please run "npm uninstall -g 977 status-dev-cli" and then "npm i -g status-dev-cli". 978 979 </aside> 980 981 You can build Status yourself for either Android or iOS by following 982 \[these 983 guidelines\](https://wiki.status.im/contributing/development/building-status/). 984 There, you will find instructions for installing an Android simulator, 985 or starting up Status in the Xcode simulator. 986 987 Then, connect your phone to your Wi-Fi network (do not use USB). 988 Development machine and phone should be in the same network. Navigate to 989 the Console, select the \`/debug\` command and choose the \`On\` 990 suggestion. You’ll get back a message telling you that debugging is on, 991 and that you can use the 992 \[status-dev-cli\](https://github.com/status-im/status-dev-cli) tools. 993 994 You also need to install \`status-dev-cli\` to make talking between 995 Status and your machine a breeze. 996 997 \`\`\`shell npm i -g status-dev-cli \`\`\` 998 999 \!\[With your phone connected, /debug "On"\](images/starting.png) 1000 1001 - With your phone connected, /debug "On"\* 1002 1003 <!-- end list --> 1004 1005 1. 1. Debugging 1006 1007 OK, so Status is installed, but how do we interact with it? 1008 1009 You can check \`<DEVICE-IP>\` by running the \`scan\` command in the 1010 terminal. Another useful command we will be using a lot later on is 1011 \`list\` which will return a list of all DApps you have added to Status. 1012 1013 \`\`\`shell status-dev-cli scan status-dev-cli list --ip <DEVICE-IP> 1014 \#be sure to use the IPv4 address \`\`\` 1015 1016 You will see that these tutorials also use \`<MACHINE-IP>\` throughout. 1017 This refers to the INTERNAL IPv4 address of your development machine. 1018 You can find that by running the command provided. 1019 1020 \`\`\`shell ifconfig | grep inet 1021 1022 1. Look for this line - i.e. your IPv4 address - and use the equivalent 1023 of 192.168.0.103 1024 1025 \--\> inet 192.168.0.103 netmask 0xffffff00 broadcast 192.168.0.255 1026 \`\`\` 1027 1028 Even more importantly though, how can we actually debug the code we 1029 write? We know how important this is for good developers and we're still 1030 working on it. Currently, the options are limited, but we ask you to 1031 work with us here as it will improve rapidly over the next little while. 1032 1033 The first and the most powerful option is the development tools included 1034 in your browser. Chrome supports remote debugging, and you can easily 1035 connect to any web view on your mobile and debug it right from the 1036 browser. The detailed instructions can be found 1037 \[here\](https://developers.google.com/web/tools/chrome-devtools/remote-debugging/). 1038 1039 If you use iOS, you can use Safari on your Mac to debug any remote web 1040 page. 1041 \[Here\](http://developer.telerik.com/featured/a-concise-guide-to-remote-debugging-on-ios-android-and-windows-phone/) 1042 is a nice guide that will explain everything to you. 1043 1044 Unfortunately, you cannot use your browser's development tools to debug 1045 bots, as switching the node only works for DApps currently. So, the 1046 option we provide for bots is the ability to extract logs. 1047 1048 \`\`\`shell status-dev-cli log <DAPP-IDENTITY> --ip <DEVICE-IP> \`\`\` 1049 1050 1. 1. Networking 1051 1052 We give instructions here for Genymotion (a popular Android emulator). 1053 1054 1\. Install genymotion 1. Create a genymotion virtual device 1. Switch 1055 to network bridge mode (in the settings of your virtual device) 1056 1057 \!\[Switch to "Bridge"\](images/networking.png) 1058 1059 1\. Start virtual device 1. Install status.im apk from nightly builds by 1060 dragging onto emulator window 1. Start status.im app on virtual device 1061 1. Turn on debugging in console (/debug On). 1. Open terminal and run 1062 \`status-dev-cli scan\` it returns two \`<DEVICE-IP>\` addresses, use 1063 \`192.168.1.\*\`, and ignore \`192.168.56.\*\`. Alternately retrieve the 1064 device ip from the emulator window \`Settings \> About phone \> Status 1065 \> IP address\`. 1. Run \`status-dev-cli add \[dapp\] --ip 1066 <DEVICE-IP>\`. \*\*Replace\*\* \`\[dapp\]\` with your dapp details 1067 (\`whisper-identity\`, etc) as stringified json or \*\*remove\*\* 1068 \`\[dapp\]\` if those details are specified in a \`package.json\` in the 1069 current directory. 1070 1071 1. 1. My First DApp 1072 1073 {{% tabs DIY Embark Truffle %}} {{% tab DIY %}} 1074 1075 1. 1. Do It Yourself with \`status-dev-cli\` 1076 1077 First, install the \`status-dev-cli\` tools globally using NPM. Then, 1078 create a directory for your app to live in, switch into it, and create 1079 an \`index.html\` file and an \`app.js\` file. 1080 1081 \`\`\`shell npm install -g status-dev-cli mkdir ~/my-dapp && cd my-dapp 1082 touch index.html app.js \`\`\` 1083 1084 The index.html will be really simple. We are going to add several meta 1085 tags to make our DApp look good on the small screens of mobile phones, 1086 and add a span that will be used by our JavaScript. 1087 1088 Our \`app.js\` file will also be simple. We are going to display the 1089 information about your account inside a span with \`account id\`. Status 1090 injects \`web3.js\` automatically, so you have an access to web3 1091 variable from everywhere and you don’t need to care about including 1092 \`web3.js\` manually. However, you can do this and most probably you 1093 want to do this if you want to make your DApps work on other platforms. 1094 1095 \> In index.html, 1096 add: 1097 1098 \`\`\`html 1099 1100 <html> 1101 1102 <head> 1103 1104 <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> 1105 1106 <meta name="HandheldFriendly" content="True"> 1107 1108 <meta name="MobileOptimized" content="320"> 1109 1110 <meta name="viewport" content="width=device-width,minimum-scale=1,maximum-scale=1"> 1111 1112 <title> 1113 1114 My DApp 1115 1116 </title> 1117 1118 <script src="app.js"> 1119 1120 </script> 1121 1122 </head> 1123 1124 <body> 1125 1126 <h1> 1127 1128 Hello world\! 1129 1130 </h1> 1131 1132 `Web3 account: `<span id="account"></span> 1133 1134 </body> 1135 1136 </html> 1137 1138 \`\`\` \> In app.js, add: 1139 1140 \`\`\`js function onContentLoaded() { 1141 1142 ` var accountSpan = document.getElementById("account");` 1143 ` accountSpan.innerHTML = ` 1144 ` (typeof web3 === "undefined" ? "undefined" : web3.eth.accounts);` 1145 1146 } document.addEventListener("DOMContentLoaded", onContentLoaded); \`\`\` 1147 1148 You then need to install a really simple \`http-server\` from NPM (we 1149 recommend it for ease-of-use), and start it in the \`my-dapp\` directory 1150 we just created. 1151 1152 Open a new terminal session, navigate back to your \`my-dapp\` 1153 directory, and go ahead and add your dapp to Status\! Make sure to pass 1154 in the \`--ip\` flag using the address returned to you by Console, when 1155 you \[enabled debugging\](\#enabling-debugging). 1156 1157 \`<MACHINE-IP>\` needs to be the internal IPv4 address returned when you 1158 run \`ifconfig | grep inet\`. 1159 1160 \`\`\`shell npm install http-server -g http-server \`\`\` 1161 1162 \> In a new terminal window run the port forwarding and DApp connection 1163 stuff. It is important to pass in the \`--ip\` flag with the IP address 1164 listed by Console once you have selected the \`debug\` option and turned 1165 it on. 1166 1167 \`\`\`shell status-dev-cli add '{"whisper-identity": "hello-bot", 1168 "dapp-url": "<http://><MACHINE-IP>:8080/", "name": "Hello"}' --ip 1169 <DEVICE-IP> \`\`\` 1170 1171 That's it\! You should be able to see your DApp in the chats, and 1172 opening it should browse automatically to a page that shows your account 1173 information. You can also do live-reloading once you're happy with this 1174 by running \`status-dev-cli watch $PWD hello-bot --ip <DEVICE-IP>\` 1175 1176 - Known Issues 1177 1178 1\) You may need to escape the \`json\` information you are passing into 1179 \`status-dev-cli\` if you are on a windows machine, like so: 1180 \`status-dev-cli add '{\\"whisper-identity\\": \\"my-dapp5\\", 1181 \\"dapp-url\\": \\"<http://><MACHINE-IP>:8 080\\",\\"name\\": \\"My 1182 DApp\\"}' --ip <DEVICE-IP>\` 1183 1184 2\) If using a real device, you also need to ensure that it is set to 1185 use MTP (media transfer Protocol) in the USB-debugging settings. Open 1186 the equivalent of your settings or develop options by pulling down the 1187 top menu and clicking in the debugging options. 1188 1189 3\) The new version of \`status-dev-cli\` does not require you to do any 1190 \`adb\` port forwarding any more and will, in fact, fail if you do. Just 1191 use the \`scan\` and \`list\` commands as and when you need them. 1192 1193 Happy 1194 travels\! 1195 1196 <aside class="success"> 1197 1198 ` You need not use NPM's http-server to serve content, there are innumerable ways of doing this. Just pick whatever is best for your environment.` 1199 1200 </aside> 1201 1202 {{% /tab %}} 1203 1204 {{% tab Truffle %}} 1205 1206 1. 1. Truffle 1207 1208 OK, so we can write a little HTML5 DApp that displays information to 1209 Status users through a simple webView component. However, we want to do 1210 so much more\! We want to write smart contracts, deploy them, and 1211 interact with them through a fully mobile user interface; and we want to 1212 build decentralized chatbots that live within Status and make friends 1213 with all the humans. 1214 1215 If you want to get straight to making chatbots, please go 1216 \[here\](\#my-first-1-1-chatbot). 1217 1218 Frameworks can lighten the load of developing considerably, and so we 1219 include here some quick examples to get you up and running with the two 1220 most popular Ethereum frameworks currently available - Truffle and 1221 Embark. 1222 1223 Firstly, we'll need a network to develop against, so let's go get 1224 \`testrpc\` - a neat little simulation of the rules and logic of the 1225 Ethereum network that runs much faster than the live network (because 1226 it's only simulating things) and is very useful for quick and dirty 1227 iterations. 1228 1229 \`\`\`shell npm install -g ethereumjs-testrpc testrpc -p 8546 \`\`\` 1230 1231 That’s it\! It will show you a list of available accounts, private keys, 1232 your HD wallet and mnemonic. Please note that we're running testrpc on 1233 (non-default) RPC port 8546, just to avoid potential conflict with the 1234 node running inside Status. If using android, you need to open the 1235 connection from your PC to your phone on that port, so Status can listen 1236 for changes there. 1237 1238 We also need to make sure that our Status client is listening to our new 1239 \`testrpc\` network, rather than Ropsten, so that we can get the 1240 information we need about our contracts etc. Luckily, this is as easy as 1241 running: 1242 1243 \`\`\`shell status-dev-cli switch-node "<http://><MACHINE-IP>:8546" --ip 1244 <DEVICE-IP> 1245 1246 1. Of course, there are options. You can use go-ethereum instead of 1247 TestRPC, and instead of port forwarding you can switch to any other 1248 accessible node using its IP 1249 address. 1250 1251 \`\`\` 1252 1253 <aside class="success"> 1254 1255 ` Please note that "switch-node" only works for DApps, and NOT for bots. You javascript is still confined to the Otto VM jail for now. We are working on a solution, but please use "dapp-url" if developing against a local network for now.` 1256 1257 </aside> 1258 1259 Open a new shell (i.e. a new Terminal window or tab) for the next part. 1260 You’ll leave \`testrpc\` running in the first window, and use the second 1261 window for the rest of the tutorial. 1262 1263 Now that you have \`testrpc\` is going, and a new shell is open, run: 1264 1265 \`\`\`shell npm install -g truffle \# Version 3.0.5+ required. \`\`\` 1266 1267 This installs the Truffle framework, and you can find its GitHub \[page 1268 here\](https://github.com/trufflesuite/truffle). 1269 1270 With Truffle installed, we can grab the Status Truffle Box, and get a 1271 basic DApp running. All the Truffle Boxes also include the app 1272 frameworks React and Redux, which were designed by Facebook and are 1273 widely used by app developers. You can find the other Truffle Boxes 1274 \[here\](https://truffle-box.github.io/). 1275 1276 To install the Status Truffle box, all you have to do is run this 1277 command in the same Terminal window: 1278 1279 \`\`\`shell git clone 1280 <https://github.com/status-im/truffle-box-status.git> 1281 1282 1. Change into the truffle box directory and install the node 1283 dependencies 1284 1285 cd truffle-box-status && npm install 1286 1287 1. Compile the contracts from Solidity (much like JavaScript) into 1288 runnable EVM code 1289 1290 `truffle compile` 1291 1292 1. Publish the compiled contracts to your network. testrpc must already 1293 be running 1294 1295 `truffle migrate` 1296 1297 \`\`\` 1298 1299 \!\[Example on OS X: testrpc running on the left, and installing Truffle 1300 on the right\](images/starting-a-dapp-on-status-with-frameworks_02.png) 1301 1302 - Example on OS X: testrpc running on the left, and installing Truffle 1303 on the right\* 1304 1305 As you run the \`migrate\` command - which is what deploys your 1306 contracts to the network - you can look at the window with \`testrpc\` 1307 running, and you’ll see your transactions being published. If you get 1308 \`Error: Invalid JSON RPC response\`, you probably forgot to run 1309 \`testrpc\`. 1310 1311 Now we are ready to see our DApp running on Status. From within your 1312 DApp directory, run: 1313 1314 \`\`\`shell 1315 1316 1. Run your Javascript 1317 1318 npm run start 1319 1320 1. (Remember to set ENV variable if working with real device) 1321 1322 `IP=`<DEVICE-IP>` npm run start` 1323 1324 \`\`\` 1325 1326 This should tell you that the the app is running, and that the DApp has 1327 been added to the Status Contacts. 1328 1329 \!\[The DApp added to the default 1330 Contacts\](images/starting-a-dapp-on-status-with-frameworks_03.png) 1331 1332 - The DApp added to the default Contacts\* 1333 1334 Again, the DApp should appear in your chats screen, and navigating to it 1335 should automatically open a browser that reveals all the goodies hidden 1336 in this truffle box. It should also display the stored value of \`5\` 1337 from the SimpleStorage contract that we deployed to \`testrpc\` by 1338 running \`truffle migrate\` above. 1339 1340 If you would like to change the name that appears for your bot when it 1341 gets added to Status, simply edit the \`package.json\` and update the 1342 name there. 1343 1344 Once everything is running, leave it as is and move on directly to the 1345 next truffle tutorial to see the power of the \`status-dev-cli watch\` 1346 command. 1347 1348 - Known problems and Notes:\* 1349 1350 1\) If you are running on a real iOS device, you need to configure 1351 Truffle Box to use the network on your computer. In \`truffle.js\`, 1352 change \`host\` to the IP of your computer: 1353 1354 \`\`\`js module.exports = { 1355 1356 ` migrations_directory: "./migrations",` 1357 ` networks: {` 1358 ` development: {` 1359 ` host: "`<MACHINE-IP>`",` 1360 ` port: 8546,` 1361 ` network_id: "*" // Match any network id` 1362 ` }` 1363 ` }` 1364 1365 }; \`\`\` 1366 1367 2\) You can always use \`localhost\` instead of \`<MACHINE-IP>\`, but 1368 the application won't be accessible automatically, since it runs on port 1369 3000 and your device/emulator knows nothing about it. Execute the 1370 following to induce black magic and make the web application accessible: 1371 1372 \`\`\`shell adb reverse tcp:8546 tcp:8546 adb reverse tcp:3000 tcp:3000 1373 \`\`\` 1374 1375 {{% /tab %}} 1376 1377 {{% tab Embark %}} 1378 1379 1. 1. Embark 1380 1381 OK, so Truffle is not your favourite and you prefer using Embark. Fine 1382 with us. As always, make sure you have installed the framework first. 1383 1384 \`\`\`shell npm -g install embark \`\`\` 1385 1386 Embark makes it super easy to set up a demo and get up and running fast: 1387 1388 \`\`\`shell embark demo cd embark_demo \`\`\` 1389 1390 Next we want to start the network. You can run a full Ethereum node with 1391 \`embark blockchain\`, but for development you probably want to run 1392 \`testrpc\`. We want it to run on port 8546 though, so it doesn't 1393 interfere with Status, so we need to edit the \`blockchain.js\`: 1394 1395 \`\`\`shell nano config/blockchain.json 1396 1397 1. Now edit the 'Development' Network and change only the rpcPort field 1398 to 8546: 1399 1400 "development": { 1401 1402 ` "enabled": true,` 1403 ` "networkType": "custom",` 1404 ` "genesisBlock": "config/development/genesis.json",` 1405 ` "datadir": ".embark/development/datadir",` 1406 ` "mineWhenNeeded": true,` 1407 ` "nodiscover": true,` 1408 ` "maxpeers": 0,` 1409 ` "rpcHost": "`<MACHINE-IP>`",` 1410 ` "rpcPort": 8546,` 1411 ` "rpcCorsDomain": "`<http://><MACHINE-IP>`:8000",` 1412 ` "account": {` 1413 ` "password": "config/development/password"` 1414 ` }` 1415 ` }` 1416 1417 1. ctrl+O will write your changes to file, ctrl+X will exit the file. 1418 2. Now, navigate back to the root of your project and start testrpc 1419 1420 cd .. && embark simulator \`\`\` 1421 1422 Open a new shell tab and switch the RPC node. Once that is done, you 1423 need to install the \`embark-status\` package. 1424 1425 \`\`\`shell status-dev-cli switch-node "<http://><MACHINE-IP>:8546" --ip 1426 <DEVICE-IP> npm install embark-status --save \`\`\` 1427 1428 When using a real device, you will now need to insert the relevant IP 1429 into two config files. 1430 1431 Open the file \`embark.json\` and edit the \`plugins\` key to reflects 1432 your DEVICE's IP address: 1433 1434 \`\`\`js "plugins": { 1435 1436 ` "embark-status": {` 1437 ` "deviceIp": "`<DEVICE-IP>`",` 1438 ` "whisperIdentity": "dapp-embark-test",` 1439 ` "name": "MyEmbarkDapp"` 1440 ` }` 1441 1442 } \`\`\` 1443 1444 Navigate to and change the \`config/webserver.js\` file so that it 1445 reflects your development machine's IP address: 1446 1447 \`\`\`js { 1448 1449 ` "enabled": true,` 1450 ` "host": "`<MACHINE-IP>`",` 1451 ` "port": 8000` 1452 1453 } \`\`\` 1454 1455 Now we’re ready to run the DApp on Status. From within your DApp 1456 directory, run: 1457 1458 \`\`\`shell embark run \`\`\` 1459 1460 The Embark console will appear within your shell with useful information 1461 about the SimpleStorage contract it has created, compiled, and deployed. 1462 Now just add your DApp, and have some fun\! 1463 1464 \`\`\`shell status-dev-cli add '{"whisper-identity": "embark", 1465 "dapp-url": "<http://><MACHINE-IP>:8000/", "name": "Embark"}' --ip 1466 <DEVICE-IP> \`\`\` 1467 1468 \!\[\](images/starting-a-dapp-on-status-with-frameworks_04.png) 1469 1470 \!\[The Embark simulator runs in one Terminal window on the left, and 1471 the Embark console on the 1472 right\](images/starting-a-dapp-on-status-with-frameworks_05.png) 1473 1474 - The Embark simulator runs in one Terminal window on the top, and the 1475 Embark console on the bottom\* 1476 1477 <!-- end list --> 1478 1479 - Known Issues and Notes:\* 1480 1481 1\) To deploy the DApp successfully on a device you may need to patch 1482 \[this 1483 line\](https://github.com/status-im/embark-status/blob/master/index.js\#L13) 1484 in embark-status to include \`+ " --dapp-port 5561"\`. 1485 1486 2\) You can always use \`localhost\` instead of \`<MACHINE-IP>\`, but 1487 the application won't be accessible automatically, since it runs on port 1488 8000 and your device/emulator knows nothing about it. Execute the 1489 following to induce black magic and make the web application accessible: 1490 1491 \`\`\`shell adb reverse tcp:8546 tcp:8546 adb reverse tcp:8000 tcp:8000 1492 \`\`\` 1493 1494 {{% /tab %}} 1495 1496 {{% /tabs %}} 1497 1498 If you want to remove your DApp because you're unhappy with it for some 1499 reason, just run \`status-dev-cli list --ip <DEVICE-IP>\` and then 1500 \`status-dev-cli remove --ip <DEVICE-IP> \[my-dapp\]\` where \[my-dapp\] 1501 is the \`whisper-identity\` returned by the \`list\` command. 1502 1503 Using Status, you can now develop mobile DApps as easily as developing 1504 for MetaMask or Mist\! But Status offers extra goodies as well. 1505 1506 In particular, Status will help you allow your users to chat with your 1507 DApp\! The chat interface will let your users easily and intuitively 1508 accomplish tasks. In the future, your users will be able to hold group 1509 conversations where all the other participants are DApps, which is kind 1510 of amazing. 1511 1512 Later we’ll have an easy mechanism to make your DApp available for 1513 others to use on Status, but for now please just submit a pull request 1514 using our \[guide on adding 1515 DApps\](http://wiki.status.im/contributing/development/adding-dapps/). 1516 1517 1. 1. My First 1-1 Chatbot 1518 1519 {{% tabs DIY Embark Truffle %}} {{% tab DIY %}} 1520 1521 1. 1. Do It Yourself 1522 1523 First, we're going to create a new \`bots\` directory and add file to 1524 keep our javascript in. 1525 1526 \`\`\`shell cd ~/my-dapp mkdir bots && cd bots && touch bot.js \`\`\` 1527 1528 Instead of adding a new DApp, we can now include a \`bot-url\` parameter 1529 in our call to \`status-dev-cli\`. The chatbot url targets a \`js\` 1530 file, and this file will be loaded in the Otto VM shown in the anatomy. 1531 Code in this file сan interact with the input field, messages and react 1532 however we program it to. 1533 1534 Add the following code snippet to the newly-created \`bot.js\` file. 1535 1536 \`\`\`js status.addListener("on-message-send", function (params, 1537 context) { 1538 1539 ` var result = {` 1540 ` err: null,` 1541 ` data: null,` 1542 ` messages: []` 1543 ` };` 1544 1545 ` try {` 1546 ` result["text-message"] = "You're amazing, master!";` 1547 ` } catch (e) {` 1548 ` result.err = e;` 1549 ` }` 1550 1551 ` return result;` 1552 1553 }); \`\`\` 1554 1555 Then, navigate back to the \`bots\` directory, do the necessary Android 1556 steps if you are using that platform, and start the http server again. 1557 Then, open a new shell window and add your new bot. It's important to 1558 note a few things here. We are \`add\`ing a new new bot, rather than 1559 just watching the DApp we built earlier for changes. Also, we are only 1560 passing in a \`bot-url\`, rather than a \`dapp-url\` - this will ensure 1561 that, when you open your new bot contact, it won't automatically launch 1562 a browser a window. 1563 1564 \`\`\`shell 1565 1566 1. make sure you're in my-dapp or the equivalent 1567 1568 cd ~/my-dapp 1569 1570 1. start the server and then open a new shell window 1571 1572 http-server \`\`\` 1573 1574 \`\`\`shell status-dev-cli add '{"whisper-identity": "botler", "name": 1575 "Botler" ,"bot-url": "<http://><MACHINE-IP>:8080/bots/bot.js"}' --ip 1576 <DEVICE-IP> \`\`\` 1577 1578 This is pretty much the simplest responsive chatbot we can write, using 1579 only the \`addListener\` function from the API. All it's listening for 1580 is a message-send event, to which it will try to respond with the test 1581 \`You're amazing, master\!\`. 1582 1583 Obviously, there's much more we can do than simply listen for messages 1584 and send flattering responses. All will be revealed in the next 1585 tutorial. If you're feeling impatient, you can find a full Demo Bot 1586 \[here\](https://github.com/status-im/status-react/tree/34b77022f7926dbabbb0e8c5e8471eaea5ed812f/bots/demo_bot). 1587 1588 - Known Issues and Notes:\* 1589 1590 1\) You can always use \`localhost\` instead of \`<MACHINE-IP>\`, but 1591 the application won't be accessible automatically, since it runs on port 1592 8080 and your device/emulator knows nothing about it. Execute the 1593 following to induce black magic and make the web application accessible: 1594 1595 \`\`\`shell adb reverse tcp:8080 tcp:8080 \`\`\` 1596 1597 {{% /tab %}} 1598 1599 {{% tab Embark %}} 1600 1601 1. 1. Embark 1602 1603 OK, so even though \`status-dev-cli\` is lightweight and awesome, the 1604 frameworks offer some really cool features and make development 1605 significantly easier for many projects. Let's see what it's like to add 1606 the same chatbot to Status using Embark. 1607 1608 First, go back to the \`embark_demo/\` directory we created 1609 \[earlier\](\#my-first-dapp), where we set up the correct configuration 1610 for Embark and Status. Essentially, you just want to make sure - as with 1611 the Truffle Box example - that you put the javascript file in the right 1612 place so that you can reference it correctly. 1613 1614 Instead of adding a new DApp, we can now include a \`bot-url\` parameter 1615 in our call to \`status-dev-cli\`. The chatbot url targets a \`js\` 1616 file, and this file will be loaded in the Otto VM shown in the anatomy. 1617 Code in this file сan interact with the input field, messages and react 1618 however we program it to. 1619 1620 Let's create a bot.js in the \`/embark_demo/app/js/\` directory and put 1621 the short snippet of javascript we need into it. 1622 1623 \`\`\`shell touch ~/embark_demo/app/js/bot.js nano 1624 ~/embark_demo/app/js/bot.js \`\`\` 1625 1626 \`\`\`js status.addListener("on-message-send", function (params, 1627 context) { 1628 1629 ` var result = {` 1630 ` err: null,` 1631 ` data: null,` 1632 ` messages: []` 1633 ` };` 1634 1635 ` try {` 1636 ` result["text-message"] = "You're amazing, master!";` 1637 ` } catch (e) {` 1638 ` result.err = e;` 1639 ` }` 1640 1641 ` return result;` 1642 1643 }); \`\`\` This is pretty much the simplest responsive chatbot we can 1644 write, using only the \`addListener\` function from the API. All it's 1645 listening for is a message-send event, to which it will try to respond 1646 with the test \`You're amazing, master\!\`. 1647 1648 Obviously, there's much more we can do than simply listen for messages 1649 and send flattering responses. All will be revealed in the next 1650 tutorial. If you're feeling impatient, you can find a full Demo Bot 1651 \[here\](https://github.com/status-im/status-react/tree/34b77022f7926dbabbb0e8c5e8471eaea5ed812f/bots/demo_bot). 1652 1653 We now need to update the \`config/blockchain.json\` so it copies over 1654 our bot into a public directory (see the last line inside app 1655 object). 1656 1657 \`\`\`js 1658 1659 ` "contracts": ["app/contracts/**"],` 1660 ` "app": {` 1661 ` "css/app.css": ["app/css/**"],` 1662 ` "images/": ["app/images/**"],` 1663 ` "js/app.js": ["embark.js", "app/js/_vendor/jquery.min.js", "app/js/_vendor/bootstrap.min.js", "app/js/**"],` 1664 ` "index.html": "app/index.html",` 1665 ` "js/bot.js": "app/js/bot.js" # Add this line in #` 1666 ` },` 1667 ` "buildDir": "dist/",` 1668 1669 \`\`\` 1670 1671 That should serve the \`js\` files you need, so the last thing you'll 1672 need to do is add this bot to Status as per usual. 1673 1674 \`\`\`shell status-dev-cli add '{"whisper-identity":"embark-demo-bot", 1675 "name":"Embark-Demo-Bot", 1676 "bot-url":"<http://><MACHINE-IP>:8000/js/bot.js"}' --ip <DEVICE-IP> 1677 \`\`\` 1678 1679 Again, you could always use \`localhost\` instead if you run into 1680 issues, and just make sure to run \`adb reverse tcp:8000 tcp:8000\`. 1681 1682 {{% /tab %}} 1683 1684 {{% tab Truffle 1685 %}} 1686 1687 1. 1. Truffle 1688 1689 ``Let's see what it looks like to add the same, flattering little chatbot to Status through the Truffle Box we set up earlier. We assume here that you still have `testrpc` running from the previous tutorial and that you are still running the `npm start` script. If not, navigate back to that directory, ensure that `testrpc` is switched on and that you have opened all the right ports if you're on Android.`` 1690 1691 `> Only if you have switched off everything from the previous tutorial.` 1692 1693 \`\`\`shell testrpc -p 8546 1694 1695 status-dev-cli switch-node "<http://><MACINE-IP>:8546" --ip <DEVICE-IP> 1696 1697 cd ~/truffle-box-status 1698 1699 1. If you want to be extra sure your contracts are there, run: 1700 1701 truffle migrate --reset \`\`\` 1702 1703 So, all we need to do here is add a \`bot\` directory in Truffle's 1704 \`public\` directory (i.e. the one accessible from the web) and write 1705 some simple javascript and - hey presto\! - we'll have a decentralized 1706 chatbot. Copy the code provided into another \`bot.js\` file. The 1707 \`bot-url\` targets a \`js\` file, and this file will be loaded in the 1708 Otto VM shown in the anatomy. Code in this file сan interact with the 1709 input field, messages and react however we program it to. 1710 1711 \`\`\`shell cd ~/truffle-box-status/public/ && mkdir bot/ touch 1712 bot/bot.js nano bot/bot.js \`\`\` 1713 1714 \`\`\`js status.addListener("on-message-send", function (params, 1715 context) { 1716 1717 ` var result = {` 1718 ` err: null,` 1719 ` data: null,` 1720 ` messages: []` 1721 ` };` 1722 1723 ` try {` 1724 ` result["text-message"] = "You're amazing, master!";` 1725 ` } catch (e) {` 1726 ` result.err = e;` 1727 ` }` 1728 1729 ` return result;` 1730 1731 }); \`\`\` 1732 1733 If you look on line 42-43 of the \`npm start\` script, you'll see that 1734 we already passed in a \`bot-url\` when adding the Truffle Box in the 1735 previous tutorial. So, all we need to do now is \`status-dev-cli watch\` 1736 that same DApp to activate the live-reloading and start chatting to our 1737 bot through the chat, or interacting with our contracts through the 1738 webView. However, we need to know what to tell \`status-dev-cli\` to 1739 watch for, so let's try \`list\` our DApps currently in Status. 1740 1741 \`\`\`shell status-dev-cli list --ip <DEVICE-IP> 1742 1743 1. dapp-0x74727566666c652d626f782d737461747573 (Name: 1744 "truffle-box-status", DApp URL: "<http://><MACINE-IP>:3000") 1745 1746 \`\`\` 1747 1748 The first value returned there is the DApp's \`whisper-identity\`, which 1749 is what we need to pass to the \`watch\` command to tell it what to look 1750 for. Using it, we can now tell \`status-dev-cli\` to watch for our 1751 changes and go find that brand new bot. 1752 1753 \`\`\`shell 1754 1755 1. Make sure you're in the truflle-box-status/ directory as that is 1756 what $PWD refers to below 1757 1758 cd ~/truffle-box-status 1759 1760 1. I would use dapp-0x74727566666c652d626f782d737461747573 for 1761 <whisper-identity> below, Substitute your own one in. 1762 1763 status-dev-cli watch $PWD "<whisper-identity>" --ip <DEVICE-IP> \`\`\` 1764 1765 And you're away\! You should be able to see your DApp, browse to the 1766 same site as before, and chat with the repetitively flattering greeter 1767 bot. 1768 1769 {{% /tab %}} 1770 1771 {{% /tabs %}} 1772 1773 Once you have worked through the first tutorials and understood the 1774 basic steps to building a DApp and adding it into Status, it's time to 1775 get our hands a little more dirty by actually writing a simple, 1776 one-response chatbot that will begin to utilise the awesome power of the 1777 Status API. 1778 1779 We kind of cheated a little in the previous tutorials. While it is 1780 totally possible to have your html5 DApp work perfectly in Status via 1781 \`webView\`, it's obviously not the most optimal way to do things. There 1782 are essentailly two different ways for developers to interact with 1783 Status, best illustrated by the Status Anatomy below: 1784 1785 \!\[status-anatomy.png\](images/status-anatomy.png) 1786 1787 The main take away here is that the chat context itself is actually an 1788 Otto VM jail that executes the javascript you write, and then integrates 1789 that directly with Status. So, we can actually write bots that are 1790 purely javascript-based. Please see 1791 \[here\](https://github.com/status-im/status-react/tree/develop/bots) 1792 for a full list of all our current bots and their source code. 1793 1794 1. 1. My First Status Command 1795 1796 {{% tabs DIY Embark Truffle %}} 1797 1798 {{% tab DIY %}} 1799 1800 1. 1. Do It Yourself with \`status-dev-cli\` 1801 1802 So, we have set up Status in \`debug\` mode, added our DApp to it 1803 (hopefully run the \`status-dev-cli watch\` command to get some 1804 live-reloading going) and learned how to start a conversation with a 1805 simple javascript chatbot. Now it's time to start using the API proper 1806 and start using the provided commands to interact with our users and 1807 help them out. 1808 1809 Navigate back to your \`bots\` directory and open the \`bot.js\` file 1810 where we put the \`status.addListener\` function in the previous 1811 tutorials. We will again pass this fils in as a \`bot-url\` parameter to 1812 \`status-dev-cli\`, which will then execute the code in an Otto VM jail. 1813 1814 \`\`\`shell cd ~/my-dapp/bots/ && nano bot.js 1815 1816 1. or use 'vi bot.js' if that's your preference 1817 1818 \`\`\` 1819 1820 Then, open the file in the text editor of your choice and add in the 1821 code provided. All we want to do is provide our user with a command, 1822 called \`hello\` that they can issue into the chat and we can respond 1823 to. In order to achieve this effect, we set up a simple 1824 \`status.command()\` and pass in a name, title and description so as to 1825 identify our command and display it to the user, along with some helpful 1826 information about what it does. 1827 1828 \`\`\`js status.command({ 1829 1830 ` name: "hello",` 1831 ` title: "HelloBot",` 1832 ` description: "Helps you say hello",` 1833 ` color: "#CCCCCC",` 1834 ` preview: function (params) {` 1835 ` var text = status.components.text(` 1836 ` {` 1837 ` style: {` 1838 ` marginTop: 5,` 1839 ` marginHorizontal: 0,` 1840 ` fontSize: 14,` 1841 ` fontFamily: "font",` 1842 ` color: "black"` 1843 ` }` 1844 ` }, "Hello from the other side!");` 1845 1846 ` return {markup: status.components.view({}, [text])};` 1847 ` }` 1848 `});` 1849 1850 \`\`\` 1851 1852 We then set a color for the command to appear in set up our preview 1853 function. You can read about exactly what the preview function can 1854 achieve in the formal API specififcation but, in a nutshell, the preview 1855 defines what the user will see returned in the markup - i.e. where the 1856 messages appear. 1857 1858 Here, we are creating a simple text response by setting up a variable 1859 that we pass to \`status.components.text\`, which the perceptive will 1860 notice is a React Native component - a whole bunch more of which are 1861 available and detailed in the formal specification. Beneath the text, we 1862 are creating a standard response of "Hello from the other side\!", all 1863 of which will be returned as json to the markup. Note again the use of 1864 another React Native component - \`status.components.view\`. 1865 1866 Go ahead and serve your dapp again: 1867 1868 \`\`\`shell http-server 1869 1870 status-dev-cli list --ip <DEVICE-IP> 1871 1872 status-dev-cli watch $PWD "<whisper-identity>" --ip <DEVICE-IP> \`\`\` 1873 1874 And there you go - we are now capable of greeting and interacting with 1875 our bot in two ways\! You should be able to see your DApp, navigate to 1876 it, tap the new \`/hello\` command you see above the text input field 1877 and see your new Dapp respond. 1878 1879 {{% /tab %}} 1880 1881 {{% tab Embark %}} 1882 1883 1. 1. Embark 1884 1885 \`\`\`shell cd ~/embark_demo/app/js/bot.js && nano bot.js \`\`\` Here, 1886 we are going to create a simple text response by setting up a variable 1887 that we pass to \`status.components.text\`, which the perceptive will 1888 notice is a React Native component - a whole bunch more of which are 1889 available and detailed in the formal specification. Beneath the text, we 1890 are creating a standard response of "Hello from the other side\!", all 1891 of which will be returned as json to the markup. Note again the use of 1892 another React Native component - \`status.components.view\`. 1893 1894 \`\`\`js status.command({ 1895 1896 ` name: "hello",` 1897 ` title: "HelloBot",` 1898 ` description: "Helps you say hello",` 1899 ` color: "#CCCCCC",` 1900 ` preview: function (params) {` 1901 ` var text = status.components.text(` 1902 ` {` 1903 ` style: {` 1904 ` marginTop: 5,` 1905 ` marginHorizontal: 0,` 1906 ` fontSize: 14,` 1907 ` fontFamily: "font",` 1908 ` color: "black"` 1909 ` }` 1910 ` }, "Hello from the other side!");` 1911 1912 ` return {markup: status.components.view({}, [text])};` 1913 ` }` 1914 `});` 1915 1916 \`\`\` Go ahead and \`run\` your Embark application again and watch for 1917 changes to your new, interactive bot. We have already made sure that the 1918 \`js\` is built to, and served in, the right place, so we should just be 1919 able to list the DApps and bots currently in Status and just watch the 1920 "embark-demo-bot" we set up earlier. 1921 1922 \`\`\`shell 1923 1924 1. Only if using an Android device 1925 1926 adb reverse tcp:8000 tcp:8000 1927 1928 embark run 1929 1930 status-dev-cli list --ip <DEVICE-IP> 1931 1932 status-dev-cli watch $PWD "<whisper-identity>" --ip \`\`\` 1933 1934 And there you go - we are now capable of greeting and interacting with 1935 our bot in two ways\! You should be able to see your DApp, navigate to 1936 it, tap the new \`/hello\` command you see above the text input field 1937 and see your new Dapp respond. 1938 1939 {{% /tab %}} 1940 1941 {{% tab Truffle %}} 1942 1943 1. 1. Truffle 1944 1945 \`\`\`shell cd ~/truffle-box-status/public/bot/ && nano bot.js \`\`\` 1946 1947 Navigate back to the truffle box \`public\` directory and open the 1948 \`bot.js\` file we previously created so as to add the code provided and 1949 display it through truffle. 1950 1951 \`\`\`js status.command({ 1952 1953 ` name: "hello",` 1954 ` title: "HelloBot",` 1955 ` description: "Helps you say hello",` 1956 ` color: "#CCCCCC",` 1957 ` preview: function (params) {` 1958 ` var text = status.components.text(` 1959 ` {` 1960 ` style: {` 1961 ` marginTop: 5,` 1962 ` marginHorizontal: 0,` 1963 ` fontSize: 14,` 1964 ` fontFamily: "font",` 1965 ` color: "black"` 1966 ` }` 1967 ` }, "Hello from the other side!");` 1968 ` return {markup: status.components.view({}, [text])};` 1969 ` }` 1970 `});` 1971 1972 \`\`\` 1973 1974 Much like we did last time, just find the \`whisper-identity\` of your 1975 DApp and \`watch\` for changes. 1976 1977 \`\`\`shell status-dev-cli list --ip <DEVICE-IP> 1978 1979 1. dapp-0x74727566666c652d626f782d737461747573 (Name: 1980 "truffle-box-status", DApp URL: "<http://><MACHINE-IP>:3000") 1981 1982 <!-- end list --> 1983 1984 1. Make sure you're in the truflle-box-status/ directory as that is 1985 what $PWD refers to below 1986 1987 cd ~/truffle-box-status 1988 1989 1. I would use dapp-0x74727566666c652d626f782d737461747573 for 1990 <whisper-identity> below, Substitute your own one in. 1991 1992 status-dev-cli watch $PWD "<whisper-identity>" --ip <DEVICE-IP> \`\`\` 1993 1994 {{% /tab %}} 1995 1996 {{% /tabs %}} 1997 1998 We can now write a 1-1 chatbot that responds when users send messages to 1999 it using the \`status.addListener\` method provided by the API, but what 2000 if we want to provide our users with a command they can interact with, 2001 rather than just waiting for them to send us some kind of message, or 2002 take some other action? 2003 2004 We need to use the \`status.command()\` method. As usual, we can do this 2005 ourselves through the barebones \`status-dev-cli\`, or through the 2006 popular frameworks currently available on Ethereum. 2007 2008 1. 1. My First Interactive Suggestions Area 2009 2010 Let's go ahead and make that \`hello\` command we just created a little 2011 bit more clever. 2012 2013 \`\`\`shell cd ~/my-dapp/bots/ && nano hello.js \`\`\` Instead of the 2014 preview parameter we used last time, let's build another 2015 \`status.command()\` and add in a \`params\` option with a 2016 \`suggestions\` object in it. This will create a suggestions area which 2017 - if you refer back to the \[Chat Anatomy\](\#overview) - is what rolls 2018 up above the keyboard, such as you see when turning on the debugging 2019 server with the options \`On\` and \`Off\`. 2020 2021 \`\`\`js status.command({ 2022 2023 ` name: "greet",` 2024 ` title: "Greeter",` 2025 ` description: "Helps you choose greetings",` 2026 ` color: "#0000ff",` 2027 ` params: [{` 2028 ` name: "greet",` 2029 ` type: status.types.TEXT,` 2030 ` suggestions: helloSuggestions` 2031 ` }]` 2032 `})` 2033 2034 \`\`\` 2035 2036 "But wait\!" we hear you cry, "what on earth is that 2037 \`helloSuggestions\` thing about?\!". Well, let’s make a function to 2038 explain. This will return a \`scrollView\` with two suggestions: 2039 "Hello", and "Goodbye". Don’t get intimidated by the length, there’s 2040 actually not much to it. 2041 2042 First, we set up the helpers that will style the suggestion as it 2043 appears in the suggestions area. 2044 2045 \`\`\`js function suggestionsContainerStyle(suggestionsCount) { 2046 2047 ` return {` 2048 ` marginVertical: 1,` 2049 ` marginHorizontal: 0,` 2050 ` keyboardShouldPersistTaps: "always",` 2051 ` height: Math.min(150, (56 * suggestionsCount)),` 2052 ` backgroundColor: "white",` 2053 ` borderRadius: 5,` 2054 ` flexGrow: 1` 2055 ` };` 2056 2057 } var suggestionSubContainerStyle = { 2058 2059 ` height: 56,` 2060 ` borderBottomWidth: 1,` 2061 ` borderBottomColor: "#0000001f"` 2062 2063 }; 2064 2065 var valueStyle = { 2066 2067 ` marginTop: 9,` 2068 ` fontSize: 14,` 2069 ` fontFamily: "font",` 2070 ` color: "#000000de"` 2071 2072 }; \`\`\` 2073 2074 Now, we need to write the main star of our show - that mysterious 2075 \`helloSuggestions\` function we passed into the \`params\` of our 2076 \`status.command()\`. The objective here is to return two touchable 2077 buttons - one for \`Hello\` and the other for \`Goodbye\`. We are making 2078 quite extensive use of React native Components here, so we expect at 2079 least some level of familiarity with the framework in order to get the 2080 most out of these tutorials. 2081 2082 \`\`\`js function helloSuggestions() 2083 { 2084 2085 ` var suggestions = ["Hello", "Goodbye"].map(function(entry) {` 2086 ` return status.components.touchable(` 2087 ` {onPress: status.components.dispatch([status.events.SET_VALUE, entry])},` 2088 ` status.components.view(` 2089 ` suggestionsContainerStyle,` 2090 ` [status.components.view(` 2091 ` suggestionSubContainerStyle,` 2092 ` [` 2093 ` status.components.text(` 2094 ` {style: valueStyle},` 2095 ` entry` 2096 ` )` 2097 ` ]` 2098 ` )]` 2099 ` )` 2100 ` );` 2101 ` });` 2102 2103 ` // Let's wrap those two touchable buttons in a scrollView` 2104 ` var view = status.components.scrollView(` 2105 ` suggestionsContainerStyle(2),` 2106 ` suggestions` 2107 ` );` 2108 2109 ` // Give back the whole thing inside an object.` 2110 ` return {markup: view};` 2111 2112 } \`\`\` 2113 2114 The main point of this example is that your \`suggestions\` parameter 2115 should accept users’ input, and then return a component to be rendered. 2116 2117 We have already added this contact to Status, so let's se if we can set 2118 up our environment to do some live reloading so that we don't have to 2119 revert to the cli every time we want to change something in the process 2120 of building all the new things. 2121 2122 \`\`\`shell http-server 2123 2124 status-dev-cli watch $PWD "<whisper-identity>" --ip <DEVICE-IP> \`\`\` 2125 2126 You can also work with the \`suggestionsTrigger\` parameter. Now that 2127 we’ve covered \`params\` and the possibility of \`suggestions\`, it’s 2128 easy to see that \`suggestionsTrigger\` will take a string corresponding 2129 to an event that, when triggered, will show all your \`suggestions\`. If 2130 you don’t include this parameter, the default is "on-change", so your 2131 suggestions will show when your users selects the command. 2132 2133 It's also worth knowing about the \`fullscreen\` option. If your command 2134 has \`suggestions\`, this \`param\` controls whether that list of 2135 suggestions expands to fill the entire screen. If your command has a lot 2136 of suggestions, you might want to set \`fullscreen\` to \`true\`, so 2137 that your users don’t have to pull the list upwards. On the other hand, 2138 if your command has only a few suggestions and you set \`fullscreen\` to 2139 \`true\`, your users will have to pull the list downwards to keep it 2140 from hiding the screen. Choose whichever will be most convenient to your 2141 users, considering your command’s suggestions. 2142 2143 OK, so we can build up a basic command, show it to the user and have it 2144 do something (like return text) when the user taps it. That's great, but 2145 what happens if we want to be a bit more dynamic and interactive and 2146 suggest to our users a range of options to choose from when issuing the 2147 command? Let's take a look... 2148 2149 For another full example of an interactive suggestion area, please take 2150 a look over our \[Demo 2151 Bot\](https://github.com/status-im/status-react/blob/develop/bots/demo_bot/bot.js), 2152 which makes prominent use of the \`defineSubscription\` method from the 2153 API and may be helpful for those looking to work with things like the 2154 \`status.component.slider\` React Native Component. 2155 2156 You could also build a location bot following a similar pattern. We 2157 provide the code for you, just because we can. See if you can get it all 2158 working right this time... 2159 2160 \`\`\`js I18n.translations = 2161 { 2162 2163 ` en: {` 2164 ` location_title: 'Location',` 2165 ` location_suggestions_title: 'Send location',` 2166 ` location_description: 'Share your location',` 2167 ` location_address: 'address'` 2168 2169 }} 2170 2171 status.command({ 2172 2173 ` name: "location",` 2174 ` title: I18n.t('location_title'),` 2175 ` description: I18n.t('location_description')` 2176 ` hideSendButton: true,` 2177 ` sequentialParams: true,` 2178 ` params: [{` 2179 ` name: "address",` 2180 ` type: status.types.TEXT,` 2181 ` placeholder: I18n.t('location_address')` 2182 ` }]` 2183 `})` 2184 ` ``` ` 2185 2186 `Or, even better, can you get some location suggestions to display?` 2187 2188 ` ```js` 2189 `function locationsSuggestions (params) {` 2190 ` var result = {title: "Send location"};` 2191 ` var seqArg = params.seqArg ? params.seqArg : "";` 2192 2193 ` if (seqArg == "Dropped pin")` 2194 ` {` 2195 ` result.markup = ["view", {}, ["text", {}, "Dropped pin" + seqArg]];` 2196 ` }` 2197 ` else if (seqArg != "")` 2198 ` {` 2199 ` result.markup = ["view", {}, ["text", {}, "Let's try to find something " + seqArg]];` 2200 ` }` 2201 ` else` 2202 ` {` 2203 ` result.markup = ['current-location', {showMap: true}];` 2204 ` }` 2205 2206 ` return result;` 2207 2208 } \`\`\` 2209 2210 1. 1. Frequently Asked Questions (FAQ) 2211 2212 <!-- end list --> 2213 2214 1. 1. My bot has been deployed but it does not appear to work. 2215 2216 Make sure that the \`bot-url\` you provided when adding your bot is 2217 accessible from your device. For example, open it in mobile browser. 2218 2219 1. 1. Is there a way to debug my bot? 2220 2221 \`status-dev-cli log\` allows to access outputs from \`console.log()\`. 2222 So, just add in the necessary \`console.log()\`s and read them in your 2223 terminal. The team is working actively to make this easier. 2224 2225 1. 1. Can I connect to a different RPC server? 2226 2227 \`status-dev-cli switch-node\` only works for \`dapp-url\`s at the 2228 moment. Due to the restrictions of the Otto VM jail that the bots \`js\` 2229 is run in, it still connects by default to Ropsten and your Status 2230 account. The team is actively working on ways around this. 2231 2232 1. 1. Can custom commands be added to normal chat? 2233 2234 Currently they are only available to 1-1 chat with bots. At some stage 2235 in the future we will implement group chats and all your dreams will 2236 come true. 2237 2238 1. 1. Status API FAQs 2239 2240 <!-- end list --> 2241 2242 1. 1. How can I set the text input value? 2243 2244 You can use \`status.components.dispatch\` in tandem with the 2245 \`SET_VALUE\` object. For instance, if you wanted to sugeest a url, you 2246 would do the following: 2247 \`status.components.dispatch(\[status.events.SET_VALUE, "@browse 2248 url"\])}\`. A more complete example is also given alongside. 2249 2250 \`\`\`javascript return {markup: 2251 status.components.touchable( 2252 2253 ` {onPress: status.components.dispatch([status.events.SET_VALUE, "@browse url"])},` 2254 ` status.components.view( {},` 2255 ` status.components.text(` 2256 ` {},` 2257 ` "Click me"` 2258 ` )` 2259 ` )` 2260 ` )};` 2261 2262 \`\`\` 2263 2264 1. 1. How can I send a command a display result back? 2265 2266 Here we use the \`onSend\` function to direct a user to a website based 2267 on their initial input. 2268 2269 \`\`\`javascript 2270 status.command({ 2271 2272 ` name: "google_or_yahoo",` 2273 ` title: 'TITLE',` 2274 ` description: 'DESCRIPTION',` 2275 ` fullscreen: true,` 2276 ` params: [{` 2277 ` name: "option",` 2278 ` type: status.types.TEXT,` 2279 ` placeholder: "either type G or Y"` 2280 ` }],` 2281 ` onSend: function(params){` 2282 ` console.log('***', params);` 2283 ` if (params.option == 'g') {` 2284 ` url = '`<http://www.google.com>`'` 2285 ` }else{` 2286 ` url = '`<http://www.yahoo.com>`'` 2287 ` }` 2288 ` return {` 2289 ` title: "Browser",` 2290 ` dynamicTitle: true,` 2291 ` singleLineInput: true,` 2292 ` actions: [ { type: status.actions.FULLSCREEN } ],` 2293 ` markup: status.components.bridgedWebView("`<http://google.com/>`")` 2294 ` };` 2295 ` }` 2296 2297 }); \`\`\` 2298 2299 1. 1. Can I send a message asynchrounously after a request has been 2300 sent? 2301 2302 Use the latest nightlies and \`status.sendMessage\` will now be 2303 available. 2304 2305 \`\`\`javascript 2306 2307 `status.command({` 2308 ` name: "test",` 2309 ` icon: "test",` 2310 ` title: "test",` 2311 ` description: "test",` 2312 ` color: "#a187d5",` 2313 ` sequentialParams: true,` 2314 ` params: [{` 2315 ` name: "address",` 2316 ` type: status.types.TEXT,` 2317 ` placeholder: "address"` 2318 ` }],` 2319 ` handler: function (params) {` 2320 ` status.sendMessage("Address " + params.address);` 2321 ` }` 2322 2323 }); \`\`\` 2324 2325 1. 1. How can I add an image to my reactive component? 2326 2327 It's easy enough to achieve this by using \`status.components.image\`. 2328 2329 \`\`\`js status.components.image({style: {width: 50, height: 50}, 2330 source: {uri: '<https://facebook.github.io/react/img/logo_og.png>'}}), 2331 \`\`\` 2332 2333 1. 1. JS and web3 API FAQ 2334 2335 <!-- end list --> 2336 2337 1. 1. How can data be stored and retrieved? 2338 2339 Yes it can be, using \`localStorage\`. 2340 2341 \`\`\`js status.addListener("on-message-send", function (params, 2342 context) 2343 { 2344 2345 ` var cnt = localStorage.getItem("cnt");` 2346 ` if(!cnt) {` 2347 ` cnt = 0;` 2348 ` }` 2349 2350 ` cnt++;` 2351 2352 ` localStorage.setItem("cnt", cnt);` 2353 ` if (isNaN(params.message)) {` 2354 ` return {"text-message": "Seems that you don't want to send money :(. cnt = " + cnt};` 2355 ` }` 2356 2357 ` var balance = web3.eth.getBalance(context.from);` 2358 ` var value = parseFloat(params.message);` 2359 ` var weiValue = web3.toWei(value, "ether");` 2360 ` if (bn(weiValue).greaterThan(bn(balance))) {` 2361 ` return {"text-message": "No way man, you don't have enough money! :)"};` 2362 ` }` 2363 ` web3.eth.sendTransaction({` 2364 ` from: context.from,` 2365 ` to: context.from,` 2366 ` value: weiValue` 2367 ` }, function (error, hash) {` 2368 ` if (error) {` 2369 ` status.sendMessage("Something went wrong, try again :(");` 2370 ` status.showSuggestions(demoSuggestions(params, context).markup);` 2371 ` } else {` 2372 ` status.sendMessage("You are the hero, you sent " + value + " ETH to yourself!")` 2373 ` }` 2374 ` });` 2375 2376 }); \`\`\` 2377 2378 1. 1. Can I interract with \`web3\` object? 2379 2380 Yes\! The snippet provided showcases both \`localStrage\` and the 2381 \`web3\` object operating in tandem. 2382 2383 1. 1. Can I parse JSON data? 2384 2385 Yes JSON.parse()is supported. 2386 2387 1. 1. Is XMLHttpRequest supported? 2388 2389 Not yet. 2390 2391 1. 1. Any examples 2392 ? 2393 2394 <!-- end list --> 2395 2396 - <https://github.com/status-im/status-react/blob/develop/bots/demo_bot/bot.js> 2397 - <https://github.com/status-im/status-react/blob/develop/bots/console/bot.js> 2398 2399 \--- weight: 40 title: Web3 API Reference --- 2400 2401 1. web3 (API) 2402 2403 To make your Ðapp work on Ethereum, you can use the \`web3\` object 2404 provided by the \[web3.js 2405 library\](https://github.com/ethereum/web3.js). Under the hood it 2406 communicates to a local node through \[RPC 2407 calls\](https://github.com/ethereum/wiki/wiki/JSON-RPC). web3.js works 2408 with any Ethereum node, which exposes an RPC layer. 2409 2410 \`web3\` contains the \`eth\` object - \`web3.eth\` (for specifically 2411 Ethereum blockchain interactions) and the \`shh\` object - \`web3.shh\` 2412 (for Whisper interaction). Over time we'll introduce other objects for 2413 each of the other web3 protocols. Working \[examples can be found 2414 here\](https://github.com/ethereum/web3.js/tree/master/example). 2415 2416 If you want to look at some more sophisticated examples using web3.js 2417 check out these \[useful Ðapp 2418 patterns\](https://github.com/ethereum/wiki/wiki/Useful-Ðapp-Patterns). 2419 2420 1. 1. Getting Started 2421 2422 <aside class="notice"> 2423 2424 Status already provides the `web3` object in both HTML5 DApps and 2425 Chatbots, so you can safely skip this step. 2426 2427 </aside> 2428 2429 TODO check how metamask suggests to embed 2430 2431 \`\`\`js if (typeof web3 \!== 'undefined') { 2432 2433 ` web3 = new Web3(web3.currentProvider);` 2434 2435 } else 2436 { 2437 2438 ` // set the provider you want from Web3.providers` 2439 ` web3 = new Web3(new Web3.providers.HttpProvider("`<http://localhost:8545>`"));` 2440 2441 } \`\`\` 2442 2443 First you need to get web3.js into your project. This can be done using 2444 the following methods: 2445 2446 \- npm: \`npm install web3\` - bower: \`bower install web3\` - meteor: 2447 \`meteor add ethereum:web3\` - vanilla: link the \`dist./web3.min.js\` 2448 2449 Then you need to create a web3 instance, setting a provider. To make 2450 sure you don't overwrite the already set provider when in mist, check 2451 first if the web3 is available: 2452 2453 After that you can use the API of the \`web3\` object. 2454 2455 1. 1. Using callbacks 2456 2457 \`\`\`js web3.eth.getBlock(48, function(error, result){ 2458 2459 ` if(!error)` 2460 ` console.log(result)` 2461 ` else` 2462 ` console.error(error);` 2463 2464 }) \`\`\` 2465 2466 As this API is designed to work with a local RPC node, all its functions 2467 use synchronous HTTP requests by default. 2468 2469 If you want to make an asynchronous request, you can pass an optional 2470 callback as the last parameter to most functions. All callbacks are 2471 using an \[error first 2472 callback\](http://fredkschott.com/post/2014/03/understanding-error-first-callbacks-in-node-js/) 2473 style: 2474 2475 1. 1. Batch requests 2476 2477 \`\`\`js var batch = web3.createBatch(); 2478 batch.add(web3.eth.getBalance.request('0x0000000000000000000000000000000000000000', 2479 'latest', callback)); 2480 batch.add(web3.eth.contract(abi).at(address).balance.request(address, 2481 callback2)); batch.execute(); \`\`\` 2482 2483 Batch requests allow queuing up requests and processing them at once. 2484 2485 - - Note\*\* Batch requests are not faster\! In fact making many 2486 requests at once will in some cases be faster, as requests are 2487 processed asynchronous. Batch requests are mainly useful to 2488 ensure the serial processing of requests. 2489 2490 <!-- end list --> 2491 2492 1. 1. web3 & BigNumber 2493 2494 \`\`\`js "101010100324325345346456456456456456456" // 2495 "101010100324325345346456456456456456456" 2496 101010100324325345346456456456456456456 // 1.0101010032432535e+38 \`\`\` 2497 2498 You will always get a BigNumber object for number values as JavaScript 2499 is not able to handle big numbers correctly. Look at the following 2500 examples: 2501 2502 web3.js depends on the \[BigNumber 2503 Library\](https://github.com/MikeMcl/bignumber.js/) and adds it 2504 automatically. 2505 2506 \`\`\`js var balance = new 2507 BigNumber('131242344353464564564574574567456'); // or var balance = 2508 web3.eth.getBalance(someAddress); 2509 2510 // toString(10) converts it to a number string 2511 balance.plus(21).toString(10); // "131242344353464564564574574567477" 2512 \`\`\` 2513 2514 The next example wouldn't work as we have more than 20 floating points, 2515 therefore it is recommended to keep you balance always in \*wei\* and 2516 only transform it to other units when presenting to the user: \`\`\`js 2517 var balance = new BigNumber('13124.234435346456466666457455567456'); 2518 2519 // toString(10) converts it to a number string, but can only show max 20 2520 floating points balance.plus(21).toString(10); // 2521 "13145.23443534645646666646" // you number would be cut after the 20 2522 floating point \`\`\` 2523 2524 1. 1. web3 2525 2526 <!-- end list --> 2527 2528 1. 1. web3.version.api 2529 2530 <!-- end list --> 2531 2532 1. 1. Returns 2533 2534 \`String\` - The ethereum js api version. 2535 2536 \`\`\`js var version = web3.version.api; console.log(version); // 2537 "0.2.0" \`\`\` 2538 2539 1. 1. web3.version.node 2540 2541 ` web3.version.node` 2542 ` // or async` 2543 ` web3.version.getNode(callback(error, result){ ... })` 2544 2545 1. 1. Returns 2546 2547 \`String\` - The client/node version. 2548 2549 \`\`\`js var version = web3.version.node; console.log(version); // 2550 "Mist/v0.9.3/darwin/go1.4.1" \`\`\` 2551 2552 1. 1. web3.version.network 2553 2554 ` web3.version.network` 2555 ` // or async` 2556 ` web3.version.getNetwork(callback(error, result){ ... })` 2557 2558 1. 1. Returns 2559 2560 \`String\` - The network protocol version. 2561 2562 \`\`\`js var version = web3.version.network; console.log(version); // 54 2563 \`\`\` 2564 2565 1. 1. web3.version.ethereum 2566 2567 ` web3.version.ethereum` 2568 ` // or async` 2569 ` web3.version.getEthereum(callback(error, result){ ... })` 2570 2571 1. 1. Returns 2572 2573 \`String\` - The ethereum protocol version. 2574 2575 \`\`\`js var version = web3.version.ethereum; console.log(version); // 2576 60 \`\`\` 2577 2578 1. 1. web3.version.whisper 2579 2580 ` web3.version.whisper` 2581 ` // or async` 2582 ` web3.version.getWhisper(callback(error, result){ ... })` 2583 2584 1. 1. Returns 2585 2586 \`String\` - The whisper protocol version. 2587 2588 \`\`\`js var version = web3.version.whisper; console.log(version); // 20 2589 \`\`\` 2590 2591 - - 2592 <!-- end list --> 2593 2594 1. 1. web3.isConnected 2595 2596 ` web3.isConnected()` 2597 2598 Should be called to check if a connection to a node exists 2599 2600 1. 1. Parameters 2601 2602 none 2603 2604 1. 1. Returns 2605 2606 \`Boolean\` 2607 2608 \`\`\`js if(\!web3.isConnected()) { 2609 2610 ` // show some dialog to ask the user to start a node` 2611 2612 } else { 2613 2614 ` // start web3 filters, calls, etc` 2615 ` ` 2616 2617 } \`\`\` 2618 2619 1. 1. web3.setProvider 2620 2621 ` web3.setProvider(provider)` 2622 2623 Should be called to set provider. 2624 2625 1. 1. Parameters 2626 2627 none 2628 2629 1. 1. Returns 2630 2631 \`undefined\` 2632 2633 \`\`\`js web3.setProvider(new 2634 web3.providers.HttpProvider('<http://localhost:8545>')); // 8080 for 2635 cpp/AZ, 8545 for go/mist \`\`\` 2636 2637 1. 1. web3.currentProvider 2638 2639 ` web3.currentProvider` 2640 2641 Will contain the current provider, if one is set. This can be used to 2642 check if mist etc. set already a provider. 2643 2644 1. 1. Returns 2645 2646 \`Object\` - The provider set or \`null\`; 2647 2648 \`\`\`js // Check if mist etc. already set a provider 2649 if(\!web3.currentProvider) 2650 2651 ` web3.setProvider(new web3.providers.HttpProvider("`<http://localhost:8545>`"));` 2652 2653 \`\`\` 2654 2655 1. 1. web3.reset 2656 2657 ` web3.reset(keepIsSyncing)` 2658 2659 Should be called to reset state of web3. Resets everything except 2660 manager. Uninstalls all filters. Stops polling. 2661 2662 1. 1. Parameters 2663 2664 1\. \`Boolean\` - If \`true\` it will uninstall all filters, but will 2665 keep the \[web3.eth.isSyncing()\](\#web3ethissyncing) polls 2666 2667 1. 1. Returns 2668 2669 \`undefined\` 2670 2671 \`\`\`js web3.reset(); \`\`\` 2672 2673 1. 1. web3.sha3 2674 2675 ` web3.sha3(string, options)` 2676 2677 1. 1. Parameters 2678 2679 1\. \`String\` - The string to hash using the Keccak-256 SHA3 algorithm 2680 1. \`Object\` - Set \`encoding\` to \`hex\` if the string to hash is 2681 encoded in hex. A leading \`0x\` will be automatically ignored. 2682 2683 1. 1. Returns 2684 2685 \`String\` - The Keccak-256 SHA3 of the given data. 2686 2687 \`\`\`js var hash = web3.sha3("Some string to be hashed"); 2688 console.log(hash); // 2689 "0xed973b234cf2238052c9ac87072c71bcf33abc1bbd721018e0cca448ef79b379" 2690 2691 var hashOfHash = web3.sha3(hash, {encoding: 'hex'}); 2692 console.log(hashOfHash); // 2693 "0x85dd39c91a64167ba20732b228251e67caed1462d4bcf036af88dc6856d0fdcc" 2694 \`\`\` 2695 2696 1. 1. web3.toHex 2697 2698 ` web3.toHex(mixed);` 2699 2700 Converts any value into HEX. 2701 2702 1. 1. Parameters 2703 2704 1\. \`String|Number|Object|Array|BigNumber\` - The value to parse to 2705 HEX. If its an object or array it will be \`JSON.stringify\` first. If 2706 its a BigNumber it will make it the HEX value of a number. 2707 2708 1. 1. Returns 2709 2710 \`String\` - The hex string of \`mixed\`. 2711 2712 \`\`\`js var str = web3.toHex({test: 'test'}); console.log(str); // 2713 '0x7b2274657374223a2274657374227d' \`\`\` 2714 2715 1. 1. web3.toAscii 2716 2717 ` web3.toAscii(hexString);` 2718 2719 Converts a HEX string into a ASCII string. 2720 2721 1. 1. Parameters 2722 2723 1\. \`String\` - A HEX string to be converted to ascii. 2724 2725 1. 1. Returns 2726 2727 \`String\` - An ASCII string made from the given \`hexString\`. 2728 2729 \`\`\`js var str = 2730 web3.toAscii("0x657468657265756d000000000000000000000000000000000000000000000000"); 2731 console.log(str); // "ethereum" \`\`\` 2732 2733 1. 1. web3.fromAscii 2734 2735 ` web3.fromAscii(string [, padding]);` 2736 2737 Converts any ASCII string to a HEX string. 2738 2739 1. 1. Parameters 2740 2741 1\. \`String\` - An ASCII string to be converted to HEX. 2. \`Number\` - 2742 The number of bytes the returned HEX string should have. 2743 2744 1. 1. Returns 2745 2746 \`String\` - The converted HEX string. 2747 2748 \`\`\`js var str = web3.fromAscii('ethereum'); console.log(str); // 2749 "0x657468657265756d" 2750 2751 var str2 = web3.fromAscii('ethereum', 32); console.log(str2); // 2752 "0x657468657265756d000000000000000000000000000000000000000000000000" 2753 \`\`\` 2754 2755 1. 1. web3.toDecimal 2756 2757 ` web3.toDecimal(hexString);` 2758 2759 Converts a HEX string to its number representation. 2760 2761 1. 1. Parameters 2762 2763 1\. \`String\` - An HEX string to be converted to a number. 2764 2765 1. 1. Returns 2766 2767 \`Number\` - The number representing the data \`hexString\`. 2768 2769 \`\`\`js var number = web3.toDecimal('0x15'); console.log(number); // 21 2770 \`\`\` 2771 2772 1. 1. web3.fromDecimal 2773 2774 ` web3.fromDecimal(number);` 2775 2776 Converts a number or number string to its HEX representation. 2777 2778 1. 1. Parameters 2779 2780 1\. \`Number|String\` - A number to be converted to a HEX string. 2781 2782 1. 1. Returns 2783 2784 \`String\` - The HEX string representing of the given \`number\`. 2785 2786 \`\`\`js var value = web3.fromDecimal('21'); console.log(value); // 2787 "0x15" \`\`\` 2788 2789 1. 1. web3.fromWei 2790 2791 ` web3.fromWei(number, unit)` 2792 2793 Converts a number of wei into the following ethereum units: 2794 2795 \- \`kwei\`/\`ada\` - \`mwei\`/\`babbage\` - \`gwei\`/\`shannon\` - 2796 \`szabo\` - \`finney\` - \`ether\` - \`kether\`/\`grand\`/\`einstein\` - 2797 \`mether\` - \`gether\` - \`tether\` 2798 2799 1. 1. Parameters 2800 2801 1\. \`Number|String|BigNumber\` - A number or BigNumber instance. 2. 2802 \`String\` - One of the above ether units. 2803 2804 1. 1. Returns 2805 2806 \`String|BigNumber\` - Either a number string, or a BigNumber instance, 2807 depending on the given \`number\` parameter. 2808 2809 \`\`\`js var value = web3.fromWei('21000000000000', 'finney'); 2810 console.log(value); // "0.021" \`\`\` 2811 2812 1. 1. web3.toWei 2813 2814 ` web3.toWei(number, unit)` 2815 2816 Converts an ethereum unit into wei. Possible units are: 2817 2818 \- \`kwei\`/\`ada\` - \`mwei\`/\`babbage\` - \`gwei\`/\`shannon\` - 2819 \`szabo\` - \`finney\` - \`ether\` - \`kether\`/\`grand\`/\`einstein\` - 2820 \`mether\` - \`gether\` - \`tether\` 2821 2822 1. 1. Parameters 2823 2824 1\. \`Number|String|BigNumber\` - A number or BigNumber instance. 2. 2825 \`String\` - One of the above ether units. 2826 2827 1. 1. Returns 2828 2829 \`String|BigNumber\` - Either a number string, or a BigNumber instance, 2830 depending on the given \`number\` parameter. 2831 2832 \`\`\`js var value = web3.toWei('1', 'ether'); console.log(value); // 2833 "1000000000000000000" \`\`\` 2834 2835 1. 1. web3.toBigNumber 2836 2837 ` web3.toBigNumber(numberOrHexString);` 2838 2839 Converts a given number into a BigNumber instance. 2840 2841 See the \[note on BigNumber\](\#a-note-on-big-numbers-in-web3js). 2842 2843 1. 1. Parameters 2844 2845 1\. \`Number|String\` - A number, number string or HEX string of a 2846 number. 2847 2848 1. 1. Returns 2849 2850 \`BigNumber\` - A BigNumber instance representing the given value. 2851 2852 \`\`\`js var value = web3.toBigNumber('200000000000000000000001'); 2853 console.log(value); // instanceOf BigNumber 2854 console.log(value.toNumber()); // 2.0000000000000002e+23 2855 console.log(value.toString(10)); // '200000000000000000000001' \`\`\` 2856 2857 - - 2858 <!-- end list --> 2859 2860 1. 1. web3.net 2861 2862 <!-- end list --> 2863 2864 1. 1. web3.net.listening 2865 2866 ` web3.net.listening` 2867 ` // or async` 2868 ` web3.net.getListening(callback(error, result){ ... })` 2869 2870 This property is read only and says whether the node is actively 2871 listening for network connections or not. 2872 2873 1. 1. Returns 2874 2875 \`Boolean\` - \`true\` if the client is actively listening for network 2876 connections, otherwise \`false\`. 2877 2878 \`\`\`js var listening = web3.net.listening; console.log(listening); // 2879 true of false \`\`\` 2880 2881 1. 1. web3.net.peerCount 2882 2883 ` web3.net.peerCount` 2884 ` // or async` 2885 ` web3.net.getPeerCount(callback(error, result){ ... })` 2886 2887 This property is read only and returns the number of connected peers. 2888 2889 1. 1. Returns 2890 2891 \`Number\` - The number of peers currently connected to the client. 2892 2893 \`\`\`js var peerCount = web3.net.peerCount; console.log(peerCount); // 2894 4 \`\`\` 2895 2896 - - 2897 <!-- end list --> 2898 2899 1. 1. web3.eth 2900 2901 Contains the ethereum blockchain related methods. 2902 2903 \`\`\`js var eth = web3.eth; \`\`\` 2904 2905 1. 1. web3.eth.defaultAccount 2906 2907 ` web3.eth.defaultAccount` 2908 2909 This default address is used for the following methods (optionally you 2910 can overwrite it by specifying the \`from\` property): 2911 2912 \- \[web3.eth.sendTransaction()\](\#web3ethsendtransaction) - 2913 \[web3.eth.call()\](\#web3ethcall) 2914 2915 1. 1. Values 2916 2917 \`String\`, 20 Bytes - Any address you own, or where you have the 2918 private key for. 2919 2920 - Default is\* \`undefined\`. 2921 2922 <!-- end list --> 2923 2924 1. 1. Returns 2925 2926 \`String\`, 20 Bytes - The currently set default address. 2927 2928 \`\`\`js var defaultAccount = web3.eth.defaultAccount; 2929 console.log(defaultAccount); // '' 2930 2931 // set the default account web3.eth.defaultAccount = 2932 '0x8888f1f195afa192cfee860698584c030f4c9db1'; \`\`\` 2933 2934 1. 1. web3.eth.defaultBlock 2935 2936 ` web3.eth.defaultBlock` 2937 2938 This default block is used for the following methods (optionally you can 2939 override it by passing the defaultBlock parameter): 2940 2941 \- \[web3.eth.getBalance()\](\#web3ethgetbalance) - 2942 \[web3.eth.getCode()\](\#web3ethgetcode) - 2943 \[web3.eth.getTransactionCount()\](\#web3ethgettransactioncount) - 2944 \[web3.eth.getStorageAt()\](\#web3ethgetstorageat) - 2945 \[web3.eth.call()\](\#web3ethcall) - 2946 \[contract.myMethod.call()\](\#contract-methods) - 2947 \[contract.myMethod.estimateGas()\](\#contract-methods) 2948 2949 1. 1. Values 2950 2951 Default block parameters can be one of the following: 2952 2953 \- \`Number\` - a block number - \`String\` - \`"earliest"\`, the 2954 genisis block - \`String\` - \`"latest"\`, the latest block (current 2955 head of the blockchain) - \`String\` - \`"pending"\`, the currently 2956 mined block (including pending transactions) 2957 2958 - Default is\* \`latest\` 2959 2960 <!-- end list --> 2961 2962 1. 1. Returns 2963 2964 \`Number|String\` - The default block number to use when querying a 2965 state. 2966 2967 \`\`\`js var defaultBlock = web3.eth.defaultBlock; 2968 console.log(defaultBlock); // 'latest' 2969 2970 // set the default block web3.eth.defaultBlock = 231; \`\`\` 2971 2972 1. 1. web3.eth.syncing 2973 2974 ` web3.eth.syncing` 2975 ` // or async` 2976 ` web3.eth.getSyncing(callback(error, result){ ... })` 2977 2978 This property is read only and returns the either a sync object, when 2979 the node is syncing or \`false\`. 2980 2981 1. 1. Returns 2982 2983 \`Object|Boolean\` - A sync object as follows, when the node is 2984 currently syncing or 2985 \`false\`: 2986 2987 `` - `startingBlock`: `Number` - The block number where the sync started.`` 2988 `` - `currentBlock`: `Number` - The block number where at which block the node currently synced to already.`` 2989 `` - `highestBlock`: `Number` - The estimated block number to sync to.`` 2990 2991 \`\`\`js var sync = web3.eth.syncing; console.log(sync); /\* { 2992 2993 ` startingBlock: 300,` 2994 ` currentBlock: 312,` 2995 ` highestBlock: 512` 2996 2997 } 2998 2999 - / 3000 3001 \`\`\` 3002 3003 1. 1. web3.eth.isSyncing 3004 3005 ` web3.eth.isSyncing(callback);` 3006 3007 This convenience function calls the \`callback\` everytime a sync 3008 starts, updates and stops. 3009 3010 1. 1. Returns 3011 3012 \`Object\` - a isSyncing object with the following 3013 methods: 3014 3015 `` * `syncing.addCallback()`: Adds another callback, which will be called when the node starts or stops syncing.`` 3016 `` * `syncing.stopWatching()`: Stops the syncing callbacks.`` 3017 3018 1. 1. Callback return value 3019 3020 \- \`Boolean\` - The callback will be fired with \`true\` when the 3021 syncing starts and with \`false\` when it stopped. - \`Object\` - While 3022 syncing it will return the syncing 3023 object: 3024 3025 `` - `startingBlock`: `Number` - The block number where the sync started.`` 3026 `` - `currentBlock`: `Number` - The block number where at which block the node currently synced to already.`` 3027 `` - `highestBlock`: `Number` - The estimated block number to sync to.`` 3028 3029 \`\`\`js web3.eth.isSyncing(function(error, 3030 sync){ 3031 3032 ` if(!error) {` 3033 ` // stop all app activity` 3034 ` if(sync === true) {` 3035 `` // we use `true`, so it stops all filters, but not the web3.eth.syncing polling`` 3036 ` web3.reset(true);` 3037 ` ` 3038 ` // show sync info` 3039 ` } else if(sync) {` 3040 ` console.log(sync.currentBlock);` 3041 ` ` 3042 ` // re-gain app operation` 3043 ` } else {` 3044 ` // run your app init function...` 3045 ` }` 3046 ` }` 3047 3048 }); \`\`\` 3049 3050 1. 1. web3.eth.coinbase 3051 3052 ` web3.eth.coinbase` 3053 ` // or async` 3054 ` web3.eth.getCoinbase(callback(error, result){ ... })` 3055 3056 This property is read only and returns the coinbase address were the 3057 mining rewards go to. 3058 3059 1. 1. Returns 3060 3061 \`String\` - The coinbase address of the client. 3062 3063 \`\`\`js var coinbase = web3.eth.coinbase; console.log(coinbase); // 3064 "0x407d73d8a49eeb85d32cf465507dd71d507100c1" \`\`\` 3065 3066 1. 1. web3.eth.mining 3067 3068 ` web3.eth.mining` 3069 ` // or async` 3070 ` web3.eth.getMining(callback(error, result){ ... })` 3071 3072 This property is read only and says whether the node is mining or not. 3073 3074 1. 1. Returns 3075 3076 \`Boolean\` - \`true\` if the client is mining, otherwise \`false\`. 3077 3078 \`\`\`js var mining = web3.eth.mining; console.log(mining); // true or 3079 false \`\`\` 3080 3081 1. 1. web3.eth.hashrate 3082 3083 ` web3.eth.hashrate` 3084 ` // or async` 3085 ` web3.eth.getHashrate(callback(error, result){ ... })` 3086 3087 This property is read only and returns the number of hashes per second 3088 that the node is mining with. 3089 3090 1. 1. Returns 3091 3092 \`Number\` - number of hashes per second. 3093 3094 \`\`\`js var hashrate = web3.eth.hashrate; console.log(hashrate); // 3095 493736 \`\`\` 3096 3097 1. 1. web3.eth.gasPrice 3098 3099 ` web3.eth.gasPrice` 3100 ` // or async` 3101 ` web3.eth.getGasPrice(callback(error, result){ ... })` 3102 3103 This property is read only and returns the current gas price. The gas 3104 price is determined by the x latest blocks median gas price. 3105 3106 1. 1. Returns 3107 3108 \`BigNumber\` - A BigNumber instance of the current gas price in wei. 3109 3110 See the \[note on BigNumber\](\#a-note-on-big-numbers-in-javascript). 3111 3112 \`\`\`js var gasPrice = web3.eth.gasPrice; 3113 console.log(gasPrice.toString(10)); // "10000000000000" \`\`\` 3114 3115 1. 1. web3.eth.accounts 3116 3117 ` web3.eth.accounts` 3118 ` // or async` 3119 ` web3.eth.getAccounts(callback(error, result){ ... })` 3120 3121 This property is read only and returns a list of accounts the node 3122 controls. 3123 3124 1. 1. Returns 3125 3126 \`Array\` - An array of addresses controlled by client. 3127 3128 \`\`\`js var accounts = web3.eth.accounts; console.log(accounts); // 3129 \["0x407d73d8a49eeb85d32cf465507dd71d507100c1"\] \`\`\` 3130 3131 1. 1. web3.eth.blockNumber 3132 3133 ` web3.eth.blockNumber` 3134 ` // or async` 3135 ` web3.eth.getBlockNumber(callback(error, result){ ... })` 3136 3137 This property is read only and returns the current block number. 3138 3139 1. 1. Returns 3140 3141 \`Number\` - The number of the most recent block. 3142 3143 \`\`\`js var number = web3.eth.blockNumber; console.log(number); // 2744 3144 \`\`\` 3145 3146 1. 1. web3.eth.register 3147 3148 ` web3.eth.register(addressHexString [, callback])` 3149 3150 (Not Implemented yet) Registers the given address to be included in 3151 \`web3.eth.accounts\`. This allows non-private-key owned accounts to be 3152 associated as an owned account (e.g., contract wallets). 3153 3154 1. 1. Parameters 3155 3156 1\. \`String\` - The address to register 2. \`Function\` - (optional) If 3157 you pass a callback the HTTP request is made asynchronous. See \[this 3158 note\](\#using-callbacks) for details. 3159 3160 1. 1. Returns 3161 3162 ? 3163 3164 \`\`\`js web3.eth.register("0x407d73d8a49eeb85d32cf465507dd71d507100ca") 3165 \`\`\` 3166 3167 1. 1. web3.eth.unRegister 3168 3169 ` web3.eth.unRegister(addressHexString [, callback])` 3170 3171 (Not Implemented yet) Unregisters a given address. 3172 3173 1. 1. Parameters 3174 3175 1\. \`String\` - The address to unregister. 2. \`Function\` - (optional) 3176 If you pass a callback the HTTP request is made asynchronous. See \[this 3177 note\](\#using-callbacks) for details. 3178 3179 1. 1. Returns 3180 3181 ? 3182 3183 \`\`\`js 3184 web3.eth.unregister("0x407d73d8a49eeb85d32cf465507dd71d507100ca") \`\`\` 3185 3186 1. 1. web3.eth.getBalance 3187 3188 ` web3.eth.getBalance(addressHexString [, defaultBlock] [, callback])` 3189 3190 Get the balance of an address at a given block. 3191 3192 1. 1. Parameters 3193 3194 1\. \`String\` - The address to get the balance of. 2. \`Number|String\` 3195 - (optional) If you pass this parameter it will not use the default 3196 block set with \[web3.eth.defaultBlock\](\#web3ethdefaultblock). 3. 3197 \`Function\` - (optional) If you pass a callback the HTTP request is 3198 made asynchronous. See \[this note\](\#using-callbacks) for details. 3199 3200 1. 1. Returns 3201 3202 \`String\` - A BigNumber instance of the current balance for the given 3203 address in wei. 3204 3205 See the \[note on BigNumber\](\#a-note-on-big-numbers-in-javascript). 3206 3207 \`\`\`js var balance = 3208 web3.eth.getBalance("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); 3209 console.log(balance); // instanceof BigNumber 3210 console.log(balance.toString(10)); // '1000000000000' 3211 console.log(balance.toNumber()); // 1000000000000 3212 \`\`\` 3213 3214 1. 1. web3.eth.getStorageAt 3215 3216 ` web3.eth.getStorageAt(addressHexString, position [, defaultBlock] [, callback])` 3217 3218 Get the storage at a specific position of an address. 3219 3220 1. 1. Parameters 3221 3222 1\. \`String\` - The address to get the storage from. 2. \`Number\` - 3223 The index position of the storage. 3. \`Number|String\` - (optional) If 3224 you pass this parameter it will not use the default block set with 3225 \[web3.eth.defaultBlock\](\#web3ethdefaultblock). 4. \`Function\` - 3226 (optional) If you pass a callback the HTTP request is made asynchronous. 3227 See \[this note\](\#using-callbacks) for details. 3228 3229 1. 1. Returns 3230 3231 \`String\` - The value in storage at the given position. 3232 3233 \`\`\`js var state = 3234 web3.eth.getStorageAt("0x407d73d8a49eeb85d32cf465507dd71d507100c1", 0); 3235 console.log(state); // "0x03" \`\`\` 3236 3237 1. 1. web3.eth.getCode 3238 3239 ` web3.eth.getCode(addressHexString [, defaultBlock] [, callback])` 3240 3241 Get the code at a specific address. 3242 3243 1. 1. Parameters 3244 3245 1\. \`String\` - The address to get the code from. 2. \`Number|String\` 3246 - (optional) If you pass this parameter it will not use the default 3247 block set with \[web3.eth.defaultBlock\](\#web3ethdefaultblock). 3. 3248 \`Function\` - (optional) If you pass a callback the HTTP request is 3249 made asynchronous. See \[this note\](\#using-callbacks) for details. 3250 3251 1. 1. Returns 3252 3253 \`String\` - The data at given address \`addressHexString\`. 3254 3255 \`\`\`js var code = 3256 web3.eth.getCode("0xd5677cf67b5aa051bb40496e68ad359eb97cfbf8"); 3257 console.log(code); // 3258 "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" 3259 \`\`\` 3260 3261 1. 1. web3.eth.getBlock 3262 3263 ` web3.eth.getBlock(blockHashOrBlockNumber [, returnTransactionObjects] [, callback])` 3264 3265 Returns a block matching the block number or block hash. 3266 3267 1. 1. Parameters 3268 3269 1\. \`String|Number\` - The block number or hash. Or the string 3270 \`"earliest"\`, \`"latest"\` or \`"pending"\` as in the \[default block 3271 parameter\](\#web3ethdefaultblock). 2. \`Boolean\` - (optional, default 3272 \`false\`) If \`true\`, the returned block will contain all transactions 3273 as objects, if \`false\` it will only contains the transaction hashes. 3274 3. \`Function\` - (optional) If you pass a callback the HTTP request is 3275 made asynchronous. See \[this note\](\#using-callbacks) for details. 3276 3277 1. 1. Returns 3278 3279 \`Object\` - The block 3280 object: 3281 3282 `` - `number`: `Number` - the block number. `null` when its pending block.`` 3283 `` - `hash`: `String`, 32 Bytes - hash of the block. `null` when its pending block.`` 3284 `` - `parentHash`: `String`, 32 Bytes - hash of the parent block.`` 3285 `` - `nonce`: `String`, 8 Bytes - hash of the generated proof-of-work. `null` when its pending block.`` 3286 `` - `sha3Uncles`: `String`, 32 Bytes - SHA3 of the uncles data in the block.`` 3287 `` - `logsBloom`: `String`, 256 Bytes - the bloom filter for the logs of the block. `null` when its pending block.`` 3288 `` - `transactionsRoot`: `String`, 32 Bytes - the root of the transaction trie of the block`` 3289 `` - `stateRoot`: `String`, 32 Bytes - the root of the final state trie of the block.`` 3290 `` - `miner`: `String`, 20 Bytes - the address of the beneficiary to whom the mining rewards were given.`` 3291 `` - `difficulty`: `BigNumber` - integer of the difficulty for this block.`` 3292 `` - `totalDifficulty`: `BigNumber` - integer of the total difficulty of the chain until this block.`` 3293 `` - `extraData`: `String` - the "extra data" field of this block.`` 3294 `` - `size`: `Number` - integer the size of this block in bytes.`` 3295 `` - `gasLimit`: `Number` - the maximum gas allowed in this block.`` 3296 `` - `gasUsed`: `Number` - the total used gas by all transactions in this block.`` 3297 `` - `timestamp`: `Number` - the unix timestamp for when the block was collated.`` 3298 `` - `transactions`: `Array` - Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter.`` 3299 `` - `uncles`: `Array` - Array of uncle hashes.`` 3300 3301 \`\`\`js var info = web3.eth.getBlock(3150); console.log(info); /\* 3302 { 3303 3304 ` "number": 3,` 3305 ` "hash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",` 3306 ` "parentHash": "0x2302e1c0b972d00932deb5dab9eb2982f570597d9d42504c05d9c2147eaf9c88",` 3307 ` "nonce": "0xfb6e1a62d119228b",` 3308 ` "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347",` 3309 ` "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",` 3310 ` "transactionsRoot": "0x3a1b03875115b79539e5bd33fb00d8f7b7cd61929d5a3c574f507b8acf415bee",` 3311 ` "stateRoot": "0xf1133199d44695dfa8fd1bcfe424d82854b5cebef75bddd7e40ea94cda515bcb",` 3312 ` "miner": "0x8888f1f195afa192cfee860698584c030f4c9db1",` 3313 ` "difficulty": BigNumber,` 3314 ` "totalDifficulty": BigNumber,` 3315 ` "size": 616,` 3316 ` "extraData": "0x",` 3317 ` "gasLimit": 3141592,` 3318 ` "gasUsed": 21662,` 3319 ` "timestamp": 1429287689,` 3320 ` "transactions": [` 3321 ` "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b"` 3322 ` ],` 3323 ` "uncles": []` 3324 3325 } 3326 3327 - / 3328 3329 \`\`\` 3330 3331 1. 1. web3.eth.getBlockTransactionCount 3332 3333 ` web3.eth.getBlockTransactionCount(hashStringOrBlockNumber [, callback])` 3334 3335 Returns the number of transaction in a given block. 3336 3337 1. 1. Parameters 3338 3339 1\. \`String|Number\` - The block number or hash. Or the string 3340 \`"earliest"\`, \`"latest"\` or \`"pending"\` as in the \[default block 3341 parameter\](\#web3ethdefaultblock). 2. \`Function\` - (optional) If you 3342 pass a callback the HTTP request is made asynchronous. See \[this 3343 note\](\#using-callbacks) for details. 3344 3345 1. 1. Returns 3346 3347 \`Number\` - The number of transactions in the given block. 3348 3349 \`\`\`js var number = 3350 web3.eth.getBlockTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); 3351 console.log(number); // 1 3352 \`\`\` 3353 3354 1. 1. web3.eth.getUncle 3355 3356 ` web3.eth.getUncle(blockHashStringOrNumber, uncleNumber [, returnTransactionObjects] [, callback])` 3357 3358 Returns a blocks uncle by a given uncle index position. 3359 3360 1. 1. Parameters 3361 3362 1\. \`String|Number\` - The block number or hash. Or the string 3363 \`"earliest"\`, \`"latest"\` or \`"pending"\` as in the \[default block 3364 parameter\](\#web3ethdefaultblock). 2. \`Number\` - The index position 3365 of the uncle. 3. \`Boolean\` - (optional, default \`false\`) If 3366 \`true\`, the returned block will contain all transactions as objects, 3367 if \`false\` it will only contains the transaction hashes. 4. 3368 \`Function\` - (optional) If you pass a callback the HTTP request is 3369 made asynchronous. See \[this note\](\#using-callbacks) for details. 3370 3371 1. 1. Returns 3372 3373 \`Object\` - the returned uncle. For a return value see 3374 \[web3.eth.getBlock()\](\#web3ethgetblock). 3375 3376 - - Note\*\*: An uncle doesn't contain individual transactions. 3377 3378 \`\`\`js var uncle = web3.eth.getUncle(500, 0); console.log(uncle); // 3379 see web3.eth.getBlock 3380 3381 \`\`\` 3382 3383 - - 3384 <!-- end list --> 3385 3386 1. 1. web3.eth.getTransaction 3387 3388 ` web3.eth.getTransaction(transactionHash [, callback])` 3389 3390 Returns a transaction matching the given transaction hash. 3391 3392 1. 1. Parameters 3393 3394 1\. \`String\` - The transaction hash. 2. \`Function\` - (optional) If 3395 you pass a callback the HTTP request is made asynchronous. See \[this 3396 note\](\#using-callbacks) for details. 3397 3398 1. 1. Returns 3399 3400 \`Object\` - A transaction object its hash 3401 \`transactionHash\`: 3402 3403 `` - `hash`: `String`, 32 Bytes - hash of the transaction.`` 3404 `` - `nonce`: `Number` - the number of transactions made by the sender prior to this one.`` 3405 `` - `blockHash`: `String`, 32 Bytes - hash of the block where this transaction was in. `null` when its pending.`` 3406 `` - `blockNumber`: `Number` - block number where this transaction was in. `null` when its pending.`` 3407 `` - `transactionIndex`: `Number` - integer of the transactions index position in the block. `null` when its pending.`` 3408 `` - `from`: `String`, 20 Bytes - address of the sender.`` 3409 `` - `to`: `String`, 20 Bytes - address of the receiver. `null` when its a contract creation transaction.`` 3410 `` - `value`: `BigNumber` - value transferred in Wei.`` 3411 `` - `gasPrice`: `BigNumber` - gas price provided by the sender in Wei.`` 3412 `` - `gas`: `Number` - gas provided by the sender.`` 3413 `` - `input`: `String` - the data sent along with the transaction.`` 3414 3415 \`\`\`js var blockNumber = 668; var indexOfTransaction = 0 3416 3417 var transaction = web3.eth.getTransaction(blockNumber, 3418 indexOfTransaction); console.log(transaction); /\* 3419 { 3420 3421 ` "hash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",` 3422 ` "nonce": 2,` 3423 ` "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",` 3424 ` "blockNumber": 3,` 3425 ` "transactionIndex": 0,` 3426 ` "from": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",` 3427 ` "to": "0x6295ee1b4f6dd65047762f924ecd367c17eabf8f",` 3428 ` "value": BigNumber,` 3429 ` "gas": 314159,` 3430 ` "gasPrice": BigNumber,` 3431 ` "input": "0x57cb2fc4"` 3432 3433 } 3434 3435 - / 3436 3437 \`\`\` 3438 3439 1. 1. web3.eth.getTransactionFromBlock 3440 3441 ` getTransactionFromBlock(hashStringOrNumber, indexNumber [, callback])` 3442 3443 Returns a transaction based on a block hash or number and the 3444 transactions index position. 3445 3446 1. 1. Parameters 3447 3448 1\. \`String\` - A block number or hash. Or the string \`"earliest"\`, 3449 \`"latest"\` or \`"pending"\` as in the \[default block 3450 parameter\](\#web3ethdefaultblock). 2. \`Number\` - The transactions 3451 index position. 3. \`Function\` - (optional) If you pass a callback the 3452 HTTP request is made asynchronous. See \[this note\](\#using-callbacks) 3453 for details. 3454 3455 1. 1. Returns 3456 3457 \`Object\` - A transaction object, see 3458 \[web3.eth.getTransaction\](\#web3ethgettransaction): 3459 3460 \`\`\`js var transaction = 3461 web3.eth.getTransactionFromBlock('0x4534534534', 2); 3462 console.log(transaction); // see web3.eth.getTransaction 3463 3464 \`\`\` 3465 3466 1. 1. web3.eth.getTransactionReceipt 3467 3468 ` web3.eth.getTransactionReceipt(hashString [, callback])` 3469 3470 Returns the receipt of a transaction by transaction hash. 3471 3472 - - Note\*\* That the receipt is not available for pending 3473 transactions. 3474 3475 <!-- end list --> 3476 3477 1. 1. Parameters 3478 3479 1\. \`String\` - The transaction hash. 2. \`Function\` - (optional) If 3480 you pass a callback the HTTP request is made asynchronous. See \[this 3481 note\](\#using-callbacks) for details. 3482 3483 1. 1. Returns 3484 3485 \`Object\` - A transaction receipt object, or \`null\` when no receipt 3486 was 3487 found: 3488 3489 `` - `blockHash`: `String`, 32 Bytes - hash of the block where this transaction was in.`` 3490 `` - `blockNumber`: `Number` - block number where this transaction was in.`` 3491 `` - `transactionHash`: `String`, 32 Bytes - hash of the transaction.`` 3492 `` - `transactionIndex`: `Number` - integer of the transactions index position in the block.`` 3493 `` - `from`: `String`, 20 Bytes - address of the sender.`` 3494 `` - `to`: `String`, 20 Bytes - address of the receiver. `null` when its a contract creation transaction.`` 3495 `` - `cumulativeGasUsed `: `Number ` - The total amount of gas used when this transaction was executed in the block.`` 3496 `` - `gasUsed `: `Number ` - The amount of gas used by this specific transaction alone.`` 3497 `` - `contractAddress `: `String` - 20 Bytes - The contract address created, if the transaction was a contract creation, otherwise `null`.`` 3498 `` - `logs `: `Array` - Array of log objects, which this transaction generated.`` 3499 3500 \`\`\`js var receipt = 3501 web3.eth.getTransactionReceipt('0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b'); 3502 console.log(receipt); 3503 { 3504 3505 ` "transactionHash": "0x9fc76417374aa880d4449a1f7f31ec597f00b1f6f3dd2d66f4c9c6c445836d8b",` 3506 ` "transactionIndex": 0,` 3507 ` "blockHash": "0xef95f2f1ed3ca60b048b4bf67cde2195961e0bba6f70bcbea9a2c4e133e34b46",` 3508 ` "blockNumber": 3,` 3509 ` "contractAddress": "0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b",` 3510 ` "cumulativeGasUsed": 314159,` 3511 ` "gasUsed": 30234,` 3512 ` "logs": [{` 3513 ` // logs as returned by getFilterLogs, etc.` 3514 ` }, ...]` 3515 3516 } 3517 \`\`\` 3518 3519 1. 1. web3.eth.getTransactionCount 3520 3521 ` web3.eth.getTransactionCount(addressHexString [, defaultBlock] [, callback])` 3522 3523 Get the numbers of transactions sent from this address. 3524 3525 1. 1. Parameters 3526 3527 1\. \`String\` - The address to get the numbers of transactions from. 2. 3528 \`Number|String\` - (optional) If you pass this parameter it will not 3529 use the default block set with 3530 \[web3.eth.defaultBlock\](\#web3ethdefaultblock). 3. \`Function\` - 3531 (optional) If you pass a callback the HTTP request is made asynchronous. 3532 See \[this note\](\#using-callbacks) for details. 3533 3534 1. 1. Returns 3535 3536 \`Number\` - The number of transactions sent from the given address. 3537 3538 \`\`\`js var number = 3539 web3.eth.getTransactionCount("0x407d73d8a49eeb85d32cf465507dd71d507100c1"); 3540 console.log(number); // 1 \`\`\` 3541 3542 1. 1. web3.eth.sendTransaction 3543 3544 ` web3.eth.sendTransaction(transactionObject [, callback])` 3545 3546 Sends a transaction to the network. 3547 3548 1. 1. Parameters 3549 3550 1\. \`Object\` - The transaction object to 3551 send: 3552 3553 `` - `from`: `String` - The address for the sending account. Uses the [web3.eth.defaultAccount](#web3ethdefaultaccount) property, if not specified.`` 3554 `` - `to`: `String` - (optional) The destination address of the message, left undefined for a contract-creation transaction.`` 3555 `` - `value`: `Number|String|BigNumber` - (optional) The value transferred for the transaction in Wei, also the endowment if it's a contract-creation transaction.`` 3556 `` - `gas`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The amount of gas to use for the transaction (unused gas is refunded).`` 3557 `` - `gasPrice`: `Number|String|BigNumber` - (optional, default: To-Be-Determined) The price of gas for this transaction in wei, defaults to the mean network gas price.`` 3558 `` - `data`: `String` - (optional) Either a [byte string](https://github.com/ethereum/wiki/wiki/Solidity,-Docs-and-ABI) containing the associated data of the message, or in the case of a contract-creation transaction, the initialisation code.`` 3559 `` - `nonce`: `Number` - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.`` 3560 3561 2\. \`Function\` - (optional) If you pass a callback the HTTP request is 3562 made asynchronous. See \[this note\](\#using-callbacks) for details. 3563 3564 1. 1. Returns 3565 3566 \`String\` - The 32 Bytes transaction hash as HEX string. 3567 3568 If the transaction was a contract creation use 3569 \[web3.eth.getTransactionReceipt()\](\#web3gettransactionreceipt) to get 3570 the contract address, after the transaction was mined. 3571 3572 \`\`\`js 3573 3574 // compiled solidity source code using 3575 <https://chriseth.github.io/cpp-ethereum/> var code = 3576 "603d80600c6000396000f3007c01000000000000000000000000000000000000000000000000000000006000350463c6888fa18114602d57005b6007600435028060005260206000f3"; 3577 3578 web3.eth.sendTransaction({data: code}, function(err, address) 3579 { 3580 3581 ` if (!err)` 3582 ` console.log(address); // "0x7f9fade1c0d57a7af66ab4ead7c2eb7b11a91385"` 3583 3584 }); \`\`\` 3585 3586 1. 1. web3.eth.sendRawTransaction 3587 3588 ` web3.eth.sendRawTransaction(signedTransactionData [, callback])` 3589 3590 Sends an already signed transaction. For example can be signed using: 3591 <https://github.com/SilentCicero/ethereumjs-accounts> 3592 3593 1. 1. Parameters 3594 3595 1\. \`String\` - Signed transaction data in HEX format 2. \`Function\` - 3596 (optional) If you pass a callback the HTTP request is made asynchronous. 3597 See \[this note\](\#using-callbacks) for details. 3598 3599 1. 1. Returns 3600 3601 \`String\` - The 32 Bytes transaction hash as HEX string. 3602 3603 If the transaction was a contract creation use 3604 \[web3.eth.getTransactionReceipt()\](\#web3gettransactionreceipt) to get 3605 the contract address, after the transaction was mined. 3606 3607 \`\`\`js var Tx = require('ethereumjs-tx'); var privateKey = new 3608 Buffer('e331b6d69882b4cb4ea581d88e0b604039a3de5967688d3dcffdd2270c0fd109', 3609 'hex') 3610 3611 var rawTx = 3612 { 3613 3614 ` nonce: '0x00',` 3615 ` gasPrice: '0x09184e72a000', ` 3616 ` gasLimit: '0x2710',` 3617 ` to: '0x0000000000000000000000000000000000000000', ` 3618 ` value: '0x00', ` 3619 ` data: '0x7f7465737432000000000000000000000000000000000000000000000000000000600057'` 3620 3621 } 3622 3623 var tx = new Tx(rawTx); tx.sign(privateKey); 3624 3625 var serializedTx = tx.serialize(); 3626 3627 //console.log(serializedTx.toString('hex')); 3628 //0xf889808609184e72a00082271094000000000000000000000000000000000000000080a47f74657374320000000000000000000000000000000000000000000000000000006000571ca08a8bbf888cfa37bbf0bb965423625641fc956967b81d12e23709cead01446075a01ce999b56a8a88504be365442ea61239198e23d1fce7d00fcfc5cd3b44b7215f 3629 3630 web3.eth.sendRawTransaction(serializedTx.toString('hex'), function(err, 3631 hash) 3632 { 3633 3634 ` if (!err)` 3635 ` console.log(hash); // "0x7f9fade1c0d57a7af66ab4ead79fade1c0d57a7af66ab4ead7c2c2eb7b11a91385"` 3636 3637 }); \`\`\` 3638 3639 - - 3640 <!-- end list --> 3641 3642 1. 1. web3.eth.sign 3643 3644 ` web3.eth.sign(address, dataToSign, [, callback])` 3645 3646 Signs data from a specific account. This account needs to be unlocked. 3647 3648 1. 1. Parameters 3649 3650 1\. \`String\` - Address to sign with. 2. \`String\` - Data to sign. 3. 3651 \`Function\` - (optional) If you pass a callback the HTTP request is 3652 made asynchronous. See \[this note\](\#using-callbacks) for details. 3653 3654 1. 1. Returns 3655 3656 \`String\` - The signed data. 3657 3658 After the hex prefix, characters correspond to ECDSA values like this: 3659 \`\`\` r = signature\[0:64\] s = signature\[64:128\] v = 3660 signature\[128:130\] \`\`\` 3661 3662 Note that if you are using \`ecrecover\`, \`v\` will be either \`"00"\` 3663 or \`"01"\`. As a result, in order to use this value, you will have to 3664 parse it to an integer and then add \`27\`. This will result in either a 3665 \`27\` or a \`28\`. 3666 3667 \`\`\`js var result = 3668 web3.eth.sign("0x135a7de83802408321b74c322f8558db1679ac20", 3669 3670 ` "0x9dd2c369a187b4e6b9c402f030e50743e619301ea62aa4c0737d4ef7e10a3d49"); // second argument is web3.sha3("xyz")` 3671 3672 console.log(result); // 3673 "0x30755ed65396facf86c53e6217c52b4daebe72aa4941d89635409de4c9c7f9466d4e9aaec7977f05e923889b33c0d0dd27d7226b6e6f56ce737465c5cfd04be400" 3674 \`\`\` 3675 3676 1. 1. web3.eth.call 3677 3678 ` web3.eth.call(callObject [, defaultBlock] [, callback])` 3679 3680 Executes a message call transaction, which is directly executed in the 3681 VM of the node, but never mined into the blockchain. 3682 3683 1. 1. Parameters 3684 3685 1\. \`Object\` - A transaction object see 3686 \[web3.eth.sendTransaction\](\#web3ethsendtransaction), with the 3687 difference that for calls the \`from\` property is optional as well. 2. 3688 \`Number|String\` - (optional) If you pass this parameter it will not 3689 use the default block set with 3690 \[web3.eth.defaultBlock\](\#web3ethdefaultblock). 3. \`Function\` - 3691 (optional) If you pass a callback the HTTP request is made asynchronous. 3692 See \[this note\](\#using-callbacks) for details. 3693 3694 1. 1. Returns 3695 3696 \`String\` - The returned data of the call, e.g. a codes functions 3697 return value. 3698 3699 \`\`\`js var result = 3700 web3.eth.call({ 3701 3702 ` to: "0xc4abd0339eb8d57087278718986382264244252f", ` 3703 ` data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"` 3704 3705 }); console.log(result); // 3706 "0x0000000000000000000000000000000000000000000000000000000000000015" 3707 \`\`\` 3708 3709 1. 1. web3.eth.estimateGas 3710 3711 ` web3.eth.estimateGas(callObject [, callback])` 3712 3713 Executes a message call or transaction, which is directly executed in 3714 the VM of the node, but never mined into the blockchain and returns the 3715 amount of the gas used. 3716 3717 1. 1. Parameters 3718 3719 See \[web3.eth.sendTransaction\](\#web3ethsendtransaction), except that 3720 all properties are optional. 3721 3722 1. 1. Returns 3723 3724 \`Number\` - the used gas for the simulated call/transaction. 3725 3726 \`\`\`js var result = 3727 web3.eth.estimateGas({ 3728 3729 ` to: "0xc4abd0339eb8d57087278718986382264244252f", ` 3730 ` data: "0xc6888fa10000000000000000000000000000000000000000000000000000000000000003"` 3731 3732 }); console.log(result); // 3733 "0x0000000000000000000000000000000000000000000000000000000000000015" 3734 \`\`\` 3735 3736 1. 1. web3.eth.filter 3737 3738 \`\`\`js // can be 'latest' or 'pending' var filter = 3739 web3.eth.filter(filterString); // OR object are log filter options var 3740 filter = web3.eth.filter(options); 3741 3742 // watch for changes filter.watch(function(error, result){ 3743 3744 ` if (!error)` 3745 ` console.log(result);` 3746 3747 }); 3748 3749 // Additionally you can start watching right away, by passing a 3750 callback: web3.eth.filter(options, function(error, result){ 3751 3752 ` if (!error)` 3753 ` console.log(result);` 3754 3755 }); \`\`\` 3756 3757 1. 1. Parameters 3758 3759 1\. \`String|Object\` - The string \`"latest"\` or \`"pending"\` to 3760 watch for changes in the latest block or pending transactions 3761 respectively. Or a filter options object as 3762 follows: 3763 3764 `` * `fromBlock`: `Number|String` - The number of the earliest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`.`` 3765 `` * `toBlock`: `Number|String` - The number of the latest block (`latest` may be given to mean the most recent and `pending` currently mining, block). By default `latest`.`` 3766 `` * `address`: `String` - An address or a list of addresses to only get logs from particular account(s).`` 3767 `` * `topics`: `Array of Strings` - An array of values which must each appear in the log entries. The order is important, if you want to leave topics out use `null`, e.g. `[null, '0x00...']`. You can also pass another array for each topic with options for that topic e.g. `[null, ['option1', 'option2']]` `` 3768 3769 1. 1. Returns 3770 3771 \`Object\` - A filter object with the following 3772 methods: 3773 3774 `` * `filter.get(callback)`: Returns all of the log entries that fit the filter.`` 3775 `` * `filter.watch(callback)`: Watches for state changes that fit the filter and calls the callback. See [this note](#using-callbacks) for details.`` 3776 `` * `filter.stopWatching()`: Stops the watch and uninstalls the filter in the node. Should always be called once it is done.`` 3777 3778 1. 1. Watch callback return value 3779 3780 \- \`String\` - When using the \`"latest"\` parameter, it returns the 3781 block hash of the last incoming block. - \`String\` - When using the 3782 \`"pending"\` parameter, it returns a transaction hash of the most 3783 recent pending transaction. - \`Object\` - When using manual filter 3784 options, it returns a log object as 3785 follows: 3786 3787 `` - `logIndex`: `Number` - integer of the log index position in the block. `null` when its pending log.`` 3788 `` - `transactionIndex`: `Number` - integer of the transactions index position log was created from. `null` when its pending log.`` 3789 `` - `transactionHash`: `String`, 32 Bytes - hash of the transactions this log was created from. `null` when its pending log.`` 3790 `` - `blockHash`: `String`, 32 Bytes - hash of the block where this log was in. `null` when its pending. `null` when its pending log.`` 3791 `` - `blockNumber`: `Number` - the block number where this log was in. `null` when its pending. `null` when its pending log.`` 3792 `` - `address`: `String`, 32 Bytes - address from which this log originated.`` 3793 `` - `data`: `String` - contains one or more 32 Bytes non-indexed arguments of the log.`` 3794 `` - `topics`: `Array of Strings` - Array of 0 to 4 32 Bytes `DATA` of indexed log arguments. (In *solidity*: The first topic is the *hash* of the signature of the event (e.g. `Deposit(address,bytes32,uint256)`), except if you declared the event with the `anonymous` specifier.)`` 3795 3796 - - Note\*\* For event filter return values see \[Contract 3797 Events\](\#contract-events) 3798 3799 \`\`\`js var filter = web3.eth.filter('pending'); 3800 3801 filter.watch(function (error, log) 3802 { 3803 3804 ` console.log(log); // {"address":"0x0000000000000000000000000000000000000000", "data":"0x0000000000000000000000000000000000000000000000000000000000000000", ...}` 3805 3806 }); 3807 3808 // get all past logs again. var myResults = filter.get(function(error, 3809 logs){ ... }); 3810 3811 ... 3812 3813 // stops and uninstalls the filter filter.stopWatching(); 3814 3815 \`\`\` 3816 3817 1. 1. web3.eth.contract 3818 3819 ` web3.eth.contract(abiArray)` 3820 3821 Creates a contract object for a solidity contract, which can be used to 3822 initiate contracts on an address. You can read more about events 3823 \[here\](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI\#example-javascript-usage). 3824 3825 1. 1. Parameters 3826 3827 1\. \`Array\` - ABI array with descriptions of functions and events of 3828 the contract. 3829 3830 1. 1. Returns 3831 3832 \`Object\` - A contract object, which can be initiated as follows: 3833 3834 \`\`\`js var MyContract = web3.eth.contract(abiArray); 3835 3836 // instantiate by address var contractInstance = 3837 MyContract.at(\[address\]); 3838 3839 // deploy new contract var contractInstance = 3840 MyContract.new(\[contructorParam1\] \[, contructorParam2\], {data: 3841 '0x12345...', from: myAccount, gas: 1000000}); 3842 3843 // Get the data to deploy the contract manually var contractData = 3844 MyContract.new.getData(\[contructorParam1\] \[, contructorParam2\], 3845 {data: '0x12345...'}); // contractData = 3846 '0x12345643213456000000000023434234' \`\`\` 3847 3848 And then you can either initiate an existing contract on an address, or 3849 deploy the contract using the compiled byte code: 3850 3851 \`\`\`js // Instantiate from an existing address: var myContractInstance 3852 = MyContract.at(myContractAddress); 3853 3854 // Or deploy a new contract: 3855 3856 // Deploy the contract asyncronous from Solidity file: ... const fs = 3857 require("fs"); const solc = require('solc') 3858 3859 let source = fs.readFileSync('nameContract.sol', 'utf8'); let 3860 compiledContract = solc.compile(source, 1); let abi = 3861 compiledContract.contracts\['nameContract'\].interface; let bytecode = 3862 compiledContract.contracts\['nameContract'\].bytecode; let gasEstimate = 3863 web3.eth.estimateGas({data: bytecode}); let MyContract = 3864 web3.eth.contract(JSON.parse(abi)); 3865 3866 var myContractReturned = MyContract.new(param1, param2, 3867 { 3868 3869 ` from:mySenderAddress,` 3870 ` `<data:bytecode>`,` 3871 ` gas:gasEstimate}, function(err, myContract){` 3872 ` if(!err) {` 3873 ` // NOTE: The callback will fire twice!` 3874 ` // Once the contract has the transactionHash property set and once its deployed on an address.` 3875 3876 ` // e.g. check tx hash on the first call (transaction send)` 3877 ` if(!myContract.address) {` 3878 ` console.log(myContract.transactionHash) // The hash of the transaction, which deploys the contract` 3879 ` ` 3880 ` // check address on the second call (contract deployed)` 3881 ` } else {` 3882 ` console.log(myContract.address) // the contract address` 3883 ` }` 3884 3885 ` // Note that the returned "myContractReturned" === "myContract",` 3886 ` // so the returned "myContractReturned" object will also get the address set.` 3887 ` }` 3888 ` });` 3889 3890 // Deploy contract syncronous: The address will be added as soon as the 3891 contract is mined. // Additionally you can watch the transaction by 3892 using the "transactionHash" property var myContractInstance = 3893 MyContract.new(param1, param2, {data: myContractCode, gas: 300000, from: 3894 mySenderAddress}); myContractInstance.transactionHash // The hash of the 3895 transaction, which created the contract myContractInstance.address // 3896 undefined at start, but will be auto-filled later \`\`\` 3897 3898 \`\`\`js // contract abi var abi = \[{ 3899 3900 ` name: 'myConstantMethod',` 3901 ` type: 'function',` 3902 ` constant: true,` 3903 ` inputs: [{ name: 'a', type: 'string' }],` 3904 ` outputs: [{name: 'd', type: 'string' }]` 3905 3906 }, 3907 { 3908 3909 ` name: 'myStateChangingMethod',` 3910 ` type: 'function',` 3911 ` constant: false,` 3912 ` inputs: [{ name: 'a', type: 'string' }, { name: 'b', type: 'int' }],` 3913 ` outputs: []` 3914 3915 }, 3916 { 3917 3918 ` name: 'myEvent',` 3919 ` type: 'event',` 3920 ` inputs: [{name: 'a', type: 'int', indexed: true},{name: 'b', type: 'bool', indexed: false}]` 3921 3922 }\]; 3923 3924 // creation of contract object var MyContract = web3.eth.contract(abi); 3925 3926 // initiate contract for an address var myContractInstance = 3927 MyContract.at('0xc4abd0339eb8d57087278718986382264244252f'); 3928 3929 // call constant function var result = 3930 myContractInstance.myConstantMethod('myParam'); console.log(result) // 3931 '0x25434534534' 3932 3933 // send a transaction to a function 3934 myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, 3935 gas: 2000}); 3936 3937 // short hand style 3938 web3.eth.contract(abi).at(address).myAwesomeMethod(...); 3939 3940 // create filter var filter = myContractInstance.myEvent({a: 5}, 3941 function (error, result) 3942 { 3943 3944 ` if (!error)` 3945 ` console.log(result);` 3946 ` /*` 3947 ` {` 3948 ` address: '0x8718986382264244252fc4abd0339eb8d5708727',` 3949 ` topics: "0x12345678901234567890123456789012", "0x0000000000000000000000000000000000000000000000000000000000000005",` 3950 ` data: "0x0000000000000000000000000000000000000000000000000000000000000001",` 3951 ` ...` 3952 ` }` 3953 ` */` 3954 3955 }); \`\`\` 3956 3957 1. 1. Contract Methods 3958 3959 \`\`\`js // Automatically determines the use of call or sendTransaction 3960 based on the method type myContractInstance.myMethod(param1 \[, param2, 3961 ...\] \[, transactionObject\] \[, defaultBlock\] \[, callback\]); 3962 3963 // Explicitly calling this method 3964 myContractInstance.myMethod.call(param1 \[, param2, ...\] \[, 3965 transactionObject\] \[, defaultBlock\] \[, callback\]); 3966 3967 // Explicitly sending a transaction to this method 3968 myContractInstance.myMethod.sendTransaction(param1 \[, param2, ...\] \[, 3969 transactionObject\] \[, callback\]); 3970 3971 // Get the call data, so you can call the contract through some other 3972 means var myCallData = myContractInstance.myMethod.getData(param1 \[, 3973 param2, ...\]); // myCallData = '0x45ff3ff6000000000004545345345345..' 3974 \`\`\` 3975 3976 The contract object exposes the contract's methods, which can be called 3977 using parameters and a transaction object. 3978 3979 1. 1. Parameters 3980 3981 \- \`String|Number\` - (optional) Zero or more parameters of the 3982 function. If passing in a string, it must be formatted as a hex number, 3983 e.g. "0xdeadbeef". - \`Object\` - (optional) The (previous) last 3984 parameter can be a transaction object, see 3985 \[web3.eth.sendTransaction\](\#web3ethsendtransaction) parameter 1 for 3986 more. \*\*Note\*\*: \`data\` and \`to\` properties will not be taken 3987 into account. - \`Number|String\` - (optional) If you pass this 3988 parameter it will not use the default block set with 3989 \[web3.eth.defaultBlock\](\#web3ethdefaultblock). - \`Function\` - 3990 (optional) If you pass a callback as the last parameter the HTTP request 3991 is made asynchronous. See \[this note\](\#using-callbacks) for details. 3992 3993 1. 1. Returns 3994 3995 \`String\` - If its a call the result data, if its a send transaction a 3996 created contract address, or the transaction hash, see 3997 \[web3.eth.sendTransaction\](\#web3ethsendtransaction) for details. 3998 3999 \`\`\`js // creation of contract object var MyContract = 4000 web3.eth.contract(abi); 4001 4002 // initiate contract for an address var myContractInstance = 4003 MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); 4004 4005 var result = myContractInstance.myConstantMethod('myParam'); 4006 console.log(result) // '0x25434534534' 4007 4008 myContractInstance.myStateChangingMethod('someParam1', 23, {value: 200, 4009 gas: 2000}, function(err, result){ ... }); \`\`\` 4010 4011 - - 4012 <!-- end list --> 4013 4014 1. 1. Contract Events 4015 4016 \`\`\`js var event = myContractInstance.MyEvent({valueA: 23} \[, 4017 additionalFilterObject\]) 4018 4019 // watch for changes event.watch(function(error, result){ 4020 4021 ` if (!error)` 4022 ` console.log(result);` 4023 4024 }); 4025 4026 // Or pass a callback to start watching immediately var event = 4027 myContractInstance.MyEvent(\[{valueA: 23}\] \[, additionalFilterObject\] 4028 , function(error, result){ 4029 4030 ` if (!error)` 4031 ` console.log(result);` 4032 4033 }); 4034 4035 \`\`\` 4036 4037 You can use events like \[filters\](\#web3ethfilter) and they have the 4038 same methods, but you pass different objects to create the event filter. 4039 4040 1. 1. Parameters 4041 4042 1\. \`Object\` - Indexed return values you want to filter the logs by, 4043 e.g. \`{'valueA': 1, 'valueB': \[myFirstAddress, mySecondAddress\]}\`. 4044 By default all filter values are set to \`null\`. It means, that they 4045 will match any event of given type sent from this contract. 2. 4046 \`Object\` - Additional filter options, see \[filters\](\#web3ethfilter) 4047 parameter 1 for more. By default filterObject has field 'address' set to 4048 address of the contract. Also first topic is the signature of event. 3. 4049 \`Function\` - (optional) If you pass a callback as the last parameter 4050 it will immediately start watching and you don't need to call 4051 \`myEvent.watch(function(){})\`. See \[this note\](\#using-callbacks) 4052 for details. 4053 4054 1. 1. Callback return 4055 4056 \`Object\` - An event object as follows: 4057 4058 \- \`address\`: \`String\`, 32 Bytes - address from which this log 4059 originated. - \`args\`: \`Object\` - The arguments coming from the 4060 event. - \`blockHash\`: \`String\`, 32 Bytes - hash of the block where 4061 this log was in. \`null\` when its pending. - \`blockNumber\`: 4062 \`Number\` - the block number where this log was in. \`null\` when its 4063 pending. - \`logIndex\`: \`Number\` - integer of the log index position 4064 in the block. - \`event\`: \`String\` - The event name. - \`removed\`: 4065 \`bool\` - indicate if the transaction this event was created from was 4066 removed from the blockchain (due to orphaned block) or never get to it 4067 (due to rejected transaction). - \`transactionIndex\`: \`Number\` - 4068 integer of the transactions index position log was created from. - 4069 \`transactionHash\`: \`String\`, 32 Bytes - hash of the transactions 4070 this log was created from. 4071 4072 \`\`\`js var MyContract = web3.eth.contract(abi); var myContractInstance 4073 = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); 4074 4075 // watch for an event with {some: 'args'} var myEvent = 4076 myContractInstance.MyEvent({some: 'args'}, {fromBlock: 0, toBlock: 4077 'latest'}); myEvent.watch(function(error, result){ 4078 4079 ` ...` 4080 4081 }); 4082 4083 // would get all past logs again. var myResults = 4084 myEvent.get(function(error, logs){ ... }); 4085 4086 ... 4087 4088 // would stop and uninstall the filter myEvent.stopWatching(); \`\`\` 4089 4090 1. 1. Contract allEvents 4091 4092 \`\`\`js var events = 4093 myContractInstance.allEvents(\[additionalFilterObject\]); 4094 4095 // watch for changes events.watch(function(error, event){ 4096 4097 ` if (!error)` 4098 ` console.log(event);` 4099 4100 }); 4101 4102 // Or pass a callback to start watching immediately var events = 4103 myContractInstance.allEvents(\[additionalFilterObject,\] function(error, 4104 log){ 4105 4106 ` if (!error)` 4107 ` console.log(log);` 4108 4109 }); 4110 4111 \`\`\` 4112 4113 Will call the callback for all events which are created by this 4114 contract. 4115 4116 1. 1. Parameters 4117 4118 1\. \`Object\` - Additional filter options, see 4119 \[filters\](\#web3ethfilter) parameter 1 for more. By default 4120 filterObject has field 'address' set to address of the contract. This 4121 method sets the topic to the signature of event, and does not support 4122 additional topics. 2. \`Function\` - (optional) If you pass a callback 4123 as the last parameter it will immediately start watching and you don't 4124 need to call \`myEvent.watch(function(){})\`. See \[this 4125 note\](\#using-callbacks) for details. 4126 4127 1. 1. Callback return 4128 4129 \`Object\` - See \[Contract Events\](\#contract-events) for more. 4130 4131 \`\`\`js var MyContract = web3.eth.contract(abi); var myContractInstance 4132 = MyContract.at('0x78e97bcc5b5dd9ed228fed7a4887c0d7287344a9'); 4133 4134 // watch for an event with {some: 'args'} var events = 4135 myContractInstance.allEvents({fromBlock: 0, toBlock: 'latest'}); 4136 events.watch(function(error, result){ 4137 4138 ` ...` 4139 4140 }); 4141 4142 // would get all past logs again. events.get(function(error, logs){ ... 4143 }); 4144 4145 ... 4146 4147 // would stop and uninstall the filter myEvent.stopWatching(); \`\`\` 4148 4149 \*\#\# web3.eth.getCompilers 4150 4151 ` web3.eth.getCompilers([callback])` 4152 4153 Gets a list of available compilers. 4154 4155 1. 1. Parameters 4156 4157 1\. \`Function\` - (optional) If you pass a callback the HTTP request is 4158 made asynchronous. See \[this note\](\#using-callbacks) for details. 4159 4160 1. 1. Returns 4161 4162 \`Array\` - An array of strings of available compilers. 4163 4164 \`\`\`js var number = web3.eth.getCompilers(); console.log(number); // 4165 \["lll", "solidity", "serpent"\] \`\`\` 4166 4167 1. 1. web3.eth.compile.solidity 4168 4169 ` web3.eth.compile.solidity(sourceString [, callback])` 4170 4171 Compiles solidity source code. 4172 4173 1. 1. Parameters 4174 4175 1\. \`String\` - The solidity source code. 2. \`Function\` - (optional) 4176 If you pass a callback the HTTP request is made asynchronous. See \[this 4177 note\](\#using-callbacks) for details. 4178 4179 1. 1. Returns 4180 4181 \`Object\` - Contract and compiler info. 4182 4183 \`\`\`js var source = "" + 4184 4185 ` "contract test {\n" +` 4186 ` " function multiply(uint a) returns(uint d) {\n" +` 4187 ` " return a * 7;\n" +` 4188 ` " }\n" +` 4189 ` "}\n";` 4190 4191 var compiled = web3.eth.compile.solidity(source); console.log(compiled); 4192 // 4193 { 4194 4195 ` "test": {` 4196 ` "code": "0x605280600c6000396000f3006000357c010000000000000000000000000000000000000000000000000000000090048063c6888fa114602e57005b60376004356041565b8060005260206000f35b6000600782029050604d565b91905056",` 4197 ` "info": {` 4198 ` "source": "contract test {\n\tfunction multiply(uint a) returns(uint d) {\n\t\treturn a * 7;\n\t}\n}\n",` 4199 ` "language": "Solidity",` 4200 ` "languageVersion": "0",` 4201 ` "compilerVersion": "0.8.2",` 4202 ` "abiDefinition": [` 4203 ` {` 4204 ` "constant": false,` 4205 ` "inputs": [` 4206 ` {` 4207 ` "name": "a",` 4208 ` "type": "uint256"` 4209 ` }` 4210 ` ],` 4211 ` "name": "multiply",` 4212 ` "outputs": [` 4213 ` {` 4214 ` "name": "d",` 4215 ` "type": "uint256"` 4216 ` }` 4217 ` ],` 4218 ` "type": "function"` 4219 ` }` 4220 ` ],` 4221 ` "userDoc": {` 4222 ` "methods": {}` 4223 ` },` 4224 ` "developerDoc": {` 4225 ` "methods": {}` 4226 ` }` 4227 ` }` 4228 ` }` 4229 4230 } \`\`\` 4231 4232 1. 1. web3.eth.compile.lll 4233 4234 ` web3. eth.compile.lll(sourceString [, callback])` 4235 4236 Compiles LLL source code. 4237 4238 1. 1. Parameters 4239 4240 1\. \`String\` - The LLL source code. 2. \`Function\` - (optional) If 4241 you pass a callback the HTTP request is made asynchronous. See \[this 4242 note\](\#using-callbacks) for details. 4243 4244 1. 1. Returns 4245 4246 \`String\` - The compiled LLL code as HEX string. 4247 4248 \`\`\`js var source = "..."; 4249 4250 var code = web3.eth.compile.lll(source); console.log(code); // 4251 "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" 4252 \`\`\` 4253 4254 1. 1. web3.eth.compile.serpent 4255 4256 ` web3.eth.compile.serpent(sourceString [, callback])` 4257 4258 Compiles serpent source code. 4259 4260 1. 1. Parameters 4261 4262 1\. \`String\` - The serpent source code. 2. \`Function\` - (optional) 4263 If you pass a callback the HTTP request is made asynchronous. See \[this 4264 note\](\#using-callbacks) for details. 4265 4266 1. 1. Returns 4267 4268 \`String\` - The compiled serpent code as HEX string. 4269 4270 \`\`\`js var source = "..."; 4271 4272 var code = web3.eth.compile.serpent(source); console.log(code); // 4273 "0x603880600c6000396000f3006001600060e060020a600035048063c6888fa114601857005b6021600435602b565b8060005260206000f35b600081600702905091905056" 4274 \`\`\` 4275 4276 1. 1. web3.eth.namereg 4277 4278 ` web3.eth.namereg` 4279 4280 Returns GlobalRegistrar object. 4281 4282 1. 1. Usage 4283 4284 see 4285 \[namereg\](https://github.com/ethereum/web3.js/blob/master/example/namereg.html) 4286 example. 4287 4288 - - 4289 <!-- end list --> 4290 4291 1. 1. web3.db 4292 4293 <!-- end list --> 4294 4295 1. 1. web3.db.putString 4296 4297 ` web3.db.putString(db, key, value)` 4298 4299 This method should be called, when we want to store a string in the 4300 local leveldb database. 4301 4302 1. 1. Parameters 4303 4304 1\. \`String\` - The database to store to. 2. \`String\` - The name of 4305 the store. 3. \`String\` - The string value to store. 4306 4307 1. 1. Returns 4308 4309 \`Boolean\` - \`true\` if successfull, otherwise \`false\`. 4310 4311 `param is db name, second is the key, and third is the string value.` 4312 4313 \`\`\`js web3.db.putString('testDB', 'key', 'myString') // true \`\`\` 4314 4315 1. 1. web3.db.getString 4316 4317 ` web3.db.getString(db, key)` 4318 4319 This method should be called, when we want to get string from the local 4320 leveldb database. 4321 4322 1. 1. Parameters 4323 4324 1\. \`String\` - The database string name to retrieve from. 2. 4325 \`String\` - The name of the store. 4326 4327 1. 1. Returns 4328 4329 \`String\` - The stored value. 4330 4331 `param is db name and second is the key of string value.` 4332 4333 \`\`\`js var value = web3.db.getString('testDB', 'key'); 4334 console.log(value); // "myString" \`\`\` 4335 4336 1. 1. web3.db.putHex 4337 4338 ` web3.db.putHex(db, key, value)` 4339 4340 This method should be called, when we want to store binary data in HEX 4341 form in the local leveldb database. 4342 4343 1. 1. Parameters 4344 4345 1\. \`String\` - The database to store to. 2. \`String\` - The name of 4346 the store. 3. \`String\` - The HEX string to store. 4347 4348 1. 1. Returns 4349 4350 \`Boolean\` - \`true\` if successfull, otherwise \`false\`. 4351 4352 \`\`\`js web3.db.putHex('testDB', 'key', '0x4f554b443'); // true 4353 4354 \`\`\` 4355 4356 1. 1. web3.db.getHex 4357 4358 ` web3.db.getHex(db, key)` 4359 4360 This method should be called, when we want to get a binary data in HEX 4361 form from the local leveldb database. 4362 4363 1. 1. Parameters 4364 4365 1\. \`String\` - The database to store to. 2. \`String\` - The name of 4366 the store. 4367 4368 1. 1. Returns 4369 4370 \`String\` - The stored HEX value. 4371 4372 `param is db name and second is the key of value.` 4373 4374 \`\`\`js var value = web3.db.getHex('testDB', 'key'); 4375 console.log(value); // "0x4f554b443" \`\`\` 4376 4377 - - 4378 <!-- end list --> 4379 4380 1. 1. web3.shh 4381 4382 \[Whisper 4383 Overview\](https://github.com/ethereum/wiki/wiki/Whisper-Overview) 4384 4385 \`\`\`js var shh = web3.shh; \`\`\` 4386 4387 1. 1. web3.shh.post 4388 4389 ` web3.shh.post(object [, callback])` 4390 4391 This method should be called, when we want to post whisper message to 4392 the network. 4393 4394 1. 1. Parameters 4395 4396 1\. \`Object\` - The post 4397 object: 4398 4399 `` - `from`: `String`, 60 Bytes HEX - (optional) The identity of the sender.`` 4400 `` - `to`: `String`, 60 Bytes HEX - (optional) The identity of the receiver. When present whisper will encrypt the message so that only the receiver can decrypt it.`` 4401 `` - `topics`: `Array of Strings` - Array of topics `Strings`, for the receiver to identify messages.`` 4402 `` - `payload`: `String|Number|Object` - The payload of the message. Will be autoconverted to a HEX string before.`` 4403 `` - `priority`: `Number` - The integer of the priority in a rang from ... (?).`` 4404 `` - `ttl`: `Number` - integer of the time to live in seconds.`` 4405 4406 2\. \`Function\` - (optional) If you pass a callback the HTTP request is 4407 made asynchronous. See \[this note\](\#using-callbacks) for details. 4408 4409 1. 1. Returns 4410 4411 \`Boolean\` - returns \`true\` if the message was send, otherwise 4412 \`false\`. 4413 4414 \`\`\`js var identity = web3.shh.newIdentity(); var topic = 'example'; 4415 var payload = 'hello whisper world\!'; 4416 4417 var message = { 4418 4419 ` from: identity,` 4420 ` topics: [topic],` 4421 ` payload: payload,` 4422 ` ttl: 100,` 4423 ` workToProve: 100 // or priority TODO` 4424 4425 }; 4426 4427 web3.shh.post(message); \`\`\` 4428 4429 1. 1. web3.shh.newIdentity 4430 4431 ` web3.shh.newIdentity([callback])` 4432 4433 Should be called to create new identity. 4434 4435 1. 1. Parameters 4436 4437 1\. \`Function\` - (optional) If you pass a callback the HTTP request is 4438 made asynchronous. See \[this note\](\#using-callbacks) for details. 4439 4440 1. 1. Returns 4441 4442 \`String\` - A new identity HEX string. 4443 4444 \`\`\`js var identity = web3.shh.newIdentity(); console.log(identity); 4445 // 4446 "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" 4447 \`\`\` 4448 4449 1. 1. web3.shh.hasIdentity 4450 4451 ` web3.shh.hasIdentity(identity, [callback])` 4452 4453 Should be called, if we want to check if user has given identity. 4454 4455 1. 1. Parameters 4456 4457 1\. \`String\` - The identity to check. 2. \`Function\` - (optional) If 4458 you pass a callback the HTTP request is made asynchronous. See \[this 4459 note\](\#using-callbacks) for details. 4460 4461 1. 1. Returns 4462 4463 \`Boolean\` - returns \`true\` if the identity exists, otherwise 4464 \`false\`. 4465 4466 \`\`\`js var identity = web3.shh.newIdentity(); var result = 4467 web3.shh.hasIdentity(identity); console.log(result); // true 4468 4469 var result2 = web3.shh.hasIdentity(identity + "0"); 4470 console.log(result2); // false \`\`\` 4471 4472 1. 1. web3.shh.newGroup 4473 4474 \`\`\`js // TODO: not implemented yet \`\`\` 4475 4476 1. 1. web3.shh.addToGroup 4477 4478 \`\`\`js // TODO: not implemented yet \`\`\` 4479 4480 1. 1. web3.shh.filter 4481 4482 \`\`\`js var filter = web3.shh.filter(options) 4483 4484 // watch for changes filter.watch(function(error, result){ 4485 4486 ` if (!error)` 4487 ` console.log(result);` 4488 4489 }); \`\`\` 4490 4491 Watch for incoming whisper messages. 4492 4493 1. 1. Parameters 4494 4495 1\. \`Object\` - The filter 4496 options: 4497 4498 `` * `topics`: `Array of Strings` - Filters messages by this topic(s). You can use the following combinations:`` 4499 `` - `['topic1', 'topic2'] == 'topic1' && 'topic2'` `` 4500 `` - `['topic1', ['topic2', 'topic3']] == 'topic1' && ('topic2' || 'topic3')` `` 4501 `` - `[null, 'topic1', 'topic2'] == ANYTHING && 'topic1' && 'topic2'` -> `null` works as a wildcard`` 4502 `` * `to`: Filter by identity of receiver of the message. If provided and the node has this identity, it will decrypt incoming encrypted messages.`` 4503 4504 2\. \`Function\` - (optional) If you pass a callback the HTTP request is 4505 made asynchronous. See \[this note\](\#using-callbacks) for details. 4506 4507 1. 1. Callback return 4508 4509 \`Object\` - The incoming 4510 message: 4511 4512 `` - `from`: `String`, 60 Bytes - The sender of the message, if a sender was specified.`` 4513 `` - `to`: `String`, 60 Bytes - The receiver of the message, if a receiver was specified.`` 4514 `` - `expiry`: `Number` - Integer of the time in seconds when this message should expire (?).`` 4515 `` - `ttl`: `Number` - Integer of the time the message should float in the system in seconds (?).`` 4516 `` - `sent`: `Number` - Integer of the unix timestamp when the message was sent.`` 4517 `` - `topics`: `Array of String` - Array of `String` topics the message contained.`` 4518 `` - `payload`: `String` - The payload of the message.`` 4519 `` - `workProved`: `Number` - Integer of the work this message required before it was send (?).`` 4520 4521 1. 1. web3.eth.sendIBANTransaction 4522 4523 \`\`\`js var txHash = 4524 web3.eth.sendIBANTransaction('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8', 4525 'XE81ETHXREGGAVOFYORK', 0x100); \`\`\` 4526 4527 Sends IBAN transaction from user account to destination IBAN address. 4528 4529 1. 1. Parameters 4530 4531 \- \`string\` - address from which we want to send transaction - 4532 \`string\` - IBAN address to which we want to send transaction - 4533 \`value\` - value that we want to send in IBAN transaction 4534 4535 1. 1. web3.eth.iban 4536 4537 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); \`\`\` 4538 4539 1. 1. web3.eth.iban.fromAddress 4540 4541 \`\`\`js var i = 4542 web3.eth.iban.fromAddress('0x00c5496aee77c1ba1f0854206a26dda82a81d6d8'); 4543 console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS \`\`\` 4544 4545 1. 1. web3.eth.iban.fromBban 4546 4547 \`\`\`js var i = web3.eth.iban.fromBban('ETHXREGGAVOFYORK'); 4548 console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" \`\`\` 4549 4550 1. 1. web3.eth.iban.createIndirect 4551 4552 \`\`\`js var i = web3.eth.iban.createIndirect({ 4553 4554 ` institution: "XREG",` 4555 ` identifier: "GAVOFYORK"` 4556 4557 }); console.log(i.toString()); // "XE81ETHXREGGAVOFYORK" \`\`\` 4558 4559 1. 1. web3.eth.iban.isValid 4560 4561 \`\`\`js var valid = web3.eth.iban.isValid("XE81ETHXREGGAVOFYORK"); 4562 console.log(valid); // true 4563 4564 var valid2 = web3.eth.iban.isValid("XE82ETHXREGGAVOFYORK"); 4565 console.log(valid2); // false, cause checksum is incorrect 4566 4567 var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var valid3 = 4568 i.isValid(); console.log(valid3); // true 4569 4570 \`\`\` 4571 4572 1. 1. web3.eth.iban.isDirect 4573 4574 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var direct = 4575 i.isDirect(); console.log(direct); // false \`\`\` 4576 4577 1. 1. web3.eth.iban.isIndirect 4578 4579 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var indirect 4580 = i.isIndirect(); console.log(indirect); // true \`\`\` 4581 4582 1. 1. web3.eth.iban.checksum 4583 4584 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var checksum 4585 = i.checksum(); console.log(checksum); // "81" \`\`\` 4586 4587 1. 1. web3.eth.iban.institution 4588 4589 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var 4590 institution = i.institution(); console.log(institution); // 'XREG' 4591 \`\`\` 4592 4593 1. 1. web3.eth.iban.client 4594 4595 \`\`\`js var i = new web3.eth.iban("XE81ETHXREGGAVOFYORK"); var client = 4596 i.client(); console.log(client); // 'GAVOFYORK' \`\`\` 4597 4598 1. 1. web3.eth.iban.address 4599 4600 \`\`\`js var i = new 4601 web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); var address = 4602 i.address(); console.log(address); // 4603 '00c5496aee77c1ba1f0854206a26dda82a81d6d8' \`\`\` 4604 4605 1. 1. web3.eth.iban.toString 4606 4607 \`\`\`js var i = new 4608 web3.eth.iban('XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS'); 4609 console.log(i.toString()); // 'XE7338O073KYGTWWZN0F2WZ0R8PX5ZPPZS' 4610 \`\`\`