---
# System prepended metadata

title: Idea to re-factor XCO related code

---


Idea to re-factor XCO related code
=====================================


## Goals:


- Move as much as possible of the blockchain logic to a coinweb node -> avoid code duplication

- Remove unnecesary blockchain logic from onramp DB 
   -  Simplify onramp code.
   -  Remove common sources of bugs and preformance bottlenecks.



- Reduce the chances for a change on coinweb's protocol to break onramp implementation.

- Reduce the client dependencies

- **Onramp stores only XCO information relevant to onramp**

  - so all xco information on onramp will be related to an operation

## Overview:

Instead of keeping track of every xco transaction and storing them on tables, the system will communicate with a coinweb node, sending and receiving events
from/to the same way it would do so with any other external service. In addition to that, sql-domains used to represent related information (i.e xco-address, 
xco-txid ...etc) should become more loose, such that if coinweb changes its formats, no changes on onramp will need to be applied.


The coinweb-node will have a public api to be called by the clients, and a private one (i.e authenticated) to be called by the onramp backend. Notice,
the coinweb node will have other APIs non-relevant to onramp, and other users not related to onramp, the coinweb code will eventually be developed by 
another team. Onramp will have its own instance of a coinweb-node.


### Public API:

- send-transaction: Just the same as what the signer verifier is currently doing at `rpc/l2coin_payment` .

- get-info:
  
  - input: User master public key and date the master public key was created.

  - output: Balances on l1 and l2 coins and tokens, utxos for thos coins and tokens where it makes sense, nonce for those coins 
    and tokens where it makes sens. Any other info the client might need.


  - this endpoint will be implemented as http and websocket endpoints.


### Private Blockchain:

- create-account: Makes the coinweb node aware of a system account, so it starts tracking them.

  - input:
    - account-name
    - (optional) account master pub key
    - account description
    - account initial balance
    - (optional) issuer pubkey or account-name (if the initial balance is different than 0, from who we 
      should withdrawal the initial balance)
  
  - output: account master pub key


- issue-funds:
  
  - input
    - sender (either account name, or master pub key)
    
    - amount
    
    - currency

    - attached-data (json): information to embed inside of the transaction, so it will be shown in the explorer. If inside attached-data there's some object
      following the pattern `{ hash: «content»}`, instead of storing `«content»`, it will store the hash of `«content»`.

    - batch (boolean): if true, it will not broadcast the transaction to the blockchain immediately, though it will seem for users as if that were the case.
  
    - (optional) batch-group: if different than null, it will associate the transaction getting issued to this batch-group. To fund this transaction the coinweb node
      might use non-committed utxo from the same batch-group as if they were comitted.
      not-committed utxo

  - output:
    - txid
    - batch-group (null if `batch = false`)

- commit-xco-transaction:
  - input:
    - list of the txid of the batched transaction to commit.

  - output:
    - l1 currency spent broadcasting.

  - description:
    - broadcast batched transactions, after this is done **they will become immutable**. If a batched transaction depends on a previous batched transaction, it will
      need to get commit before or at the same call, otherwise this call will fail. Attempting to commit an already commited transaction will not have any effect and
      it will not be considered an error. Attempting to commit a rollback transaction, will be considered an error.

- rollback-xco-transaction:
  - input:
    - list of the txid of the batched transaction to rollback.

  - output:
    - 'ok'.

  - description:
    - undo transactions that has not been committed yet. If you attempt to rollback a transaction that have some other batched transactions depending on it, you would need
      to rollback the later before or at the same call, otherwise the call will fail. Attempting to rollback a already rollbacked transaction will not have any effect and
      it will not be considered an error. Attempting to rollback a commit transaction will be considered an error. In some circumstances, a transaction can get rollbacked
      on its own without this function getting called, for example, in the case of a double-spent attempt.

- set-callbacks:
  
  - input: 
    - callback_url: the url where to receive events notifications.
    
    - (optional) since: 

  - output: the xco-node-id of the coinweb node (currently not used).

  - description: Configure the coinweb-node to send events to the given url as callbacks. The coinweb node will re-send the same event (i.e callbacks with the same `event_id`)
    every time the event payload changes, or if onramp didn't response correctly (i.e "200 ok") to the callback.

    events: 
     - funds_events: For every payment done, a `funds_events` will get generated. Every time one of its fields (i.e number_of_confirmations, rejected, valid...etc)
       changes, **the event will be resent**.

       - event_id: Primary key of the event, for `funds_events` it is always the same as `utxo`.

       - amount:
       
       - currency:
       
       - address:
       
       - derivation index

       - receiver pub key (null if it belongs to an user)

       - receiver hash pub key

       - utxo:
       
       - number_of_confirmations: (0 if on the mempool, -1 if it became invalid, minimum between the number of confirmation and maximum threshold)
       
       - txid:
       
       - batch_group (null if committed)
       
       - rejected: true if this used to be a valid transaction, but now it is no longer a valid transaction (i.e a successful double spent) 

       - valid: one of:
         - high-chance-of-acceptance
         - might-get-accepted
         - invalid

### Blockexplorer API:

The coinweb node will keep the same inerface for the blockexplorer; so for the blockexplorer frontend side the only change would be to call coinweb instead of onramp.

## Gradual Implementation:

> To implement this, we'll need to wait the Coinweb node to be more mature (it is not clear yet how the coinweb node development timeline will be). As the coinweb node prototype gradually became more mature, the different parts of the refactorization will get unlocked. Once possible the `piece_transaction` and `body_transaction` should get removed.  

## Tasks:

