Exchange Integration

From Mochimo Wiki
Jump to: navigation, search

Document Title: Integrating Mochimo Cryptocurrency w/3rd Party Transaction Systems

Intended Audience: Technical Integration Teams for Cryptocurrency Exchanges, Payment Processors, and 2nd Layer Service Providers.\

Summary: This document describes Mochimo Addresses, Address Tags, Basic Transaction Creation, API Integration, and using the command-line wallet tools for 3rd party systems and exchange integration.

Author: Matt Zweil (stackoverflo)

Last Updated: 6 August 2020


Introduction to Mochimo Addresses

Mochimo uses WOTS+ digital signatures in the form of a Public Key “Address” and Secret Key. Mochimo Public Keys are only signed one time, and then never used again. A separate short identifier called an “Address Tag” is bound to the WOTS+ Public Key and moved to a new Public Key each time a Public Key is signed (spent). The actually long-form WOTS+ Public key (2208 Bytes) is usually transparent to senders and receivers, as they just refer to their short address tag to send and receive MCM. The Mochimo wallet keeps a pool of “raw” WOTS+ addresses to move the user’s Address Tag to with each transaction. Mochimo’s Public Key Addresses have a unique optional field called an “Address Tag”. When you first create the WOTS+ Address/Secret pair, it will be an "untagged" address otherwise referred to as a "raw” WOTS address. The tag field in the address is the last 12 bytes.

Note: For an untagged address, the last 12 bytes of the 2208 byte raw WOTS+ Address will be set to the default value of: 0x420000000e00000001000000

Introduction to Mochimo "Tags"

Mochimo has an on-chain binding between a user’s WOTS+ Public Key, and a short 12-byte field called an "address tag", or just "tag". Tags are globally unique, owned by the user forever, and can only be moved from one WOTS+ address to the next by signing a transaction where the source address owns that 12-byte Tag binding. Mochimo has a unique concept in cryptocurrency called a “Change Address”, which is a required part of any transaction. The “Change Address” is where any unspent coins go, when the users does a partial spend of their wallet. The wallet specifies the new “raw” WOTS+ address in the “Change Address” field, and when the transaction is accepted on the network, the 12-byte tag binding moves to that new address on our blockchain. Creating the Tag for the first time is called “Registering” as tag, and it involves a slightly different process. The steps to creating an address tag are simple:

Creating a New Tag for the First Time

   •	Generate a WOTS Public/Secret Pair (for example using our wallet)
   •	Generate a Random 12-byte Number
   •	Confirm that new 12-byte tag is not already in use (not very likely)
       o	You can use the API endpoint: /net/resolve/[tag]
   •	Replace the last 12 bytes of any WOTS Public key (0x420000000e00000001000000 by default) with your new 12-byte tag.  Note the Mochimo wallet does this automatically for you.
   •	Register the tag on the network by sending any amount of MCM to it in a transaction with the following form:
       o	Source Address: Raw WOTS Address #1
       o	Destination Address: RAW WOTS Address #2
       o	Change Address: Your Newly Tagged WOTS Address (different from #1 and #2)
       o	Amount: [At least .000001 MCM aka 1000 satochis]

When we send to a "Change Address" and include our new tag, that tag becomes part of the block chain, and is now "bound" to that WOTS address in the blockchain ledger.

Note: It is a requirement that this registration process happens from an untagged WOTS+ address. The process of creating raw WOTS+ addresses in bulk, as well as the process of creating and registering unique tags in bulk is automated using our Command Line Wallet, and is covered in additional detail later in this document.

Introduction to Mochimo Transactions

Here is the basic flow of a person-to-person Mochimo transaction. In this example, Alice has an address tag "0x123412341234123412341234" and wants to send MCM to Bob. Her address balance has 10 MCM, and she wants to send Bob 1 MCM. 1. Alice asks Bob for his Mochimo address. 2. Bob provides Alice with a short 12-byte number, for example: 0xB0BB0BB0BB0BB0BB0BB0BB0B 3. Alice enters that tag into her Mojo Wallet and names it: "Bob". 4. Alice clicks "Send" and selects her source tag which she has named "Alice", and selects the destination address "Bob". She enters the send amount of 1 MCM, and clicks Send. 5. Alice’s Mochimo Wallet “resolves” Bob’s tag by asking the network which WOTS+ address it is bound to. • In the backend, Alice's Mochimo wallet calls the network API with the "/net/resolve" endpoint and passes it the 12-byte tag 0xB0BB0BB0BB0BB0BB0BB0BB0B. The network responds with the full WOTS address (2208 bytes ending in 0xB0BB0BB0BB0BB0BB0BB0BB0B). The wallet will use this 2208 bytes as the Destination Address for the transaction it is preparing. 6. The wallet selects an unused raw WOTS+ address from its local pool of WOTS+ Key/Secret pairs and sets it as the “Change Address” for the transaction. • The unsent coins (9MCM) will be forwarded to this Change automatically by the network. 7. The wallet creates and signs the transaction using the full WOTS address for Alice’s source, the full WOTS+ address for Bob’s destination, and the full WOTS+ address of the new Change Address. 8. The wallet connects to some network nodes and sends the full transaction. The transaction includes the digital signature of the entire transaction signed with the secret key for Alice's Source WOTS+ Address.

Note: When the node receives a transaction with a tagged address, it checks that the tag and the WOTS address binding is correct for all tagged address. If they are, it will process the transaction, otherwise it will reject it.

A Closer Look at the Example Transaction

Alice's Mochimo wallet has a pool of available "raw WOTS" Public Key/Secret Key pairs. They have no tag on the end, and instead end with the default of 0x420000000e00000001000000 tag. When it is time for Alice to SEND a transaction, the wallet picks one of those unused raw addresses, and as part of the transaction it MOVES THE TAG, from the old source address to the new Change Address. So here is what Alice sent to the network:

Tagged Source Address         - Alice's full WOTS+ address, ending in 0x123412341234123412341234
Tagged Destination Address    - Bob's full WOTS+ address, ending in 0xB0BB0BB0BB0BB0BB0BB0BB0B
Tagged Change Address         - Alice's NEW WOTS+ address, ending in 0x123412341234123412341234
Amount: 1000000000            - 1 billion satochis - AKA 1 MCM]
Fee: 500                      - Default network fee is 500 satochis
Signature:                    - The above transaction, signed with the secret key of the Source Address

