Protocol /
AccountsWorkPage
Protocol.AccountsWorkPage History
Hide minor edits - Show changes to output
Changed lines 3-19 from:
* close account
--------------------------
[[#verify-account]]
'''Verifying Account Data'''
Send a @@verify-account@@ message to which the reply contains:
* account balance
* units of account
* credit limit for each node
* routing information for each node
Especially important to verify is the balance. If there are discrepancies, they will have to be worked out between the node owners. In future it may be possible to compare payments receipt-by-receipt to find the source of the discrepancy.
*** Also: Complete audit of every message in account history
--------------------------
[[#verify-account]]
'''Verifying Account Data'''
Send a @@verify-account@@ message to which the reply contains:
* account balance
* units of account
* credit limit for each node
* routing information for each node
Especially important to verify is the balance. If there are discrepancies, they will have to be worked out between the node owners. In future it may be possible to compare payments receipt-by-receipt to find the source of the discrepancy.
*** Also: Complete audit of every message in account history
to:
* specify close account error messages
Changed lines 7-188 from:
!! Accounts
An account is a mutual-credit connection between two nodes defined by the following data, a copy of which is kept by the node of each account partner.
Required data:
* an account ID, which serves as a permanent identifier for the account
* each node's ID
* the unit of account (see Units of Account)
* the number of decimal digits with which to keep this account
* a credit limit for each node
* a balance for the account
* each node's routing information (see Query Routing)
* an authentication key for each node (see Authentication Keys)
Optional data:
* interest rate, as a decimal
* compounding period, in days
* account agreement, possibly including debt-settlement terms/schedule
Example:
[@
{
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay the outstanding balance in cash on demand.",
}
@]
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data. The roles of "initiator" node and "partner" node are determined at account creation time, with the node making the initial account offer being deemed the "initiator". These roles stay constant for the life of the account, allowing either node to its node ID.
The balance field may appear in either the "initiator" or "partner" node object, and gives the balance from that node's perspective (negative means owing, positive means owed).
Custom data fields may be added to an account as long as their meaning is understood by both nodes.
Generally a node will want to keep a record of all messages necessary to calculate the current balance on the account, including transaction receipts and changes to the account.
[[#account-data-ownership]]
'''Account Data Ownership'''
While both nodes must store all shared account data, certain fields will conventionally be owned or controlled by one node or the other. Specifically, each node generally solely owns its own "node_id", "routing_id", "key", and the other node's "limit". Ownership of all other fields is generally shared. Other arrangements are possible, though they are not communicated explicitly. Instead, ownership is negotiated through account messages and their responses.
Ownership decides the semantics of changing the value of an account field.
[[#account-messages]]
'''Account Messages'''
There are two account messages: @@account_request@@ and @@account_set@@.
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership. An @@account_request@@ must be signed unless it only contains account fields that are solely owned by the receiving node. If a node does not feel it is the sole owner of all account fields in an unsigned @@account-request@@ it received, it should reply with a ''Message must be signed'' error. (Every owner of a field must sign off on changes to it.) An implementation may decide to simply sign every @@account-request@@.
[@
{
"account_request": {
"request_id": (integer),
"account": {
"account_id": (string),
(remaining account data structure containing requested field values)
},
["note": (string explaining request)]
}
}
@]
To avoid overlap, the "initiator" node uses odd request IDs, and the "partner" node uses even request IDs. Only those account fields that contain new, non-default values, or are to be changed need to be included.
The @@account_set@@ message is to confirm a new account, accept the changes requested in an @@account_request@@, or to declare changes to fields over which a node has sole ownership. An @@account_set@@ must always be signed.
[@
{
"account_set": {
["request_id": (integer),]
"timestamp": (string with format "2006-11-01 15:02:48.780000"),
"account": {
"account_id": (string),
(remaining account data structure containing requested field values)
},
}
}
@]
The request ID is only necessary when the @@account_set@@ refers to an earlier request. In that case, the account fields must be identical to those in the earlier @@account-request@@ with the same request ID.
The timestamp establishes the exact time, measured in [[connection time -> Protocol/Host-LevelMessages#connection-time]], that the changes to the account fields take effect.
Account messages, other than at account-creation time, should only alter one account field at a time unless two or more fields must be altered in atomic fashion.
[[#creating-an-account]]
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with a signed @@account_request@@ message containing:
* a request ID
* an account ID
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* any other optional data fields desired for this account
[@
{
"account_request": {
"request_id": 1,
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200,
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
},
"note": "Let's have an account!"
}
}
@]
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#changing-account-data]]
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner. An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed. An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need not contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account_set@@ completes the change.
Case-specific errors:
: ''Field change by account_request only'' : Contains path to field that node receiving an @@account_set@@ deems requires an @@account_request@@ to change, ie, that it owns or shares ownership of the field in question.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change, ie, that it does not own the field in question. This error should not be used when the message received contains at least one field that does properly require an @@account_request@@ message.
The account messages, combined with the above two errors, allow nodes to negotiate ownership of account data fields when it differs from convention.
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account_set@@ or @@account_request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
[[#changing-keys]]
'''Changing Keys'''
A
to:
[[#verify-account]]
'''Verifying Account Data'''
Send a @@verify-account@@ message to which the reply contains:
* account balance
* units of account
* credit limit for each node
* routing information for each node
Especially important to verify is the balance. If there are discrepancies, they will have to be worked out between the node owners. In future it may be possible to compare payments receipt-by-receipt to find the source of the discrepancy.
*** Also: Complete audit of every message in account history
'''Verifying Account Data'''
Send a @@verify-account@@ message to which the reply contains:
* account balance
* units of account
* credit limit for each node
* routing information for each node
Especially important to verify is the balance. If there are discrepancies, they will have to be worked out between the node owners. In future it may be possible to compare payments receipt-by-receipt to find the source of the discrepancy.
*** Also: Complete audit of every message in account history
Changed lines 77-78 from:
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership. Except when creating a new account, an @@account_request@@ does not have to be signed.
to:
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership. An @@account_request@@ must be signed unless it only contains account fields that are solely owned by the receiving node. If a node does not feel it is the sole owner of all account fields in an unsigned @@account-request@@ it received, it should reply with a ''Message must be signed'' error. (Every owner of a field must sign off on changes to it.) An implementation may decide to simply sign every @@account-request@@.
Added lines 113-114:
Account messages, other than at account-creation time, should only alter one account field at a time unless two or more fields must be altered in atomic fashion.
Changed lines 174-177 from:
: ''Field change by account_request only'' : Contains path to field that node receiving an @@account_set@@ deems requires an @@account_request@@ to change.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change.
: ''Field change by account_set only'' : Contains path to
to:
: ''Field change by account_request only'' : Contains path to field that node receiving an @@account_set@@ deems requires an @@account_request@@ to change, ie, that it owns or shares ownership of the field in question.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change, ie, that it does not own the field in question. This error should not be used when the message received contains at least one field that does properly require an @@account_request@@ message.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change, ie, that it does not own the field in question. This error should not be used when the message received contains at least one field that does properly require an @@account_request@@ message.
Changed lines 183-188 from:
To add a new data field to an account, use @@account_set@@ or @@account_request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
to:
To add a new data field to an account, use @@account_set@@ or @@account_request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
[[#changing-keys]]
'''Changing Keys'''
A
[[#changing-keys]]
'''Changing Keys'''
A
Changed lines 75-78 from:
There are two account messages: @@account_request@@ and @@account_set@@:
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership.
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership.
to:
There are two account messages: @@account_request@@ and @@account_set@@.
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership. Except when creating a new account, an @@account_request@@ does not have to be signed.
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership. Except when creating a new account, an @@account_request@@ does not have to be signed.
Changed lines 94-95 from:
The @@account_set@@ message is to confirm a new account, accept the changes requested in an @@account_request@@, or to declare changes to fields over which a node has sole ownership.
to:
The @@account_set@@ message is to confirm a new account, accept the changes requested in an @@account_request@@, or to declare changes to fields over which a node has sole ownership. An @@account_set@@ must always be signed.
Changed line 100 from:
"timestamp": (string containing date and time),
to:
"timestamp": (string with format "2006-11-01 15:02:48.780000"),
Changed lines 116-117 from:
Accounts are created by one node offering to accept another's IOUs with an @@account_request@@ message containing:
to:
Accounts are created by one node offering to accept another's IOUs with a signed @@account_request@@ message containing:
Changed lines 157-160 from:
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a new timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply.The reply may also be an error code, in which case the account is not created.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply.
to:
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#changing-account-data]]
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. If the reply is an error, the account is not created.
[[#changing-account-data]]
Changed lines 164-182 from:
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
[@
{
"account_set": {
"timestamp": "2006-11-01 15:02:48.780000",
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
[JSON structure of fields to be changed]
}
}
}
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
[@
{
"
"timestamp": "2006-11-01 15:02:48.780000"
[JSON structure of fields to be changed]
}
}
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection
to:
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner. An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed. An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need not contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account_set@@ completes the change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed. An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need not contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the account fields and values and request ID from the @@account-request@@. An affirmative reply to the @@account_set@@ completes the change.
Changed lines 172-185 from:
: ''Field change by request only'' : Returns path to field that node receiving an @@account_set@@ deems requires a request to change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed, containing:
*account ID
* time & date for the change to take effect (optional)
* the fields to be changed, with their new values
* an explanatory note
An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply neednot contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the request-message contents. A signed affirmative reply containing the contents of the original request-message from the request originator completes the change. Having the request originator confirm the change at this point allows them final control over implementing the change (who knows what may have happened in the delay between request and approval) and maintains consistent semantics for the @@account-set@@ message.
*** Adding new fields
*
* time & date for the change to take effect (optional)
* the fields to be changed, with their new values
* an explanatory note
An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the request-message contents
*** Adding new fields
to:
: ''Field change by account_request only'' : Contains path to field that node receiving an @@account_set@@ deems requires an @@account_request@@ to change.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change.
The account messages, combined with the above two errors, allow nodes to negotiate ownership of account data fields when it differs from convention.
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account_set@@ or @@account_request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
: ''Field change by account_set only'' : Contains path to field that node receiving an @@account_request@@ deems requires a @@account_set@@ to change.
The account messages, combined with the above two errors, allow nodes to negotiate ownership of account data fields when it differs from convention.
[[#adding-new-fields]]
'''Adding New Fields'''
To add a new data field to an account, use @@account_set@@ or @@account_request@@ as appropriate. If the other node does not understand the field, it will reply with an error, and the field may not be added.
Changed lines 57-58 from:
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data. The roles of "initiator" node and "partner" node are determined at account creation time, with the node making the initial account offer being deemed the "initiator".
to:
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data. The roles of "initiator" node and "partner" node are determined at account creation time, with the node making the initial account offer being deemed the "initiator". These roles stay constant for the life of the account, allowing either node to its node ID.
Added lines 65-71:
[[#account-data-ownership]]
'''Account Data Ownership'''
While both nodes must store all shared account data, certain fields will conventionally be owned or controlled by one node or the other. Specifically, each node generally solely owns its own "node_id", "routing_id", "key", and the other node's "limit". Ownership of all other fields is generally shared. Other arrangements are possible, though they are not communicated explicitly. Instead, ownership is negotiated through account messages and their responses.
Ownership decides the semantics of changing the value of an account field.
'''Account Data Ownership'''
While both nodes must store all shared account data, certain fields will conventionally be owned or controlled by one node or the other. Specifically, each node generally solely owns its own "node_id", "routing_id", "key", and the other node's "limit". Ownership of all other fields is generally shared. Other arrangements are possible, though they are not communicated explicitly. Instead, ownership is negotiated through account messages and their responses.
Ownership decides the semantics of changing the value of an account field.
Changed lines 75-91 from:
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with an @@account_request@@ message containing:
* a request ID
* an account ID
* timestamp
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* some explanatory text to the recipient
* any other optional or custom data desired
to:
There are two account messages: @@account_request@@ and @@account_set@@:
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership.
An @@account_request@@ is to request a new account, or to request a change in value to fields over which a node does not have sole ownership.
Changed lines 82-84 from:
"request_id": 1,
"timestamp": "2006-10-23 11:01:11.145000",
"timestamp": "2006-10-23 11:01:11.145000",
to:
"request_id": (integer),
Changed lines 84-99 from:
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200,
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200,
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
to:
"account_id": (string),
(remaining account data structure containing requested field values)
(remaining account data structure containing requested field values)
Changed lines 87-88 from:
to:
["note": (string explaining request)]
Changed lines 92-103 from:
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. The reply may also be an error code, in which case the account is not created
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
to:
To avoid overlap, the "initiator" node uses odd request IDs, and the "partner" node uses even request IDs. Only those account fields that contain new, non-default values, or are to be changed need to be included.
The @@account_set@@ message is to confirm a new account, accept the changes requested in an @@account_request@@, or to declare changes to fields over which a node has sole ownership.
The @@account_set@@ message is to confirm a new account, accept the changes requested in an @@account_request@@, or to declare changes to fields over which a node has sole ownership.
Changed lines 99-100 from:
"timestamp": "2006-11-01 15:02:48.780000",
to:
["request_id": (integer),]
"timestamp": (string containing date and time),
"timestamp": (string containing date and time),
Changed lines 102-104 from:
"account_id": "550e8400-e29b-41d4-a716-446655440000",
[JSON structure of fields to be changed]
}
to:
"account_id": (string),
(remaining account data structure containing requested field values)
},
(remaining account data structure containing requested field values)
},
Changed lines 107-115 from:
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
Case-specific errors:
: ''Field change by request only'' : Returns path to field that node receiving an @@account_set@@ deems requires a request to change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed, containing:
to:
@]
The request ID is only necessary when the @@account_set@@ refers to an earlier request. In that case, the account fields must be identical to those in the earlier @@account-request@@ with the same request ID.
The timestamp establishes the exact time, measured in [[connection time -> Protocol/Host-LevelMessages#connection-time]], that the changes to the account fields take effect.
[[#creating-an-account]]
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with an @@account_request@@ message containing:
* a request ID
* an account ID
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* any other optional data fields desired for this account
[@
{
"account_request": {
"request_id": 1,
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200,
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
},
"note": "Let's have an account!"
}
}
@]
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a new timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. The reply may also be an error code, in which case the account is not created.
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner containing:
The request ID is only necessary when the @@account_set@@ refers to an earlier request. In that case, the account fields must be identical to those in the earlier @@account-request@@ with the same request ID.
The timestamp establishes the exact time, measured in [[connection time -> Protocol/Host-LevelMessages#connection-time]], that the changes to the account fields take effect.
[[#creating-an-account]]
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with an @@account_request@@ message containing:
* a request ID
* an account ID
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* any other optional data fields desired for this account
[@
{
"account_request": {
"request_id": 1,
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200,
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
},
"note": "Let's have an account!"
}
}
@]
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a new timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. The reply may also be an error code, in which case the account is not created.
'''Changing Account Data'''
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner containing:
Changed line 166 from:
* time & date for the change to take effect (optional)
to:
* time & date for the change to take effect
Added lines 168-190:
[@
{
"account_set": {
"timestamp": "2006-11-01 15:02:48.780000",
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
[JSON structure of fields to be changed]
}
}
}
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
Case-specific errors:
: ''Field change by request only'' : Returns path to field that node receiving an @@account_set@@ deems requires a request to change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed, containing:
* account ID
* time & date for the change to take effect (optional)
* the fields to be changed, with their new values
Changed lines 7-9 from:
''Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.''
to:
''Ryan: Here's an update I'm working on. Still not sure about allowing changes to multiple fields in a single account_set/request.''
Added line 21:
* a balance for the account
Changed lines 38-50 from:
"nodes": [
{
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here]
}, {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
}
]
to:
"initiator": {
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
},
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here],
"balance": -15.50
},
"partner": {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
},
Changed lines 57-58 from:
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data.
to:
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data. The roles of "initiator" node and "partner" node are determined at account creation time, with the node making the initial account offer being deemed the "initiator".
The balance field may appear in either the "initiator" or "partner" node object, and gives the balance from that node's perspective (negative means owing, positive means owed).
The balance field may appear in either the "initiator" or "partner" node object, and gives the balance from that node's perspective (negative means owing, positive means owed).
Changed lines 63-66 from:
Generally a node will keep a record of all messages necessary to calculate the current balance on the account, including transaction receipts and changes to the account.
Unless otherwise specified, all account messages must be signed by the sender's authentication key.
to:
Generally a node will want to keep a record of all messages necessary to calculate the current balance on the account, including transaction receipts and changes to the account.
[[#account-messages]]
'''Account Messages'''
[[#creating-an-account]]
[[#account-messages]]
'''Account Messages'''
[[#creating-an-account]]
Changed lines 71-72 from:
Accounts are created by one node offering to accept another's IOUs with an @@offer@@ message containing:
to:
Accounts are created by one node offering to accept another's IOUs with an @@account_request@@ message containing:
Changed lines 87-88 from:
"offer": {
"request_id":16903,
"request_id":
to:
"account_request": {
"request_id": 1,
"request_id": 1,
Changed lines 90-94 from:
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"nodes": [
{
"unit": "urn:ripple:units:CAD",
"precision": 4,
"
to:
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"initiator": {
Changed lines 99-101 from:
to:
"balance": -15.50
},
"partner": {
},
"partner": {
Changed lines 104-108 from:
}
]
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand.",
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand.",
to:
},
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
},
"note": "Let's have an account!"
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand."
},
"note": "Let's have an account!"
Changed lines 115-124 from:
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account-create@@ with the full account data structure.
To indicate that the account has been created, the node receiving the @@account-create@@ responds with an affirmative reply. The reply may also be an error with one of the following error codes indicating why the account has not been created:
* incorrect account ID
* offer withdrawn
* unsupported field
Otherwise it sends an @@offer-reject@@ message.
To indicate that the account has been created
* incorrect account ID
* offer withdrawn
* unsupported field
Otherwise it sends an @@offer-reject@@ message
to:
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account_set@@ echoing the request ID and the full account data structure in the request, as well as a new timestamp which is the official account creation time.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. The reply may also be an error code, in which case the account is not created.
To indicate that the account has been created, the node receiving the @@account_set@@ responds with an affirmative reply. The reply may also be an error code, in which case the account is not created.
Changed lines 121-124 from:
To declare a change to one or more account data fields, a node sends a signed @@account-
to:
To declare a change to one or more account data fields, a node sends a signed @@account_set@@ message to its account partner containing:
Changed lines 127-130 from:
To request a change to one or more account data fields, a node sends an @@account-request@@
to:
[@
{
"account_set": {
"timestamp": "2006-11-01 15:02:48.780000",
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
[JSON structure of fields to be changed]
}
}
}
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
Case-specific errors:
: ''Field change by request only'' : Returns path to field that node receiving an @@account_set@@ deems requires a request to change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed, containing:
{
"account_set": {
"timestamp": "2006-11-01 15:02:48.780000",
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
[JSON structure of fields to be changed]
}
}
}
An affirmative reply by the other node indicates acceptance of those changes. An error indicates rejection.
Case-specific errors:
: ''Field change by request only'' : Returns path to field that node receiving an @@account_set@@ deems requires a request to change.
To request a change to one or more account data fields, a node sends an @@account_request@@ message, which need not be signed, containing:
Changed line 147 from:
* time & date for the change to take effect
to:
* time & date for the change to take effect (optional)
Changed lines 81-98 from:
<
<timestamp>2006-10-23 11
<account id=
<unit>urn
<digits>4</digits>
<node id=
<routing
<key>...</key>
</node>
<node id=
<limit>200</limit>
</node>
<interest_rate>0.05</interest_rate>
<compound_period>0</compound_period>
<agreement>Both parties agree to pay any outstanding balance in cash on demand
</account>
</offer>
to:
{
"offer": {
"request_id": 16903,
"timestamp": "2006-10-23 11:01:11.145000",
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"nodes": [
{
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
}, {
"node_id": "random@example.com",
"limit": 200,
}
]
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand.",
}
}
"offer": {
"request_id": 16903,
"timestamp": "2006-10-23 11:01:11.145000",
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"nodes": [
{
"node_id": "rfugger@ripplepay.com",
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [key info here],
}, {
"node_id": "random@example.com",
"limit": 200,
}
]
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay any outstanding balance in cash on demand.",
}
}
Changed lines 111-113 from:
* unrecognized field
*
to:
* unsupported field
Changed lines 32-51 from:
<
<digits>
<node>
<
<
<
</node>
<node>
<node_id>random@example.com</node_id>
<limit>200</limit>
<routing
<key>
</node>
<interest
<compound_period>0</compound_period>
<agreement>Both parties agree to pay the outstanding balance in cash on demand
</account>
to:
{
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"nodes": [
{
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here]
}, {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
}
]
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay the outstanding balance in cash on demand.",
}
"account": {
"account_id": "550e8400-e29b-41d4-a716-446655440000",
"unit": "urn:ripple:units:CAD",
"precision": 4,
"nodes": [
{
"node_id": "rfugger@ripplepay.com",
"limit": 100.0000,
"routing_id": "7136976c-251d-4be4-b6e2-74baf4b4a53c",
"key": [public key info here]
}, {
"node_id": "random@example.com",
"limit": 200.0000,
"routing_id": "d699c900-b245-4e3d-a586-eb5743fa24af",
"key": [public key info here]
}
]
"interest_rate": 0.05,
"compound_period": 0,
"agreement": "Both parties agree to pay the outstanding balance in cash on demand.",
}
Changed lines 56-57 from:
The XML structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data.
to:
The JSON structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data.
Changed lines 5-10 from:
----
Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.
----
Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.
----
to:
--------------------------
''Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.''
''Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.''
Added lines 1-6:
'''To Do'''
* close account
----
* close account
----
Changed lines 9-10 from:
to:
----
Changed lines 74-76 from:
<offer request_id="16093">
<timestamp>2006-10-23 11:01:11.145000</timestamp>
<account id="550e8400-e29b-41d4-a716-446655440000">
to:
<offer>
<request_id>16093</request_id>
<timestamp>2006-10-23 11:01:11.145000</timestamp>
<account id="550e8400-e29b-41d4-a716-446655440000">
<request_id>16093</request_id>
<timestamp>2006-10-23 11:01:11.145000</timestamp>
<account id="550e8400-e29b-41d4-a716-446655440000">
Changed line 85 from:
to:
<limit>200</limit>
Added lines 1-127:
Ryan: Here's an update I'm working on. Still not sure about making the requesting node echo back data they've already sent -- I'll probably take that out.
----------------------
!! Accounts
An account is a mutual-credit connection between two nodes defined by the following data, a copy of which is kept by the node of each account partner.
Required data:
* an account ID, which serves as a permanent identifier for the account
* each node's ID
* the unit of account (see Units of Account)
* the number of decimal digits with which to keep this account
* a credit limit for each node
* each node's routing information (see Query Routing)
* an authentication key for each node (see Authentication Keys)
Optional data:
* interest rate, as a decimal
* compounding period, in days
* account agreement, possibly including debt-settlement terms/schedule
Example:
[@
<account>
<account_id>550e8400-e29b-41d4-a716-446655440000</account_id>
<unit>urn:ripple:units:CAD</unit>
<digits>4</digits>
<node>
<node_id>rfugger@ripplepay.com</node_id>
<limit>100</limit>
<routing_id>7136976c-251d-4be4-b6e2-74baf4b4a53c</routing_id>
<key>...</key>
</node>
<node>
<node_id>random@example.com</node_id>
<limit>200</limit>
<routing_id>d699c900-b245-4e3d-a586-eb5743fa24af</routing_id>
<key>...</key>
</node>
<interest_rate>0.05</interest_rate>
<compound_period>0</compound_period>
<agreement>Both parties agree to pay the outstanding balance in cash on demand.</agreement>
</account>
@]
The XML structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data.
Custom data fields may be added to an account as long as their meaning is understood by both nodes.
Generally a node will keep a record of all messages necessary to calculate the current balance on the account, including transaction receipts and changes to the account.
Unless otherwise specified, all account messages must be signed by the sender's authentication key.
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with an @@offer@@ message containing:
* a request ID
* an account ID
* timestamp
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* some explanatory text to the recipient
* any other optional or custom data desired
[@
<offer request_id="16093">
<timestamp>2006-10-23 11:01:11.145000</timestamp>
<account id="550e8400-e29b-41d4-a716-446655440000">
<unit>urn:ripple:units:CAD</unit>
<digits>4</digits>
<node id="rfugger@ripplepay.com">
<routing_id>7136976c-251d-4be4-b6e2-74baf4b4a53c</routing_id>
<key>...</key>
</node>
<node id="random@example.com">
<limit>200</limit>
</node>
<interest_rate>0.05</interest_rate>
<compound_period>0</compound_period>
<agreement>Both parties agree to pay any outstanding balance in cash on demand.</agreement>
</account>
</offer>
@]
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account-create@@ with the full account data structure.
To indicate that the account has been created, the node receiving the @@account-create@@ responds with an affirmative reply. The reply may also be an error with one of the following error codes indicating why the account has not been created:
* incorrect account ID
* offer withdrawn
* unrecognized field
*
Otherwise it sends an @@offer-reject@@ message.
'''Changing Account Data'''
Before an account field modification can be considered complete, both nodes must have a signed and dated copy of the modification from the other partner.
To declare a change to one or more account data fields, a node sends a signed @@account-set@@ message to its account partner containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
A signed affirmative reply by the other node echoing back the message contents indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account-request@@ message, which need not be signed, containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
* an explanatory note
An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need not contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the request-message contents. A signed affirmative reply containing the contents of the original request-message from the request originator completes the change. Having the request originator confirm the change at this point allows them final control over implementing the change (who knows what may have happened in the delay between request and approval) and maintains consistent semantics for the @@account-set@@ message.
*** Adding new fields
----------------------
!! Accounts
An account is a mutual-credit connection between two nodes defined by the following data, a copy of which is kept by the node of each account partner.
Required data:
* an account ID, which serves as a permanent identifier for the account
* each node's ID
* the unit of account (see Units of Account)
* the number of decimal digits with which to keep this account
* a credit limit for each node
* each node's routing information (see Query Routing)
* an authentication key for each node (see Authentication Keys)
Optional data:
* interest rate, as a decimal
* compounding period, in days
* account agreement, possibly including debt-settlement terms/schedule
Example:
[@
<account>
<account_id>550e8400-e29b-41d4-a716-446655440000</account_id>
<unit>urn:ripple:units:CAD</unit>
<digits>4</digits>
<node>
<node_id>rfugger@ripplepay.com</node_id>
<limit>100</limit>
<routing_id>7136976c-251d-4be4-b6e2-74baf4b4a53c</routing_id>
<key>...</key>
</node>
<node>
<node_id>random@example.com</node_id>
<limit>200</limit>
<routing_id>d699c900-b245-4e3d-a586-eb5743fa24af</routing_id>
<key>...</key>
</node>
<interest_rate>0.05</interest_rate>
<compound_period>0</compound_period>
<agreement>Both parties agree to pay the outstanding balance in cash on demand.</agreement>
</account>
@]
The XML structure here is only to show how fields will be addressed in account messages, not to dictate how a node must store its data.
Custom data fields may be added to an account as long as their meaning is understood by both nodes.
Generally a node will keep a record of all messages necessary to calculate the current balance on the account, including transaction receipts and changes to the account.
Unless otherwise specified, all account messages must be signed by the sender's authentication key.
'''Creating an Account'''
Accounts are created by one node offering to accept another's IOUs with an @@offer@@ message containing:
* a request ID
* an account ID
* timestamp
* the offering node's network ID
* the offering node's routing information
* the units of account
* the number of decimal digits with which to keep this account
* the proposed credit limit for node receiving the offer
* an initial balance for the new account
* some explanatory text to the recipient
* any other optional or custom data desired
[@
<offer request_id="16093">
<timestamp>2006-10-23 11:01:11.145000</timestamp>
<account id="550e8400-e29b-41d4-a716-446655440000">
<unit>urn:ripple:units:CAD</unit>
<digits>4</digits>
<node id="rfugger@ripplepay.com">
<routing_id>7136976c-251d-4be4-b6e2-74baf4b4a53c</routing_id>
<key>...</key>
</node>
<node id="random@example.com">
<limit>200</limit>
</node>
<interest_rate>0.05</interest_rate>
<compound_period>0</compound_period>
<agreement>Both parties agree to pay any outstanding balance in cash on demand.</agreement>
</account>
</offer>
@]
An affirmative reply means the offer is being held for consideration. If the offer recipient accepts the offer, his node sends back an @@account-create@@ with the full account data structure.
To indicate that the account has been created, the node receiving the @@account-create@@ responds with an affirmative reply. The reply may also be an error with one of the following error codes indicating why the account has not been created:
* incorrect account ID
* offer withdrawn
* unrecognized field
*
Otherwise it sends an @@offer-reject@@ message.
'''Changing Account Data'''
Before an account field modification can be considered complete, both nodes must have a signed and dated copy of the modification from the other partner.
To declare a change to one or more account data fields, a node sends a signed @@account-set@@ message to its account partner containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
A signed affirmative reply by the other node echoing back the message contents indicates acceptance of those changes. An error indicates rejection.
To request a change to one or more account data fields, a node sends an @@account-request@@ message, which need not be signed, containing:
* account ID
* time & date for the change to take effect
* the fields to be changed, with their new values
* an explanatory note
An affirmative reply here only indicates that the request has been understood and is being held for approval. The reply need not contain any data nor be signed.
Once the request is approved, the request recipient sends an @@account-set@@ message echoing back the request-message contents. A signed affirmative reply containing the contents of the original request-message from the request originator completes the change. Having the request originator confirm the change at this point allows them final control over implementing the change (who knows what may have happened in the delay between request and approval) and maintains consistent semantics for the @@account-set@@ message.
*** Adding new fields