ClientAPI

!!! An implementation proposal

[[Implementation/Components|See how this component fits in the system]]

%thumb% Attach:RedInterface.png"Ripple Merchant API"

%thumb% Attach:RedInterface.png.png"Ripple Merchant API"

%thumb% Attach:RedLink2.png"Ripple Merchant API"

* [[Main/Definitions]]
* [[Main/Client API Request Examples]]

* a ripple user might well register only a single node, but a user might also have [[UsersAndNodes|reasons to register multiple nodes]]

'''A Client'''
* Software that manages accounts that involve lines of credit between parties.

'''A Node'''

'''A User'''
* a user may interact with the ripple system via a single registered node, or may choose to register multiple nodes, just as an email user might choose to have more than one email address
**

* nodes store [[Credit Relationship Exchange Rates]]. These rates determine transaction fees, if any, when acting as a payment intermediary

** when routing, can charge a transaction fee
** can be friendly, and not charge a fee
** nodes store [[Credit Relationship Exchange Rates]]. These rates determine transaction fees, if any, when acting as a payment intermediary

** Node A's request

** With Node A's request
*** Establishes the unit of value for the relationship, and node A's account data; node B's confirmation establishes node B's account data.
*** If Node A has already established credit relationships with other nodes, incoming and outgoing exchange rates are established between all of node A's other relationships and the new relationship with node B
** Node B's confirmation
*** If Node B has already established credit relationships with other nodes, exchange rates are established between them and the new credit relationship with Node A
* If a node is unwilling to exchange between certain subsets of its relationships when available credit permits, it should properly be represented as two nodes for the routing system to function optimally.

* Two nodes may have more than one credit relationships connecting them, for instance to allow for credit relationships in more than one currency

* exists between two nodes, say node A and node B

* exists between two nodes (node A and node B below)
* describes a line of credit that node A has with node B, and the reciprocal line of credit node B has with node A

* has an account for each node, each containing the following data:
** the balance of payments between the two nodes (kept as two balances in case there is disagreement between the nodes)
** an upper limit, which is the maximum balance on this account
** a lower limit, which is the minimum balance on this account

** the balance of payments (e.g. credit spends) between the two nodes. The balance of payment is a single number. From one node's point of view the number is positive, from the other node's point of view it is negative. (Maybe not so simple -- what about reconciliation... see below... )

* has credit relationships (lines of credit) with other nodes

* exists between two nodes (node a and node b below)
* describes a line of credit that node a has with node b, and the reciprocal line of credit node b has with node a
* has a specific unit of value, such as USD, Euro, or oz. of gold
* contains the following:
** the balance of payments (e.g. credit spends) between the two nodes. The balance of payment is a single number. From one node's point of view the number is positive, from the other node's point of view it is negative.
** credit limits and issuance limits for each node, where
*** the credit limit is the maximum amount of credit one node will issue to the other
*** the issuance limit is the maximum amount of indebtedness one node will permit itself to get into with the other

*** balance of payments on this credit relationship (the sum of the balances of both lines of credit)

!!!! A client instance can register and manage nodes and credit relationships between them.
* To register a node, a client requests that the server create the node.
* To register a credit relationship between node A and node B, node A's client requests that the server register the relationship.  The server then asks node B's client, which may be different from node A's client, to confirm the relationship.
** Node A's request establishes the unit of value for the relationship, and node A's account data; node B's confirmation establishes node B's account data.
** Node A's request establishes incoming and outgoing exchange rates between all of node A's other relationships; node B's confirmation does the same for node B.  If a node is unwilling to exchange between certain subsets of its relationships when available credit permits, it should properly be represented as two nodes for the routing system to function optimally.
* For the standalone backend, relationships must be between nodes on a single Ripple server.  For the distributed version, relationships may also be between nodes on different Ripple servers.  (This defines ''standalone'' and ''distributed''.)
* A client instance can delete its nodes
* A client instance can delete a relationship that its node is party to, with the permission of the other party.

!!!! A client can update data for nodes and credit relationships
* Data that can be updated:
** credit and issuance limits for each relationship account
** exchange rates between a node's relationships
* When set (including initially) this data has an expiry time after which it is invalid and must be updated before the accounts in question can be used again.  Before the expiry time, Ripple may commit transactions on the accounts in question as long as the balance remains within their respective credit limits.
** Changing a credit limit may leave the account balance outside that limit.  This is permissible, and simply means that any transactions on that relationship must move the balance closer zero, never further away, until the balance is once again within the account limits.
* Updates may be pushed by client pre-emptively, before or after expiry time, or pulled by server as needed, if that mode is supported by the client.
* A ''reconciliation'' must occur before new account data can be registered.

** The reconciliation may be ''hard'', meaning the cumulative balances for the accounts in question are reset to zero or ''soft'', meaning they are not.  In other words, new credit limits set after a hard reconciliation are relative to the current balance, and credit limits after a soft reconciliation are still relative to the balance at the last hard reconciliation.

