{"action":"created","issue":{"url":"https://api.github.com/repos/interledger/rfcs/issues/45","repository_url":"https://api.github.com/repos/interledger/rfcs","labels_url":"https://api.github.com/repos/interledger/rfcs/issues/45/labels{/name}","comments_url":"https://api.github.com/repos/interledger/rfcs/issues/45/comments","events_url":"https://api.github.com/repos/interledger/rfcs/issues/45/events","html_url":"https://github.com/interledger/rfcs/issues/45","id":164936905,"number":45,"title":"RFC-4: Events `receive`, `fulfill_execution_condition`, `reject` -> `transfer_{prepare,execute,reject}`","user":{"login":"emschwartz","id":3262610,"avatar_url":"https://avatars.githubusercontent.com/u/3262610?v=3","gravatar_id":"","url":"https://api.github.com/users/emschwartz","html_url":"https://github.com/emschwartz","followers_url":"https://api.github.com/users/emschwartz/followers","following_url":"https://api.github.com/users/emschwartz/following{/other_user}","gists_url":"https://api.github.com/users/emschwartz/gists{/gist_id}","starred_url":"https://api.github.com/users/emschwartz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/emschwartz/subscriptions","organizations_url":"https://api.github.com/users/emschwartz/orgs","repos_url":"https://api.github.com/users/emschwartz/repos","events_url":"https://api.github.com/users/emschwartz/events{/privacy}","received_events_url":"https://api.github.com/users/emschwartz/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":3,"created_at":"2016-07-11T21:19:16Z","updated_at":"2016-07-12T15:02:41Z","closed_at":null,"body":"Proposal: replace `receive`, `fulfill_execution_condition`, and `reject` with `transfer_prepare`, `transfer_execute`, `transfer_reject`.\r\n\r\nRight now our event API leads to unnecessary complication on the part of the user of the plugin (client or connector).\r\n\r\nLet's say you're a receiving client trying to check when you receive money. Right now you need to listen for both the `receive` and the `fulfill_execution_condition` events. You need to check whether a transfer you get from the `receive` event has an `execution_condition`. If not, you have actually received money. If the transfer does have a condition, you need to recognize that you have not received money but only a notification of funds being held. You only know a Universal payment (with holds) is completed when you get a `fulfill_execution_condition` event. You can't only check the `fulfill_execution_condition` event though because you might get money from a transfer with no condition.\r\n\r\nSince any user of the plugin will immediately want to know the state of a transfer it gets, and since the plugin is in the best position to know what state it is in (depends on the details of the ledger), the plugin should provide explicit events for these different states."},"comment":{"url":"https://api.github.com/repos/interledger/rfcs/issues/comments/232076009","html_url":"https://github.com/interledger/rfcs/issues/45#issuecomment-232076009","issue_url":"https://api.github.com/repos/interledger/rfcs/issues/45","id":232076009,"user":{"login":"justmoon","id":53233,"avatar_url":"https://avatars.githubusercontent.com/u/53233?v=3","gravatar_id":"","url":"https://api.github.com/users/justmoon","html_url":"https://github.com/justmoon","followers_url":"https://api.github.com/users/justmoon/followers","following_url":"https://api.github.com/users/justmoon/following{/other_user}","gists_url":"https://api.github.com/users/justmoon/gists{/gist_id}","starred_url":"https://api.github.com/users/justmoon/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/justmoon/subscriptions","organizations_url":"https://api.github.com/users/justmoon/orgs","repos_url":"https://api.github.com/users/justmoon/repos","events_url":"https://api.github.com/users/justmoon/events{/privacy}","received_events_url":"https://api.github.com/users/justmoon/received_events","type":"User","site_admin":false},"created_at":"2016-07-12T15:02:41Z","updated_at":"2016-07-12T15:02:41Z","body":"> Let's say you're a receiving client trying to check when you receive money. Right now you need to listen for both the `receive` and the `fulfill_execution_condition` events.\r\n\r\nThat's not ideal. If you're the receiving client you're the one who has to **post** the fulfillment. The way it should work is: You would only listen to `receive`. If the transfer has a condition, you post the fulfillment and then process the payment and if it doesn't, you just process the payment.\r\n\r\nI'm going to assume for simplicity that we're going to get rid of cancellation conditions. (#48)\r\n\r\n##### Example (Receiver)\r\n\r\n```js\r\nclient.on('receive', (transfer) => {\r\n  // Check amount, etc.\r\n  if (transfer.condition) {\r\n    // Try to fulfill the condition or throw if unable\r\n  }\r\n  // Process the payment\r\n})\r\n```\r\n\r\n##### Example (Connector)\r\n\r\n```js\r\nclient.on('receive', (transfer) => {\r\n  if (transfer.condition) {\r\n    // Check if expiry window is sufficient\r\n  }\r\n  // Forward payment (same condition or lack thereof)\r\n})\r\n\r\nclient.on('send_fulfill', (transfer, fulfillment) => {\r\n  // Forward fulfillment to transfer.noteToSelf.source_ledger\r\n})\r\n```\r\n\r\nCurrently, the receiver needs only `receive` and the connector needs `receive` to pass forward a transfer (with or without condition) and `fulfill_execution_condition` to pass back a fulfillment.\r\n\r\n### Simple API\r\n\r\nThis would be the simplest possible API which covers all common use cases (sending, connecting, receiving):\r\n\r\n-> `receive(transfer)` - Someone did a send() to me\r\n-> `send_fulfill(transfer, fulfillment)` - A transfer I sent got fulfilled\r\n-> `send_reject(transfer)` - A transfer I sent got rejected\r\n\r\n### Advanced API\r\n\r\nThis could be used for more advanced use cases like logging transfers\r\n\r\n-> `transfer_prepare(transfer)`\r\n-> `transfer_execute(transfer, fulfillment?)`\r\n-> `transfer_reject(transfer)`\r\n\r\nOr:\r\n\r\n-> `transfer_update(transfer, status:String, fulfillment?)`\r\n\r\n----\r\n\r\nWe want to minimize the complexity of the ledger plugins, so having two APIs seems not ideal. Perhaps one solution would be to have the ledger plugin API expose only `transfer_update` and `ilp-core` automatically add the other events from that. At a mimimum, the `receive` event I think is very useful - see the pseudo-code above."}}
{"actor":{"display_login":"justmoon"}}