Update the brief example in the README.md

[AaronCritchley]

The existing example is not functional, due to the change from load_orders -> load_orderbook in this commit.

This changeset amends the example to be functional, with a small modification to place the order at a value we'd typically expect to see in the orderbook representation rather than a fixed $ value, which is hopefully a bit easier for a first time user to understand when they can see their order in the orderbook.

I have kept the print convention of the existing example, but please let me know if you would prefer it be changed to a Python 3.7-esque syntax with f-strings etc.

Log output from the example included below:

Orders (initial):
	 « OrderBook SOL-PERP [spread: 140.94000000, 82.142%]
	BUY      98,443.41000000 at         171.58000000   :: SELL       9,262.33000000 at         312.52000000
	BUY           0.01000000 at         100.00000000   :: SELL      10,000.00000000 at         313.24000000
	BUY           0.01000000 at         100.00000000   :: SELL           0.10000000 at         500.00000000
	BUY           0.01000000 at         100.00000000   :: 
	BUY           0.01000000 at         100.00000000   :: 
»


Placed order:
	 « Order BUY for 1.00000000 at 171.58000000 [ID: 0 / 1640726013288] POST_ONLY »


Sleeping for 10 seconds...


Orders (including our new order):
 « OrderBook SOL-PERP [spread: 140.94000000, 82.142%]
	BUY      98,443.41000000 at         171.58000000   :: SELL       9,262.33000000 at         312.52000000
	BUY           1.00000000 at         171.58000000   :: SELL      10,000.00000000 at         313.24000000
	BUY           0.01000000 at         100.00000000   :: SELL           0.10000000 at         500.00000000
	BUY           0.01000000 at         100.00000000   :: 
	BUY           0.01000000 at         100.00000000   :: 
»


Cancellation signature:
	 ['2E3etN9jdFC4eV5zhrCEv5P4BdzVq4auHnK4oG1SKbUhyXMMBGT4Jd1T5KXB7c7s6u8FGwz1AA3Y3yAVapWBWvEX']


Sleeping for 10 seconds...


Orders (without our order):
 « OrderBook SOL-PERP [spread: 140.94000000, 82.142%]
	BUY      98,443.41000000 at         171.58000000   :: SELL       9,262.33000000 at         312.52000000
	BUY           0.01000000 at         100.00000000   :: SELL      10,000.00000000 at         313.24000000
	BUY           0.01000000 at         100.00000000   :: SELL           0.10000000 at         500.00000000
	BUY           0.01000000 at         100.00000000   :: 
	BUY           0.01000000 at         100.00000000   :: 
»

[OpinionatedGeek]

Thanks for tackling this!

I take your point about f-strings but I wanted to avoid them in this example. I wanted to keep this one as basic as I could, and I'd get rid of the \n and \t if I could do it simply. I like the idea of print("variable", variable) if we can - there's no ambiguity in the output that it's showing that variable's value.

The more realistic examples are in the mango-explorer-examples repo, and we can get as complicated as we like there.

I appreciate the idea of using the oracle to get a realistic price so that the order appears in the output, but I'd rather avoid using an oracle if we can. The idea behind buying at $10 was partly because the order wouldn't be filled - I worry that a beginner might accidentally run this code against mainnet instead of devnet and I didn't want them to suddenly have an unexpected SOL-PERP position.