The only way to move a tag from one address to another, it to sign a transaction with the private key of the Source Address, where the transaction has a Change Address with the SAME tag. When that happens, whatever balance the Source Address has minus whatever is sent to the Destination Address, will move to the Change Address. The next time someone wants to send money to Alice's 0x123412341234123412341234 tag, they will send a /net/resolve call and the full WOTS of the "Change Address" from the above transaction will now be returned, because that is what is bound to that Tag on the blockchain.

How Exchanges Use Tags

1: Create a Pool of Deterministic Addresses

An exchange will want a large pool of unused raw WOTS+ addresses to use across all users. Many exchanges opt to use the command line tool to create a pool of unused WOTS addresses/secrets, and then store them in a database. To use that tool, execute the following command: java -jar mojo.jar wots --index 0 --count 5000 --mnemonic-words "word1 word2 word3" mywots.json The above will generate 5000 WOTS/secret pairs from index 0 to 4999 using the mnemonic-words as a determinist seed and store those addresses in the file: mywots.json. You will then store these in a database.

2: Register Tags on the Network

An exchange will purchase a small amount of Mochimo, for example .0001 MCM, and send them to an untagged WOTS address (WOTS-1). They will then generate a pool of 1000 random 12-byte numbers and proceed to check that they are not in use on the network using the /net/resolve/[tag] API endpoint for each tag. For each tag1 to tag1000, the exchange will then have a script that does the following:

   Send 
       SOURCE: Raw WOTS1 Address
       DESTINATION: Raw WOTS2 Address
       CHANGE: Tagged WOTS Address Ending in tag1
       Amount 1000
       Signature
   Wait 1 Block
   
   Send 
       SOURCE: Raw WOTS 2 Address
       DESTINATION: Raw WOTS 1 Address
       CHANGE: Tagged WOTS Address Ending in tag2
       Amount 1000
       Signature
   
   Repeat
   

Notice that we are sending back and forth between WOTS1 and WOTS2, which means we're signing the same WOTS address multiple times. This is an easy way to register multiple tags. In normal use we would NOT sign the same WOTS address more than once. Tag registration is the only exception. Since we only have .0001 MCM in those addresses, we don't worry about the security implications for this method. There are other ways to do this, but this is the quickest/easiest.

At the end of this this process, we have 1000 Registered Address Tags in our database that are bound to 1000 of our WOTS Address Pairs.

3: Assign an Address Tag to Each User Account

When a user buys MCM coins for the first time on the exchange, or when they click the "Receive Address" button for first time, the exchange looks in its pool of unused Registered Address Tags, and PERMANENTLY assigns one to the user. From that moment, on the user can send and receive coins from that address tag.

4: Sending Coins - Create the Transaction File

When the user wants to send coins off the exchange, the exchange collects the "destination tag" from the user, and then does an API call to find the full WOTS address: /net/resolve/[tag]. The exchange then creates a transaction file using the CLI:

  java -jar mojo.jar sign \
  --source-wots USERS-FULL-WOTS-ADDRESS-WITH-TAG \
  --source-secret SECRETKEY-FOR-USERS-WOTS-ADDRESS \
  --destination-wots FULL-ADDRESS-RETURNED-BY-NET-RESOLVE-API \
  --change-wots NEW-UNUSED-WOTS-ADDRESS-FROM-DATABASE-ADDING-USERS-TAG \
  --offline \
  --source-balance CURRENT_BALANCE AMOUNT_TO_SEND \
  FILENAME

Call the above jar file and pass it the user's source address and secret, select an unused WOTS address from the pool of 5000 raw addresses in your database. Mark it as used. Add the user's tag to the last 12 bytes to create the "change address" for the transaction. Add the destination address that was resolved by the API and specify that you want to generate a transaction file offline. Pass it the source address's balance and the amount you want to send. Finally include the file name you want the BASE64 encoded transaction stored in.

5: Sending Coins - Use the API to Send the TX

Now complete an API call (in this example we show the URL for the Mochimo Public API, but you can maintain your own - and we recommend that you do.) To post that transaction to 5 random nodes on the network using the "/push" API endpoint complete the TX as follows: http://api.mochimo.org:8888/push POST {"transaction": [base64 encoded transaction from file], "recipients": 5} With the above approach, the exchange marks the old address as "used" in the database, and marks the new "change address" with the moved tag as the "current" address. The user's address tag never changes.