Ripple API

[nelisky]

Ok, so I have been hard at understanding the whole ripple concept and it has spawned some neat ideas. As a coder I tend to try and understand frameworks in as much of a hands on approach as possible, so I thought I'd ask those who are in the know how to go about this.

The history and all transactions are public, so I could parse my way through said history to get to the information I need, but is there a simpler way? I want to know, for a specific currency and issuer, who is holding IOUs and how much each wallet has, say I want to know every wallet that has Bitstamp BTCs and how many of them they have.

[moocowpong1]

I think rippled does a lot of what you want, but you can't play with it yet. There's a lot information on the wiki about that sort of thing, although I haven't taken the time to look at it closely.

If you want an example ledger to see how the information is stored, JoelKatz posted one here: https://bitcointalk.org/index.php?topic=148278.msg1573763#msg1573763

[nelisky]

Thank you for the pointer. Turns out this initial request I made was right in front of my face and I just failed to see it; https://ripple.com/wiki/RPC_API#account_lines

I still have to filter the currencies and there's no batching which may make things hard with huge ledgers, but it is there and is real easy.

[nelisky]

In trying to jump in to find out why I'm having issues and which paths are being involved, I tried calling the ripple_path_find RPC command, according to the instructions on the wiki https://ripple.com/wiki/RPC_API#ripple_path_find but it is failing complaining about invalid arguments:

Request:
{"destination_amount": "0.05", "source_currencies": [{"currency": "BTC"}], "command": "ripple_path_find", "source_account": "rKLw2zHgA31nRZN3erfZkfR8uhAkQ8s95P", "destination_account": "rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt"}

Response:
{u'status': u'error', u'error_code': 23, u'error_message': u'Invalid parameters.', u'request': {u'destination_amount': u'0.05', u'source_currencies': [{u'currency': u'BTC'}], u'command': u'ripple_path_find', u'source_account': u'rKLw2zHgA31nRZN3erfZkfR8uhAkQ8s95P', u'destination_account': u'rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt'}, u'error': u'invalidParams', u'type': u'response'}

Any clues into what I'm doing wrong?

[JoelKatz]

Your amount format is wrong. Try this:

{
    "command" : "ripple_path_find",
    "source_account": "rKLw2zHgA31nRZN3erfZkfR8uhAkQ8s95P",
    "destination_account": "rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt",
    "destination_amount": {
        "currency": "BTC",
        "issuer": "rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt",
        "value": "0.05"
    }
}

[nelisky]

Thank you, Joel. It works, so please note that the wiki is wrong here

No on to parsing the result...

[nelisky]

Code:

{u'paths_computed':
  [
    [
      {u'currency': u'BTC', u'account': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'},
      {u'currency': u'BTC', u'account': u'rh7eAu9SrFsE2fVfc1PJTs1WYDHGAUde6V', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rh7eAu9SrFsE2fVfc1PJTs1WYDHGAUde6V'},
      {u'currency': u'BTC', u'account': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E'}
    ],
    [
      {u'currency': u'BTC', u'account': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'},
      {u'currency': u'BTC', u'account': u'rh7eAu9SrFsE2fVfc1PJTs1WYDHGAUde6V', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rh7eAu9SrFsE2fVfc1PJTs1WYDHGAUde6V'},
      {u'currency': u'BTC', u'account': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E'}
    ],
    [
      {u'currency': u'BTC', u'account': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'},
      {u'currency': u'BTC', u'account': u'rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW'},
      {u'currency': u'BTC', u'account': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E', u'type': 49,
       u'type_hex': u'0000000000000031', u'issuer': u'rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E'}
    ]
  ],
 u'source_amount': {u'currency': u'BTC', u'value': u'0.0501', u'issuer': u'rKLw2zHgA31nRZN3erfZkfR8uhAkQ8s95P'}, 
 u'paths_canonical': []}

So I guess I'm getting 3 potential credit lines that could be used, but the first 2 are exactly the same, are they now? Can you help me understand what I'm looking at above (a pointer to the documentation is fine)?

FYI this is one case where I would assume the transfer should be possible but it fails with the partial path error.

[JoelKatz]

So I guess I'm getting 3 potential credit lines that could be used, but the first 2 are exactly the same, are they now? Can you help me understand what I'm looking at above (a pointer to the documentation is fine)?

Duplicate paths are caused by a bug. We've been working on pathfinding heavily for the past week. Expect things to get much better over the next week or so.

[nelisky]

So the 3 paths I see are actually 2 paths and are alternative ways of proceeding with the transfer? Could you take the first one and convert it to an english sentence?

[JoelKatz]

So the 3 paths I see are actually 2 paths and are alternative ways of proceeding with the transfer? Could you take the first one and convert it to an english sentence?

In this case, the paths are alternative ways of performing the transfer. In a more complex case, the paths may be needed together to accomplish the full transfer.

Supplying multiple paths also ensures that the transaction succeeds even if the state has changed between when the transaction is formed and when it is processed. When the final transaction is executed, the paths are taken incrementally to ensure the best rate (from those paths) is given. The rate can change as IOUs are pushed through a path for two reasons: 1) If the path includes an order book, you can exhaust the best offer and have to move to an inferior offer. 2) If the path switches from redeeming IOUs to issuing IOUs, the rate can change. (You have to accept your own IOUs at face value, but you can devalue someone else's.)

To explain 2 in a little more detail, say I hold your IOUs and payment path goes from me to you. So long as I hold your IOUs, I can give them to you and you must honor them at face value. However, when I run out of IOUs, if you have extended credit to me, the path can still work with you getting my IOUs instead of me giving you yours. This can result in a different rate because the issuer of the IOUs and the direction they move has changed.

                 {
                     "account" : "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
                     "currency" : "BTC",
                     "issuer" : "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
                     "type" : 49,
                     "type_hex" : "0000000000000031"
                  },
                  {
                     "account" : "rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW",
                     "currency" : "BTC",
                     "issuer" : "rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW",
                     "type" : 49,
                     "type_hex" : "0000000000000031"
                  },
                  {
                     "account" : "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
                     "currency" : "BTC",
                     "issuer" : "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
                     "type" : 49,
                     "type_hex" : "0000000000000031"
                  }

This is an expanded path showing things like currencies even when they don't change. It's a rippling path with no exchanges involved, all in the same currency. The first node is Bitstamp. So the sender is going to return Bitstamp IOUs to Bitstamp and in return Bitsamp will issue IOUs to rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW. In exchange for the Bitstamp IOUs, rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW will issue their own IOUs to rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E, who will in turn issue their own IOUs to the recipient.

[nelisky]

In this case, the paths are alternative ways of performing the transfer. In a more complex case, the paths may be needed together to accomplish the full transfer.

Supplying multiple paths also ensures that the transaction succeeds even if the state has changed between when the transaction is formed and when it is processed. When the final transaction is executed, the paths are taken incrementally to ensure the best rate (from those paths) is given. The rate can change as IOUs are pushed through a path for two reasons: 1) If the path includes an order book, you can exhaust the best offer and have to move to an inferior offer. 2) If the path switches from redeeming IOUs to issuing IOUs, the rate can change. (You have to accept your own IOUs at face value, but you can devalue someone else's.)

To explain 2 in a little more detail, say I hold your IOUs and payment path goes from me to you. So long as I hold your IOUs, I can give them to you and you must honor them at face value. However, when I run out of IOUs, if you have extended credit to me, the path can still work with you getting my IOUs instead of me giving you yours. This can result in a different rate because the issuer of the IOUs and the direction they move has changed.

In 1) will order books ever be used automatically, i.e. if I send USD but only have BTC, or is that limited to when dealing directly with orders?

As for 2) that is pretty smart, I must say. It does not apply to the case where both sides of a trade trust a common exchange but not one another, right?

[nelisky]

This is an expanded path showing things like currencies even when they don't change. It's a rippling path with no exchanges involved, all in the same currency. The first node is Bitstamp. So the sender is going to return Bitstamp IOUs to Bitstamp and in return Bitsamp will issue IOUs to rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW. In exchange for the Bitstamp IOUs, rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW will issue their own IOUs to rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E, who will in turn issue their own IOUs to the recipient.

So rKLw2zHgA31nRZN3erfZkfR8uhAkQ8s95P wants to send to rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt. rKLw returns the IOUs it holds from Bitstamp and Bitstamp issues a new set of IOUs to rhR5j5LXsujSuwG2bcn1P39utdTA79ceaW. This in turn issues own IOUs to rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E which issues own IOUs to rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt.

Why the extra hops if rLDDq8ZGhCaVBP8MyYTifhCJzgWPQBjwpt trusts Bitstamp? And these IOUs from rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E, are they still Bitstamp IOUs as far as the recipient is concerned?

It might just be late here, but I fail to understand why this "complicated" path would ever need to take place, unless there's already an outstanding balance between the multiple nodes that would get settled with this transaction.

[JoelKatz]

In 1) will order books ever be used automatically, i.e. if I send USD but only have BTC, or is that limited to when dealing directly with orders?

Order books will always be used when a change of currency is required since that's the only way to change currencies. Otherwise, order books will be used where available. For example, if you hold bitstamp BTC IOUs and are trying to pay someone who only accepts WeExchange BTC IOUs, it will try to ripple through an account, but it will also look for both a direct order book between the two IOUs and an indirect path through two order books.

As for 2) that is pretty smart, I must say. It does not apply to the case where both sides of a trade trust a common exchange but not one another, right?

(I assume by "exchange" you mean an issuer, not a change in currencies.) Assuming the issuer hasn't issued the first one credit, then it cannot apply. (And gateways don't usually extend credit to anyone.) It can only apply when you are returning IOUs to someone who has extended you credit. At first you can give them their own IOUs and then you can issue your own IOUs.