Can you think of another way of adding the order so it appears in the orderbook output but is unlikely to be filled? Nothing immediately occurs to me but I'm hoping you might have an idea or two. If not, we'll go with your oracle-based approach (it's important for the user to see their order), but maybe adjust it a bit?

Thanks again for looking into this.

[AaronCritchley]

Thanks for the feedback Geoff, appreciate it! I think your points and concerns RE: the code being applied to mainnet make sense. Happy to make the suggested changes

Can you think of another way of adding the order so it appears in the orderbook output but is unlikely to be filled? Nothing immediately occurs to me but I'm hoping you might have an idea or two. If not, we'll go with your oracle-based approach (it's important for the user to see their order), but maybe adjust it a bit?

I see a few options, we could:

1. Change the code from using load_orderbook to load_my_orders, this would guarantee the users sees the order, but they would have less context as they would not see it relative to the book.
2. Change the order to be "bottom of visible book" (i.e. 5th best bid) - I don't think this solves the problem very well though, but would slightly improve the situation.
3. Change the order size to something much smaller so it would be fairly inconsequential if it did get accidentally executed, perhaps min-lot size?
4. Change the code to be slightly more defensive against an accidental removal of the cluster_name="devnet", perhaps with an assertion before we place the order.

Let me know if you would like me to implement any of the above, no worries if not. I'm fine with removing the oracle code and just keeping it to a $10 bid or similar.

[OpinionatedGeek]

Using load_my_orders sounds like an excellent idea!

How about every time we show the orderbook, we then show the user's orders? The first and third entries should be empty, and the second one should show one order - the one just placed. That should show them both the context of the orderbook, as well as the details of their order which may not appear in the top orderbook entries.

How does that sound to you?

[AaronCritchley]

How does that sound to you?

Sounds good, I'll implement later today!

[AaronCritchley]

I've implemented your suggested changes, with a minor change to wording for increasing clarity in the logs.

Log output from the example included below:

Initial order book:
	 « OrderBook SOL-PERP [spread: 0.01000000, 0.006%]
	BUY         243.41000000 at         174.92000000   :: SELL         245.78000000 at         174.93000000
	BUY      98,355.30000000 at         171.58000000   :: SELL         491.56000000 at         174.93000000
	BUY         245.78000000 at         170.23000000   :: SELL         983.12000000 at         174.93000000
	BUY         491.56000000 at         169.37000000   :: SELL         247.60000000 at         175.10000000
	BUY         983.12000000 at         168.50000000   :: SELL       8,261.13000000 at         312.52000000
»
Your current orders:
	 []


Placed order:
	 « Order BUY for 1.00000000 at 10.00000000 [ID: 0 / 1640824205415] POST_ONLY »


Sleeping for 10 seconds...


Order book (including our new order):
 « OrderBook SOL-PERP [spread: 0.01000000, 0.006%]
	BUY         243.41000000 at         174.92000000   :: SELL         245.67000000 at         174.93000000
	BUY      98,355.30000000 at         171.58000000   :: SELL         491.35000000 at         174.93000000
	BUY         245.67000000 at         170.33000000   :: SELL         982.69000000 at         174.93000000
	BUY         491.35000000 at         169.46000000   :: SELL         247.60000000 at         175.10000000
	BUY         982.69000000 at         168.60000000   :: SELL       8,261.13000000 at         312.52000000
»
Your current orders:
	 [« Order [BsLNUtm91MmeCvBS6JfYUghYRsySL4jSbWD9ifCG7r9Z] BUY for 1.00000000 at 10.00000000 [ID: 18465190817783257189999 / 1640824205415] »]


Cancellation signature:
	 ['2ZL18sZhWUsN4S2Faafq9vtfA33eCZP4ZdqwUtcVVBxqi47zPBHyTbkGy2Ahs4ZNF5Bh8NBJ5EPYRrT67DqLBDMH']


Sleeping for 10 seconds...


Order book (without our order):
 « OrderBook SOL-PERP [spread: 0.01000000, 0.006%]
	BUY         243.41000000 at         174.92000000   :: SELL         245.35000000 at         174.93000000
	BUY      98,355.30000000 at         171.58000000   :: SELL         490.71000000 at         174.93000000
	BUY         245.35000000 at         170.56000000   :: SELL         981.42000000 at         174.93000000
	BUY         490.71000000 at         169.69000000   :: SELL         247.60000000 at         175.10000000
	BUY         981.42000000 at         168.82000000   :: SELL       8,261.13000000 at         312.52000000
»
Your current orders:
	 []

[OpinionatedGeek]

Brilliant! Thank you so much for this!