diff --git a/AENS.md b/AENS.md index cc9110ea..6ce30636 100644 --- a/AENS.md +++ b/AENS.md @@ -93,7 +93,7 @@ the name's length. It is decreasing function: for shorter names have higher init fee. Also bidding by claim transaction is constrained by price progression. -Each next bid has to be higher by `X` tokens, determined by percent of the price +Each next bid has to be higher by `X` coins, determined by percent of the price defined in governance. All, functions, base fee, free length value and price progression may be subject diff --git a/channels/OFF-CHAIN.md b/channels/OFF-CHAIN.md index 89d5de26..685a0076 100644 --- a/channels/OFF-CHAIN.md +++ b/channels/OFF-CHAIN.md @@ -670,7 +670,7 @@ In order to deposit more funds into the channel, one party can initiate a `deposit_created` request. It consists of a single-authenticated `channel_deposit_tx` transaction as well as a list of updates. The transaction includes the state hash and round of the next off-chain state, after applying -the updates on top of latest state. +the updates on top of latest state. Note that it is possible to deposit a zero amount, essentially making the operation an on-chain snapshot. @@ -991,7 +991,7 @@ A channel can be closed under three circumstances: 1. Both parties agree to the close and authenticate the closing transaction together, which then gets broadcasted and included in the blockchain. 2. One party wants to close the channel: the other party might had been missing - for some time or had been trying to cheat. In this case either side can publish + for some time or had been trying to cheat. In this case either side can publish the latest state authenticated by both parties and claim their balance after the negotiated timeout. 3. A malicious party tries to publish an outdated state, which it prefers over a @@ -1150,7 +1150,7 @@ call is considered to be executed. Its results can be extracted from the calls tree in the state tree. Part of the call is the `amount` a participants commits to the contract. This is not to be confused with [gas consumption](#gas-consumption) - `amount` are -the tokens moved from the caller's off-chain balance to the off-chain balance +the coins moved from the caller's on-chain balance to the on-chain balance of the contract been called. ### Contracts referring to on-chain data diff --git a/consensus/README.md b/consensus/README.md index c3af0503..9254c0ef 100644 --- a/consensus/README.md +++ b/consensus/README.md @@ -130,9 +130,9 @@ Available from the Fortuna consensus protocol version. The peer-to-peer network is not part of the consensus and will be described in a separate document. -### Coins and tokens +### Coins -#### æternity tokens +#### æternity coins We use the following denominations: diff --git a/consensus/locking.md b/consensus/locking.md index 238a6fa4..76e9103e 100644 --- a/consensus/locking.md +++ b/consensus/locking.md @@ -1,8 +1,8 @@ # Coins locking -We want a predictable inflation so there MUST not be any token burning. In order +We want a predictable inflation so there MUST not be any coin burning. In order to achieve this whenever there is a need for coins burning, we are locking those excess coins. This leads to a deterministic total amount of coins and thus - to a predictable inflation. This works as sending all to be locked -coins to a predifined address that nobody has a private key for. Those tokens +coins to a predifined address that nobody has a private key for. Those coins are unspendable at this point. diff --git a/contracts/aevm.md b/contracts/aevm.md index 3a4ee510..64caf58c 100644 --- a/contracts/aevm.md +++ b/contracts/aevm.md @@ -23,9 +23,8 @@ Interaction with the first class objects of the æternity chain (e.g. oracles, names, and state channels) is done through calls to a built-in contract at address 0. - -The value in the call indicates the tokens that the primop can use from the contract account. -Unused tokens stay on the contract account. +The value in the call indicates the coins that the primop can use from the +contract account. Unused coins stay on the contract account. The first argument in the call specifies which primop to call. The following arguments are encoded as Sophia data. @@ -100,7 +99,7 @@ The byte code contains meta data for the contract. - byte_code - the actual byte code The layout of the encoding can be found -[here](https://github.com/aeternity/protocol/blob/master/serializations.md#sophia-byte-code). +[here](https://github.com/aeternity/protocol/blob/master/serializations.md#sophia-byte-code). The encoding is tagged with the compiler version. #### Type information @@ -294,7 +293,7 @@ The `CALL` instruction for calling another contract works differently for Sophia contracts than in the EVM. It expects on the stack (top to bottom): - `Gas` - the amount of gas to allocate to the call - `Address` - the address of the contract to call (or 0 for primops) -- `Amount` - the amount of tokens to transfer with the call +- `Amount` - the amount of coins to transfer with the call - `Calldata` - the calldata value (pair of function hash and arguments) - `TypeHash` - the function hash of primops that have dynamic types (e.g., oracles). Otherwise unused. diff --git a/contracts/contract_state_tree.md b/contracts/contract_state_tree.md index 5e71ee5b..269bd741 100644 --- a/contracts/contract_state_tree.md +++ b/contracts/contract_state_tree.md @@ -21,7 +21,7 @@ See [Contract Serialization](../serializations.md#contract) for the serializatio The contract also has a nonce and a balance recorded in an account state tree. A call to a contract can execute chain transactions and these transactions are allowed to spend -tokens from the balance of the contract. +coins from the balance of the contract. #### The contract definition diff --git a/contracts/fate.md b/contracts/fate.md index d5348379..186095ea 100644 --- a/contracts/fate.md +++ b/contracts/fate.md @@ -486,7 +486,7 @@ Writing to the accumulator pushes a value to the stack. | 'LOG2' | Arg0 Arg1 Arg2 | Create a log message with two topics in the call object. | {integer,integer,string} | none | | 'LOG3' | Arg0 Arg1 Arg2 Arg3 | Create a log message with three topics in the call object. | {integer,integer,integer,string} | none | | 'LOG4' | Arg0 Arg1 Arg2 Arg3 Arg4 | Create a log message with four topics in the call object. | {integer,integer,integer,integer,string} | none | -| 'SPEND' | Arg0 Arg1 | Transfer Arg1 tokens to account Arg0. (If the contract account has at least that many tokens. | {address,integer} | none | +| 'SPEND' | Arg0 Arg1 | Transfer Arg1 coinss to account Arg0. (If the contract account has at least that many coins. | {address,integer} | none | | 'ORACLE_REGISTER' | Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Arg6 | Arg0 := New oracle with address Arg2, query fee Arg3, TTL Arg4, query type Arg5 and response type Arg6. Arg0 contains delegation signature. | {signature,address,integer,variant,typerep,typerep} | oracle | | 'ORACLE_QUERY' | Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 Arg6 Arg7 | Arg0 := New oracle query for oracle Arg1, question in Arg2, query fee in Arg3, query TTL in Arg4, response TTL in Arg5. Typereps for checking oracle type is in Arg6 and Arg7. | {oracle,any,integer,variant,variant,typerep,typerep} | oracle_query | | 'ORACLE_RESPOND' | Arg0 Arg1 Arg2 Arg3 Arg4 Arg5 | Respond as oracle Arg1 to query in Arg2 with response Arg3. Arg0 contains delegation signature. Typereps for checking oracle type is in Arg4 and Arg5. | {signature,oracle,oracle_query,any,typerep,typerep} | none | diff --git a/node/api/README.md b/node/api/README.md index 5d8c20a9..83858fea 100644 --- a/node/api/README.md +++ b/node/api/README.md @@ -44,7 +44,7 @@ The æternity node exposes the following APIs: * [Encoding scheme for API identifiers](./api_encoding.md) * [Account management user API usage](./account_api_usage.md) -* [Spending tokens using user API](./spend_api_usage.md) +* [Spending coins using user API](./spend_api_usage.md) * [Oracle user API usage](./oracle_api_usage.md) * [Naming system API usage](./naming_system_api_usage.md) * [Contract API usage](./contract_api_usage.md) @@ -58,16 +58,16 @@ for managing state channels over WebSocket connections. The 'legacy' protocol wa ### Description -Channels provide means for off-chain transactions with functionality of on-chain dispute resolution. -Channels require persisted connections to æternity nodes. Each participant in -a channel uses one's own trusted node. For persistence of this connection, WebSockets -are used. -Channels have on-chain state that persists who the participants are and the -total amout of tokens put into the channel. -Each channel also has an off-chain state representing the latest distribution of the balance of the -channel. It can be updated - each new state is co-signed by both parties and only then it becomes the latest valid state of the -channel. At any point in time channel can be closed either unilaterally or -through mutual agreement. +Channels provide means for off-chain transactions with functionality of +on-chain dispute resolution. Channels require persisted connections to +æternity nodes. Each participant in a channel uses one's own trusted node. For +persistence of this connection, WebSockets are used. Channels have on-chain +state that persists who the participants are and the total amout of coins put +into the channel. Each channel also has an off-chain state representing the +latest distribution of the balance of the channel. It can be updated - each new +state is co-signed by both parties and only then it becomes the latest valid +state of the channel. At any point in time channel can be closed either +unilaterally or through mutual agreement. ### Connection diff --git a/node/api/account_api_usage.md b/node/api/account_api_usage.md index 4e4601cf..da4250fc 100644 --- a/node/api/account_api_usage.md +++ b/node/api/account_api_usage.md @@ -28,7 +28,7 @@ You shall read output like the following... ``` {"balance":80, "id":"ak_N1WLMewMQPUyQBdEhXRSYee84RQNKJrECwbbseMkNsZhv1X", "nonce":0} ``` -... or - if you do not have tokens yet e.g. because you have not yet mined a block successfully - the following: +... or - if you do not have any coins yet e.g. because you have not yet mined a block successfully - the following: ``` {"reason":"Account not found"} ``` diff --git a/node/api/channel_ws_api.md b/node/api/channel_ws_api.md index 63065ad8..6d18c9f8 100644 --- a/node/api/channel_ws_api.md +++ b/node/api/channel_ws_api.md @@ -36,9 +36,9 @@ Roles: | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | - | from | string | Participant's account to take tokens from | Yes | - | to | string | Participant's account to add tokens to | Yes | - | amount | integer | Amount of tokens to transfer | Yes | + | from | string | Participant's account to take coins from | Yes | + | to | string | Participant's account to add coins to | Yes | + | amount | integer | Amount of coins to transfer | Yes | | block_hash | string | The on-chain block hash to pin the off-chain environment | No | | meta | array of strings | Meta information about the update | No | @@ -253,7 +253,7 @@ Roles: | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | - | amount | integer | Amount of tokens to deposit in the channel | Yes | + | amount | integer | Amount of coins to deposit in the channel | Yes | | block_hash | string | The on-chain block hash to pin the off-chain environment | No | | fee | integer | The on-chain transaction fee to be used. If not provided the FSM picks a value for the client | No | | gas_price | integer | the gas_price to be used for the fee computation | No | @@ -402,7 +402,7 @@ Roles: | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | - | amount | integer | Amount of tokens to withdraw form the channel | Yes | + | amount | integer | Amount of coins to withdraw form the channel | Yes | | block_hash | string | The on-chain block hash to pin the off-chain environment | No | | fee | integer | The on-chain transaction fee to be used. If not provided the FSM picks a value for the client | No | | gas_price | integer | the gas_price to be used for the fee computation | No | @@ -602,7 +602,7 @@ Roles: | contract_id | contract id | contract to call | Yes | | call\_data | call data | call data | Yes | | abi\_version | integer | call abi version | Yes | - | amount | integer | amount of tokens to transfer to contract | Yes | + | amount | integer | amount of coins to transfer to contract | Yes | | block_hash | string | The on-chain block hash to pin the off-chain environment | No | | meta | array of strings | Meta information about the update | No | @@ -945,7 +945,7 @@ Roles: | contract_id | contract id | contract to call | Yes | | call\_data | call data | call data | Yes | | abi\_version | integer | call abi version | Yes | - | amount | integer | amount of tokens to transfer to contract | Yes | + | amount | integer | amount of coins to transfer to contract | Yes | | gas\_price | integer | the gas\_price to be used for the fee computation and the update execution | Yes | | gas | integer | gas limit, if not provided `1000000` is the default value | No | | nonce | integer | the nonce to be used in the transaction | No | @@ -955,7 +955,7 @@ Roles: { "jsonrpc": "2.0", "method": "channels.force_progress", - "params": { + "params": { "abi_version":1, "amount":10, "call_data":"cb_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACCzVg5SHSPanMS8lSeSX8SFfJMeAfEkyR6oKfQhD6XCTgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA5gCcXw==", @@ -986,7 +986,7 @@ Roles: | Name | Type | Description | Required | | ---- | ---- | ----------- | -------- | - | amount | integer | the tokens amount given to the off-chain contract | Yes | + | amount | integer | the coins amount given to the off-chain contract | Yes | | abi\_version | integer | abi version | Yes | | call\_data | integer | contract execution call data | Yes | | call\_stack | list | contract execution call stack | Yes | @@ -999,19 +999,19 @@ Roles: #### Example ```javascript -{ +{ "jsonrpc":"2.0", "method":"channels.sign.force_progress_tx", - "params":{ + "params":{ "channel_id":"ch_2FdiLKkRUdPw4oTRbB6i3M6pquogzWLABQjU373hizDbnD8gGC", - "data":{ + "data":{ "signed_tx":"tx_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", - "updates":[ - { + "updates":[ + { "abi_version":1, "amount":10, "call_data":"cb_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACCzVg5SHSPanMS8lSeSX8SFfJMeAfEkyR6oKfQhD6XCTgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA5gCcXw==", - "call_stack":[ + "call_stack":[ ], "caller_id":"ak_Vu1cGq2d3Dpo9gP7pVJc8KMubXr8PjuX51b4yyJmFDcXgTZxT", @@ -1057,7 +1057,7 @@ Roles: | contract_id | contract id | contract to call | Yes | | call\_data | call data | call data | Yes | | abi\_version | integer | call abi version | Yes | - | amount | integer | amount of tokens to transfer to contract | Yes | + | amount | integer | amount of coins to transfer to contract | Yes | | block_hash | string | The on-chain block hash to pin the off-chain environment | No | | meta | array of strings | Meta information about the update | No | @@ -1095,7 +1095,7 @@ Roles: | type | transaction type | Yes | The `info` values could be: - + * `"funding_signed"` - reported by the `initiator`, indicating that a `channel_create_tx` has been singly authenticated by the `initiator` client, and sent to the `responder` for co-signing. * `"funding_created"` - reported by the `responder`, indicating that a `channel_create_tx` has been @@ -1783,12 +1783,12 @@ If the abort of the update is successful, the client that aborted receives a message for it: ```javascript -{ +{ "jsonrpc":"2.0", "method":"channels.info", - "params":{ + "params":{ "channel_id":"ch_95YaTDZAysRu3GkmW2yKkCK1H4fGtcttoj2qwFDfUSduTpCPf", - "data":{ + "data":{ "event":"aborted_update" } }, diff --git a/node/api/channels_api_usage.md b/node/api/channels_api_usage.md index 53826f7a..29adbc53 100644 --- a/node/api/channels_api_usage.md +++ b/node/api/channels_api_usage.md @@ -181,8 +181,8 @@ will describe these in groups which indicate their relation to each other. | responder_id | string | responder's public key | Yes | No | Yes | | lock_period | integer | amount of blocks for disputing a solo close | Yes | No | Yes | | push_amount | integer | initial deposit in favour of the responder by the initiator | Yes | No | No | - | initiator_amount | integer | amount of tokens the initiator has committed to the channel | Yes | No | Yes | - | responder_amount | integer | amount of tokens the responder has committed to the channel | Yes | No | Yes | + | initiator_amount | integer | amount of coins the initiator has committed to the channel | Yes | No | Yes | + | responder_amount | integer | amount of coins the responder has committed to the channel | Yes | No | Yes | | channel_reserve | integer | the minimum amount both peers need to maintain | Yes | No | Yes | | ttl | integer | maximum height of a block to include the `channel_create_tx` | No | No | Yes | | host | string | host of the `responder`'s node| Yes if `role=initiator` | No | No | No | @@ -200,7 +200,7 @@ will describe these in groups which indicate their relation to each other. responders. If the `responder` sets `initiator_id` to `"any"`, the responder will accept a connection request from any initiator, and fetch the proper `initiator_id` from the `channel_open` message. - + Once established, the channel follows a [predefined set of state transitions](/channels/README.md#overview). The implementation protects the client from edge cases when transitions take too long or never happen using @@ -909,7 +909,7 @@ Example: ``` ### Transfer -The transfer update is moving tokens from one channel account to another. The update is a change to be applied on top of the latest state. It has the +The transfer update is moving coins from one channel account to another. The update is a change to be applied on top of the latest state. It has the following structure: | Name | Type | Description | @@ -975,7 +975,7 @@ The starter sends a message containing the desired change ``` The `starter` might take the role of `from` or `to` so the `starter` can -trigger sending or request for tokens. +trigger sending or request for coins. ##### Starter authenticates updated state The starter receives a message containing the updated channel state as an @@ -1140,7 +1140,7 @@ following structure: | call_data | string | api encoded compiled AEVM call data for the code | That would create a contract with the poster being the `owner` of it. Poster -commits initially a `deposit` amount of tokens to the new contract. +commits initially a `deposit` amount of coins to the new contract. #### Start create contract update ##### Trigger a create contract update @@ -1295,7 +1295,7 @@ following structure. | call_data | string | ABI encoded compiled AEVM call data for the code | That would call a contract with the poster being the `caller_id` of it. Poster -commits an `amount` amount of tokens to the contract. +commits an `amount` amount of coins to the contract. The call would also create a `call` object inside the channel state tree. It contains the result of the contract call. @@ -1610,8 +1610,8 @@ chain and has the following structure: | ---- | ---- | ----------- | | channel id | string | ID of the channel| | from | string | initiator's public key | - | initiator_amount_final | integer | final amount of tokens to be awarded by the initiator | - | responder_amount_final | integer | final amount of tokens to be awarded by the responder | + | initiator_amount_final | integer | final amount of coins to be awarded by the initiator | + | responder_amount_final | integer | final amount of coins to be awarded by the responder | | ttl | integer | maximum block height to include the transaction | | fee | integer | fee to be paid to the miner | | gas_price | integer | the gas_price to be used for the fee computation | @@ -1868,7 +1868,7 @@ from being cheated by simply providing a co-authenticated off-chain state with a higher round. This is done via the `channel_slash_tx` transaction. Since a co-authenticated off-chain state has a higher priority than an -unilaterally on-chain produced one via a `channel_force_progress_tx` transaction, +unilaterally on-chain produced one via a `channel_force_progress_tx` transaction, a `channel_slash_tx` transaction can invalidate a whole chain of `channel_force_progress_tx` transactions if the first one of them had been based on a channel state that is older than the one provided by the `channel_slash_tx` @@ -1913,7 +1913,7 @@ the channel has now entered a closing state: "method": "channels.info", "params": { "channel_id": "ch_Et72swxcKCAJ8KzUDm17X1Ukuo6W7516WfYDPdUoTYpArCdfQ", - "data": + "data": "event": "closing" } }, @@ -2190,12 +2190,12 @@ the WebSocket connection: #### Update error Newly requested updates are not always successful. For example one participant -tries to spend more tokens that one currently has in the channel's balance. +tries to spend more coins than one currently has in the channel's balance. Another would be a participant initiating an update while the other participant had already proposed a different one. This diverges from the update flow [described above](#channel-off-chain-update). -Example message for when the `from` does not have enough tokens to spend +Example message for when the `from` does not have enough coins to spend ```javascript { "channel_id": "ch_zVDx935M1AogqZrNmn8keST2jH8uvn5kmWwtDqefYXvgcCRAX", @@ -2227,9 +2227,9 @@ Example message for when the `from` does not have enough tokens to spend The structure is having a `reason` and `request` holding the request being sent. Possible error reasons are: -* `Insufficient balance` - when `from` does not have enough tokens in the +* `Insufficient balance` - when `from` does not have enough coins in the channel. Keep in mind that there is a minimal amount of `channel_reserve` - tokens to be kept by both parties. + coins to be kept by both parties. * `Negative amount` - the `udpate` event contained a negative amount @@ -2338,12 +2338,12 @@ instead. The response the client receives in that case is: ```javascript -{ +{ "jsonrpc":"2.0", "method":"channels.info", - "params":{ + "params":{ "channel_id":"ch_95Ya...", - "data":{ + "data":{ "event":"aborted_update" } }, @@ -2443,7 +2443,7 @@ details: #### Total balance update events -After the channel has been opened it has a total balance of tokens committed to +After the channel has been opened it has a total balance of coins committed to it. This balance is persisted as part of the on-chain channel state. Upon closing a channel on-chain, the closing balances of the participants are checked against this balance. Under no circumstances can the sum of the closing balances @@ -2451,9 +2451,9 @@ be greater than the total balance on-chain. Participants are able to modify the total balance: the following two functionalities are available: -* deposit - when a participant wants to commit more tokens from his on-chain +* deposit - when a participant wants to commit more coins from his on-chain balance to the channel total balance -* withdrawal - when a participant wants to transfer tokens out of the channel +* withdrawal - when a participant wants to transfer coins out of the channel on-chain balance to one's personal account ### Deposit events @@ -2463,8 +2463,8 @@ deposit. The process closely resembles the [update](#update). The most notable difference is the transaction has been mutually authenticated: it is `channel_deposit_tx` and after the procedure is finished, it is posted on-chain. -Since both the initiator and responder can deposit tokens, in the scope of this description we -will call the participant that commits tokens to the channel a depositor and +Since both the initiator and responder can deposit coins, in the scope of this description we +will call the participant that commits coins to the channel a depositor and the other party - acknowledger. Note that any public key outside of the channel participants is considered invalid for the depositor role. @@ -2658,8 +2658,8 @@ withdrawal. The process closely resembles the [update](#update). The most notabl difference is that the transaction has been mutually authenticated: it is `channel_withdraw_tx` and after the procedure is finished - it is being posted on-chain. -Since both the initiator and responder can withdraw tokens, in the scope of this description we -will call the participant that commits tokens to the channel a withdrawer and +Since both the initiator and responder can withdraw coins, in the scope of this description we +will call the participant that commits coins to the channel a withdrawer and the other party - an acknowledger. Note that any public key outside of the channel participants is considered invalid for the withdrawer role. @@ -3283,7 +3283,7 @@ it is time to finally close the channel. One of the participants posts a `channel_settle_tx` transaction that enforces closing of the channel. This happens according to the latest channel state that was sent on-chain. The `channel_settle_tx` just finalizes the channel closing with the last received -state, redistributes tokens to participants and closes the channel. No further +state, redistributes coins to participants and closes the channel. No further disputes are possible after that. @@ -3411,7 +3411,7 @@ dispute the malicious on-chain transaction. } ``` -#### Snapshotter inittiates a snapshot solo +#### Snapshotter inittiates a snapshot solo If the channel is in an `open` state, any participant can initiate a solo snapshot transaction by: @@ -3423,7 +3423,7 @@ snapshot transaction by: "params": {} } ``` -#### Snapshotter authenticates the snapshot solo +#### Snapshotter authenticates the snapshot solo After the `channel_snapshot_solo_tx` has been requested, the FSM prompts the client to sign it with: @@ -3545,19 +3545,19 @@ After the `channel_force_progress_tx` has been requested, the FSM prompts the client to sign it with: ```javascript -{ +{ "jsonrpc":"2.0", "method":"channels.sign.force_progress_tx", - "params":{ + "params":{ "channel_id":"ch_2FdiLKkRUdPw4oTRbB6i3M6pquogzWLABQjU373hizDbnD8gGC", - "data":{ + "data":{ "signed_tx":"tx_+Qi9CwHAuQ....", - "updates":[ - { + "updates":[ + { "abi_version":1, "amount":10, "call_data":"cb_AAAAAAA...", - "call_stack":[ + "call_stack":[ ], "caller_id":"ak_Vu1cG...", diff --git a/node/api/spend_api_usage.md b/node/api/spend_api_usage.md index 3761a008..fadacbd2 100644 --- a/node/api/spend_api_usage.md +++ b/node/api/spend_api_usage.md @@ -1,15 +1,15 @@ -# Spending tokens - intended usage +# Spending coins - intended usage The following assumes that the node exposes at address 127.0.0.1 the following ports: * User API internal HTTP endpoint: 3113 -## Send tokens to another account +## Send coins to another account -In order to send tokens, you need to have tokens i.e. a positive (non-zero) balance. -You obtain tokens e.g. after having mined successfully a block or received tokens through a transaction. +In order to send coins, you need to have coins i.e. a positive (non-zero) balance. +You obtain coins e.g. after having mined successfully a block or received coins through a transaction. -In order to transfer tokens from an account (`sender_id`) to another account (`recipient_id`): +In order to transfer coins from an account (`sender_id`) to another account (`recipient_id`): * prepare spend transaction as per [specification](../../serializations.md). In order to ease the initial integration, the æternity node provides [/debug/transactions/spend endpoint](https://api-docs.aeternity.io#/internal/PostSpend)): ``` bash @@ -22,13 +22,13 @@ curl -X POST -H "Content-Type: application/json" -d '{"sender_id":"...", "recipi Once the transaction is included in a block, the recipient shall receive the specified amount and the miner that specified fee. The `ttl` has to reflect the current height of the chain, it specify at what height the transaction expire and can't be included on the chain. -## Notes on testing spending tokens +## Notes on testing spending coins -The simplest way for testing sending tokens is setting up a local network of two nodes - disconnected from the testnet. -The reason is that in order to spend tokens from your account you need to obtain tokens in the first place, and in order to obtain tokens you need to mine a block faster than all other miners in the network. -Testing spending tokens in a local network enables obtaining tokens without competing with other miners. +The simplest way for testing sending coins is setting up a local network of two nodes - disconnected from the testnet. +The reason is that in order to spend coins from your account you need to obtain coins in the first place, and in order to obtain coins you need to mine a block faster than all other miners in the network. +Testing spending coins in a local network enables obtaining coins without competing with other miners. -At least one of the two nodes needs to mine - in order to have tokens to spend. +At least one of the two nodes needs to mine - in order to have coins to spend. At least one of the two nodes needs to be configured with the peer address of the other node in order for them to form a network.