The network doesn't currently handle all of these cases quite as well as it could when finding paths. We are working on this now.

[nelisky]

As for 2) that is pretty smart, I must say. It does not apply to the case where both sides of a trade trust a common exchange but not one another, right?

(I assume by "exchange" you mean an issuer, not a change in currencies.) Assuming the issuer hasn't issued the first one credit, then it cannot apply. (And gateways don't usually extend credit to anyone.) It can only apply when you are returning IOUs to someone who has extended you credit. At first you can give them their own IOUs and then you can issue your own IOUs.

The network doesn't currently handle all of these cases quite as well as it could when finding paths. We are working on this now.

Yes, issuer, still getting used to the semantics here. The cases that are failing for me (including the one I pasted the RPC call for) are all V shaped. Both ends trust one 3rd party issuer, none trust the other, so I am trying to move Bitstamp IOUs from walletA to walletB, where none of the wallets has extended credit to the other, but both have for Bitstamp.

If walletB had extended credit to walletA, the transfer would succeed but instead of sending the Bitstamp IOUs walletA would issue its own IOUs to walletB. This is all fine, except that having done that I was then not capable redeeming walletA's IOU from walletB to Bitstamp.

I am always working under the assumption that both the V shaped transfer and the latter paragraph example (full circle?) are legal and are only failing due to something wrong with the found paths. The specific error 'Path could not send full amount.' (tecPATH_PARTIAL) appears to say that there aren't enough IOUs in the path to move the full amount transfered, which could be easily solved by taking the shortest path of no hops other than the wallets involved + the issuer, but I haven't looked at the actual code, so this is just a wild guess.

[JoelKatz]

I am always working under the assumption that both the V shaped transfer and the latter paragraph example (full circle?) are legal and are only failing due to something wrong with the found paths. The specific error 'Path could not send full amount.' (tecPATH_PARTIAL) appears to say that there aren't enough IOUs in the path to move the full amount transfered, which could be easily solved by taking the shortest path of no hops other than the wallets involved + the issuer, but I haven't looked at the actual code, so this is just a wild guess.

We just identified a bug that could cause the tecPATH_PARTIAL case. It could also affect the other cases. I'll add some paths as you describe to my test cases.

[Arvicco]

Joel,

Is there any documentation (other than the source) describing the keypairs and signing? 

I'm mostly interested in constructing/signing a raw transaction locally without JavaScript, and then transmitting it as a tx_blob via 'submit' API. The other way of submitting a transaction with tx_json and secret on the wire is REALLY unsafe.

[JoelKatz]

Joel,

Is there any documentation (other than the source) describing the keypairs and signing? 

I'm mostly interested in constructing/signing a raw transaction locally without JavaScript, and then transmitting it as a tx_blob via 'submit' API. The other way of submitting a transaction with tx_json and secret on the wire is REALLY unsafe.

The JavaScript client now has code to build a raw binary transaction and sign it locally. Secrets are no longer sent over the wire.

There is documentation on the binary format in the wiki, but it's kind of hard to get a high-level overview from there.

[ahbritto]

We have this:

* https://npmjs.org/package/ripple-lib

We push it irregularly. It is undocumented. It is subject to change without notice. It does local signing.

It should be pretty easy to make a command line interface with it.

More information here:

* https://ripple.com/wiki/Ripple_JavaScript_library

[nelisky]

Looking at account_tx now, trying the full range of ledger indexes (0 to 323284 currently) I get 6 results back, all of them failed attempts at sending (the tecPARTIAL_PATH I've reported). There are 4 events in the account history (receiving XRP, receiving BTC and sending a custom currency) that aren't referenced at all in account_tx. Is this expected?

I assumed account_tx would be a filtered version of tx_history, but I may be confusing the command semantics.

[Arvicco]

What is the date format used in Ripple API? For example, account_tx returns "tx":  {"date":415507200}

Wiki says Unix epoch but it can't be right. 415507200 sec since Unix = 1983-03-03 07:17:40. Must be some offset or something?