* A client can tag nodes with one or more ''addresses''. 
** Multiple nodes may have the same address, but they must be on the same client.
* Payment is between two addresses, called the paying and receiving addresses.  Each address may consist of multiple nodes.
* Both paying and receiving clients must approve a payment before it occurs.
* Either paying or receiving client may initiate the payment process.

'''A client'''
* is software that manages accounts that involve lines of credit between parties.

'''A credit relationship'''
* is a line of credit between two nodes, and the reciprocal line of credit in the same units, if it exists.
* consists of the following data:

*** balance of payments on this credit relationship (the sum of the balances of both lines of credit -- [[Implementation/CreditRelationshipBalanceExample | example]])

*** the credit limit for the other node (the maximum amount of obligations this node will accept from the other; range: zero-infinite)
*** the issuance limit for this node (the maximum amount of obligations this node will issue to the other; range: zero-infinite)

* A credit relationship is a line of credit between two nodes, and the reciprocal line of credit in the same units, if it exists.

*** balance of payments on this credit relationship (the sum of the balances of both lines of credit)

'''A node'''

* can be a payment endpoint, either payer or recipient
* can be a payment intermediary, receiving value from one node and passing it along to another as part of a payment chain
* is controlled by a single client instance

Let the client specify a callback URL or formula that takes available data at each hop and makes more complex decisions about where to route and what exchange rates to use.

* can be a payment endpoint, either payer or recipient.

* A credit relationship is a line of credit between two nodes, and the reciprocal line of credit in the same units, if it exists{-, with the balance kept as a sum of the balances of the two lines of credit to simplify their use in payments.-}

!!!! A client can register and manage user nodes and credit relationships between them.
* Each node belongs to only one client.

!!!! A client must register data for accounts and exchanges

!!!! Transaction interaction

** The reconciliation may be ''hard'', meaning the cumulative balances for the accounts on the Ripple server is reset to zero or ''soft'', meaning it is not.  In other words, new credit limits set after a hard reconciliation are relative to the current balance, and credit limits after a soft reconciliation are still relative to the balance at the last hard reconciliation.
** A hard reconciliation must be followed by a data update.  A soft reconciliation may optionally be followed by a data update.

!! Ripple Client Server Protocol/API

The interface between inter-user accounting clients and the Ripple backend, either standalone or distributed.

!!!!! A single Ripple server can support multiple clients.

!!!!! A client can register and manage users and accounts between them.

* Each user is a user of only one client.

* There are two versions of an account, each owned by one of the users that is party to the account, and each kept on that party's client.

* A client can only manage its own users and account versions, not those of other clients.
* When user A's client registers a version of his account with user B, user B's client must confirm the existence of the account by registering its version of the account.

* A client can delete accounts, exchanges, and users.

!!!!! A client must register data for accounts and exchanges

* Data may be pushed by client pre-emptively, before or after expiry time, or pulled by server as needed, if that mode is supported by the client.

* A client may request a reconciliation with the Ripple server for some or all of its accounts.

* Both payer's and recipient's clients must approve a payment before it occurs.

Two interfaces may be useful:

* HTTP/REST client request, server respond model, where server must wait for client to check in to send certain information
* XMPP real-time messaging, where server can push or request information from the client as it needs

!!!!! A single Ripple server can support multiple accounting systems.

!!!!! An accounting system can register and manage users and accounts between them.
* An account is between two users.
* Each user is a user of only one accounting system.
* Each user has one or more ''exchanges'', which are nodes connecting the user's accounts together, indicating that that user will exchange between those accounts for Ripple payments.
* There are two versions of an account, each owned by one of the users that is party to the account, and each kept on that party's accounting system.
* Each version of an account belongs to a single exchange.
* An accounting system can only manage its own users and account versions, not those of other accounting systems.
* When user A's accounting system registers a version of his account with user B, user B's accounting system must confirm the existence of the account by registering its version of the account.
* For the standalone backend, accounts must be between users on a single Ripple server.  For the distributed version, accounts may be between users on different Ripple servers as well.  (This defines ''standalone'' and ''distributed''.)
* An accounting system can delete accounts, exchanges, and users.

!!!!! An accounting system must register data for accounts and exchanges
* Data registered include:
** upper and lower limits for each account
** exchange rates between each pair of accounts in an exchange, in each direction
* Data has an expiry time after which it is invalid and must be updated before the accounts in question can be used again.  Before the expiry time, Ripple may commit transactions on the accounts in question as long as the balance remains within their respective credit limits.
* Data may be pushed by client pre-emptively, before or after expiry time, or pulled by server as needed.
* A ''reconciliation'' must occur before new account data can be registered (see below).
* An accounting system may request a reconciliation with the Ripple server for some or all of its accounts.
** The reconciliation may be ''hard'', meaning the cumulative balances for the accounts on the Ripple server is reset to zero or ''soft'', meaning it is not.
** The reconciliation may be followed by a data update.

