Questions about Gatewayd from a Documentation Engineer
Q: What does gatewayd, technically speaking, do and not do? What's not within the scope of the project? Obviously, it's not rippled and it's not a mobile app for managing customer money, but beyond that I'm a bit fuzzy. I think I heard there's a skeleton web interface for handling customers?
A: At its core gatewayd is designed to simplify and automate interaction with the ripple network, specifically sending payments to other ripple addresses, and handling notification of the receipt of payments from other ripple address to the gateway's ripple address. In order to maintain an audit-able record of ripple payments sent to and from the gateway's ripple address, a relational database is included as part of the gatewayd software.
From the perspective of a gateway operator, interaction with gatewayd is achieved via its HTTP/JSON interface, allowing developers to create and monitor payments, and to query a record of transactions through their gateway.
Two unix processes automate the sending and receiving of payments via ripple, by reading and writing to the ripple_transactions and ripple_addresses database tables, recording historical ripple transaction data for later use.
The process found in processes/outgoing.js periodically queries the ripple_transactions database table for records with the state column set to outgoing. When a ripple_transaction record in the outgoing state is found the unix process digitally signs and sends the payment to the ripple network for acceptance into the global ledger.
The process found in processes/incoming.js periodically queries the ripple network for new payments made to the gateway's ripple address. When a new payment is discovered the process writes a record of the payment in the ripple_transactions database table and a record of the sender address in the ripple_addresses database table. In order to track its progress in processing incoming payments, the process saves and loads the hash of the last payment it has processed.
By using the database as a queue in this way gatewayd is able to process outgoing and incoming payments on ripple in an asynchronous fashion. If the gatewayd server loses connection with the ripple network, or if the server machine is restarted, or if the two unix processes simply crash, payment processing can still be resumed later when the processes are back online and proceed smoothly where it left off.
A gateway's role in ripple is to accept possession of assets and issue corresponding ripple IOU currency to the depositor. Gatewayd includes a relational database, and in order to maintain a complete account of transactions in and out of the gateway, grants the ability to record transactions and accounts that occur externally to the ripple network. For instance a gateway often receives inter-bank payments from another bank account, and needs to make a record of inter-bank transaction in their database.
Two unix processes automate the handling of transactions of value received via networks external to ripple, by reading and writing to the external_transactions and external_accounts database tables, recording historical external transaction data for later use.
The process found in processes/deposits reads the external transactions table for any transaction of type deposit with a state of queued, and then applies some business logic to that external transaction record to ultimately submit some ripple transaction. The business logic in the file located at processes/deposits is designed to be modified to suit your custom business needs. By default the deposits process queries the database for the destination ripple address associated with the queued external transaction by way of a users table that joins them, however such behavior is often modified per business rules.
The process found in processes/withdrawals reads the ripple transactions table for any transaction in the state of incoming, and then applies some business logic to that ripple transaction record to ultimately record some pending external transaction to an account in some network external to ripple. The business logic in the file located at processes/withdrawals is designed to be modified to suit your custom business needs. By default the withdrawals process queries the database for an external account associated with the incoming queued ripple transaction by way of its destination tag, however such behavior is often modified per business rules.
By using the database as a queue in this way gatewayd is able to asynchronously handle incoming deposits of value receive from networks and accounts external to Ripple. The HTTP / JSON API interface is used to record such transactions, and can be used to asynchronously process pending withdrawal transactions.
Q: Is there a difference between "Ripple Gateway Framework" and "gatewayd"? Which term do we prefer to use most often?
A: Gatewayd is the official name of the software, which provides a framework for building an automated gateway on ripple. What makes Gatewayd a framework is that pieces of it are meant to be customized depending on your unique banking and payments systems integration effort.
Q: The setup process includes setting up hot and cold wallets. Can you explain a bit about the best practices in this regard and how the software ties into it? Especially in the case of a gateway, where I expect main transactions to be mostly in IOUs, I don't really see what risks the hot wallet is mitigating.
If you are issuing IOUs on Ripple your IOUs become real liabilities that must be covered, and thus you want to prevent at all costs having the account that issues your currency be compromised. The most basic and widely-used strategy for preventing your issuing ripple account from being compromised is to keep that ripple account secret off of any servers that could be hacked or compromised. However at the same time an automated ripple gateway needs to be able to sign and send payments automatically to its users, presenting a dilemma since the secret key used for signing must also be stored offline, away from the server. Thus the "hot wallet" comes into play, enabling the issuing ripple account, now known as the "cold wallet" to be kept offline, while still sending automated payments. The hot wallet secret is stored on the server, and a limited amount of currency is issued into the hot wallet from the cold wallet manually by the gateway operator. If the server is then compromised, the balance of the hot wallet can be stolen, but the attacker will not have access to the gateway's issuing account, thus greatly limiting liability. Remember a gateway establishes lines of trust from its users to its ripple account, and if the account "cold wallet" is compromised the attacker can issue unlimited fraudulent funds from the gateway's account without recourse.
Q: Are incoming payments to the gateway always linked to withdrawals? What other cases could there be? For users, is just sending any payment to the gateway sufficient to qualify for a withdrawal?
A: No incoming payments are not always linked to withdrawals of asserts. For instance an incoming payment could be intended for making a payment for a e-commerce shopping cart. In gatewayd the default policy to be applied to in incoming transaction is to treat it is a "withdrawal", but this policy is designed to be customized or overridden with custom business logic.
Q What are hosted wallets? Do they exist in the Ripple ledger / in rippled's database whatsoever?
A A ripple address can be divided into "hosted" wallets by taking a single ripple address and appending a new "destination tag" for each user to construct a "hosted" address. In the ledger only the base ripple address is part of an account entry, so a hosted wallet with five thousand destination tags would still have only a single ledger entry for the base ripple address. A hosted wallet service theoretically accepts payments to such an address / destination tag pair, to which the service provider controls the private key. They would then display the balance of payments they received on behalf of the user, but the service provider would have control of the funds and be able to send them.