!!!!! Transaction interaction
* Payment is between two Ripple users, called the payer and recipient.
* The payment pathset may originate and terminate at any subset of the payer's and recipient's exchanges, respectively.
* Both payer's and recipient's accounting systems must approve a payment before it occurs.
* Either payer or recipient may initiate the payment process.
* Payment consists of value transfer along a ''pathset'' of one or more paths of accounts between payer and recipient.
* Payment is denominated in ''payment units'', which may or may not be the same as the units on any account used in the transaction.

** Each user is a user of only one accounting system.
** Each user has one or more ''exchanges'', which are nodes connecting the user's accounts together, indicating that that user will exchange between those accounts for Ripple payments.

** Each version of an account belongs to a single exchange.
** An accounting system can only manage its own users and account versions, not those of other accounting systems.
** When user A's accounting system registers a version of his account with user B, user B's accounting system must confirm the existence of the account by registering its version of the account.
** For the standalone backend, accounts must be between users on a single Ripple server.  For the distributed version, accounts may be between users on different Ripple servers as well.  (This defines ''standalone'' and ''distributed''.)

** freeze credit for accounts in pathset
** params: @@payment_id <list of accounts> <list_of_amount_for_each_account>@@

* commit pathset
** params: @@payment_id@@

!! Ripple Server-Account System API

** The Ripple server must support accounting systems that will interact with their users at transaction time to get transaction authorizations along payment paths.  (Of course, this will take a lot longer.)

HTTP GET/POST parameters for input, JSON for results.  (Possibly allow for XML as well, if client prefers?)

!!! Rippler Server API

Client interface for an account system to the Ripple transaction server.

Account system data will be defined manually by the Ripple server admin.

!!!! Users

* register user
** params: @@name@@

* get users

* delete user

!!!! Accounts

* delete account

!!!! Exchanges

* register exchange
** params: @@user@@

* get exchanges

* add account to exchange

* remove account from exchange

* paying_exchanges = <list of accounts>
* receiving_exchanges = <list of accounts>
* units = <string>

* deadline = <datetime>


!!! Account System API

Account systems must provide the following to the transaction module:

!!!! Accounts

* confirm account

* payment request

!!!! Payments

* commit pathsets

To support both local and remote user identification for the distributed server, local users are identified by username only, and remote users by their Ripple ID (user@ripplehost:port).  Apps developed on the standalone server should support Ripple usernames in this format for forward compatibility to the distributed server.

The distributed server will store signed messages as part of each account history and payment.  These are not available on the standalone server.  Could just have optional JSON return fields for these where necessary, that are left empty by the standalone server.  These are only useful for auditing, and aren't central to regular operations.

** There are two versions of an account, each owned by one of the users that is party to the account, and each kept on that party's accounting system.

** When an accounting system registers a version of an account with a user of another accounting system, that user's system must confirm the existence of the account by registering its version of the account.

** Accounting systems determine the exchange rate between account units for their users.
** The Ripple server communicates with accounting systems to determine request exchanges, freeze available credit, and commit balance changes.

** The Ripple server determines the exchange rate between payment units and account units at path endpoints, and between account units for successive path accounts.  The Ripple server should provide some basic way to convert between well-known units (and therefore between account units based on well-known units), as well as allowing accounting systems to determine their own exchange rates if they wish.

** Payment is between two Ripple users, called the payer and recipient.
** Both payer's and recipient's accounting systems must approve a payment before it occurs.
** Payment consists of value transfer along one or more paths of accounts between payer and recipient.
** Payment is denominated in payment units, which may or may not be the same as the units on any account used in the transaction.
** The Ripple server determines the exchange rate between payment units and account units at path endpoints, and between account units for successive path accounts. 
** The Ripple server must be able to determine exchange rates for accounts on behalf of a user whose accounting system does not keep a version of the account or accounts in question.  Thus the accounting system must give the Ripple server some method of determining exchange rates when it confirms an accounts, even when it does not register a version of that account.
** The Ripple server communicates with accounting systems to determine available credit on accounts, freeze that credit, and commit balance changes.

** An account is between two users.
** Each user is a user of one accounting system.
** There may be one or two versions of an account, each owned by one of the users that is party to the account, and each kept on that party's accounting system.
** An accounting system can only manage its own users and account versions, not those of other accounting systems
** When an accounting system registers a version of an account with a user of another accounting system, that user's system must confirm the existence of the account, and be given the opportunity to register its version of the account.
** For the standalone backend, accounts must be between users on a single Ripple server.  For the distributed version, accounts may be between users on different Ripple servers as well.

** The Ripple server determines exchange rates between each user's accounts at transaction time, including for which the user's accounting system doesn't keep a version.