• Proxy This repository contains the proxy contract which allows several operations. Before deploying a proxy (i.e. a ~MateriaFactory~) it's necessary to have an already existing ~MateriaFactory~ which is not initialized, the constructor requires the following parameters:

• ~doubleProxy~ (the DFO's double proxy address)
• ~factory~ (the ~MateriaFactory~ address)
• ~bridgeToken~ (the bridge token ERC20 address e.g. uSD)

** DeFi In questa sezione descriveremo le possibili operazioni DeFi effettuabili e come eseguirle. Innanzitutto occorre precisare gli attori coinvolti:

• Questo contratto, ovvero il proxy
• La collection ERC20Wrapper di EthItem
• La factory, atta è creare le pair

*** Operazioni Le operazioni sono le seguenti e sono tutte da intendersi tra token gia' wrappati in EthItem. Ovvero supporremo che l'utente gia' possiede gli EthItem necessari nella collection ERC20Wrapper e che potra' ricevere solo EthItem come esito delle operazioni. Tutte queste operazioni, per evitare ~approve~ che renderebbero necessarie molteplici transazioni, sono svolte come trasferimenti di token ERC1155 (ricordo che ERC20Wrapper è un superset di ERC1155) quindi richiedono di chiamare di chiamare i metodi ~SafeTransfer~ e ~SafeBatchTransfer~ di ERC20Wrapper.

**** Adding liquidity Occorre chiamare il metodo ~SafeBatchTransfer~ di ERC20Wrapper con i seguenti parametri:

• ~_from~ è colui che ricevera' l'LP
• ~_to~ è l'address del proxy
• ~_ids~ è un array di interi contenenti gli object id degli item nella collection che voglio inviare
• ~_values~ è l'array delle corrispettive quantita'
• ~_data~ è un array di byte contenente il payload

L'operazione che stiamo effettuando individua un ~id~ univoco, il payload come primo valore (~uint256~) contiene questo identificativo, acnora da decidere. Gli altri valori nel payload, in ordine, sono:

• ~amountAMin~ che è il valore minimo per cui siamo disposti ad effettuare l'add liquidity.
• ~amountBMin~ come sopra
• ~to~ è l'address che ricevera' l'LP
• ~deadline~ timestamp oltre il quale la transazione fallira' necessariamente.

Uno dei due object id deve essere quello di uSD.

Nel caso di insuccesso la transazione non viene aggiunta a nessun blocco e quindi gli Item rimangono al chiamante. Nel caso di successo viene aggiunta liquidita' (creando la pair se non esiste) per almeno i valori ~amountAmMin~ e ~amountBMin~, la due eventuali rimanenze vengono reinviate a ~_from~. Viene mintato un LP come ERC20, viene wrappato nella collection ERC20Wrapper e viene inviato a to.

**** Removing liquidity Occorre chiamare il metodo ~SafeTransfer~ di ERC20Wrapper con i seguenti parametri:

• ~_from~ è colui che ricevera' l'LP
• ~_to~ è l'address del proxy
• ~_id~ è l'id del LP (gia' wrappato in EthItem!)
• ~_value~ è la quantita' di tale LP
• ~_data~ è un array di byte contenente il payload

L'operazione che stiamo effettuando individua un ~id~ univoco, il payload come primo valore (~uint256~) contiene questo identificativo, ancora da decidere. Gli altri valori nel payload, in ordine, sono:

• ~to~ è l'address che rivera i due item
• ~deadline~ timestamp oltre il quale la transazione fallira' necessariamente.

Nel caso di insuccesso la transazione non viene aggiunta a nessun blocco e quindi l'Item rimane al chiamante. Nel caso di successo vengono inviati a ~_from~ i due item, in maniera proporzionale al LP inviato (l'LP viene riconvertito in ERC20 dal proxy e poi bruciato.)

**** Swapping Exact To Inexact Occorre chiamare il metodo ~SafeTransfer~ di ERC20Wrapper con i seguenti parametri:

• ~_from~ è colui che ricevera' l'LP
• ~_to~ è l'address del proxy
• ~_id~ è l'id dell'item che voglio dare
• ~_value~ è la quantita' di tale item
• ~_data~ è un array di byte contenente il payload

L'operazione che stiamo effettuando individua un ~id~ univoco, il payload come primo valore (~uint256~) contiene questo identificativo, ancora da decidere. Gli altri valori nel payload, in ordine, sono:

• ~otherItem~ è l'item che voglio ricevere in cambio
• ~amountOutMin~ è la soglia di quantita sotto la quale non accetterò il token in cambio
• ~to~ è l'address che rivera l'item
• ~deadline~ timestamp oltre il quale la transazione fallira' necessariamente.

Nel caso di insuccesso la transazione non viene aggiunta a nessun blocco e quindi l'Item rimane al chiamante. Nel caso di successo viene scambiato ~_value~ di item con id ~_id~ con almeno ~amountOutMin~ di token con id ~otherItem~, il destinatario del token in uscita è sempre ~to~.

**** Swapping Inexact to Exact Analogo al precedente ma scelgo in maniera esatta quanto voglio ricevere e dispongo un bound al massimo che sono disposto a dare. A differenza dell'operazione precedente questo caso prevede un rimborso della rimanenza, come avviene nell'operazione di aggiunta di liquidita'.

**** Fee on transfer Swapping Exact To Inexact Da scrivere (e capire bene prima)

**** Fee on transfer Swapping Inexact To Exact Da scrivere (e capire bene prima)

*** Wrapping (con conseguente operazione tra le precedenti, eventualmente) Per effettuare il wrap di un token, da semplice token ERC20 a item nella collection ERC20Wrapper di EthItem, basta chiamare il metodo ~wrap~ del contrato proxy con i seguenti parametri:

• ~tokens~ è l'array degli indirizzi dei token ERC20 che sto wrappando
• ~amounts~ è l'array delle rispettive quantita'
• ~receiver~ è colui che ricevera' gli item dopo il wrap
• ~payload~ è il payload che verra' eseguito dal ricevente, nel caso esso sia un contratto e implementi ~ERC1155Receiver~

Prima di effettuare questa chiamata bisogna aver fatto un ~approve~ del proxy a muovere tutti questi token delle quantita' desiderate. Inoltre la transazione può avere un valore (~msg.value~), tale quantita' viene wrappata come item in ERC20WRapper.

Importante: è possibile effettuare una qualsiasi delle operazioni descritte precedentemente nella stessa transazione del wrapping sfruttando il fatto che il proxy è un + ~ERC1155Receiver~, ovvero usando l'indirizzo del proxy come ~receiver~ e un opportuno payload.

*** Unwrapping Per ognuna delle operazioni descritte sopra (quelle scandite da differenti ~id~ nel payload) esiste una versione che integra un conseguente unwrap. L'unwrap invece di inviare l'item al ~to~ deciso nel payload, invia direttamente il token ERC20 unwrappato. Propongo di usare come convenzione che nel caso di id maggiori di N queste operazioni sono uguali a quelle con lo stesso id meno N, con la differenza di fare unwrap alla fine. Per esempio supponiamo N=500, se 2 indica l'operazione di swap Exact to Inexact allora 502 potrebbe indicare la stessa operazione con però conseguente unwrap.

** Conclusioni finali Il grande vantaggio di questa struttura è che per aggiungere una nuova operazione è sufficiente aggiungere un solo metodo al proxy, e associarlo ad uno specifico id aggiungendolo nel grosso "switch case" di uno dei callback che vengono chiamati quando il proxy riceve gli Item. Facendo così si ha gratis, senza aggiungere neppure una riga di codice, la versione con unwrap finale (se l'id è maggiore di N viene eseguita l'opeazione id-N e viene poi fatto l'unwrap), la versione con wrap (basta chiamare ~wrap~ e passare il nuovo id nel payload) e la versione che fa entrambe le cose.

#+begin_src +----------------------------<----------------------------------------------------------<------------------+ | | | +------------------------------------+ | | | | ^ v | +------------------------+ | +-->-+Swap Exact2Inexact (+ unwrap) | | | v |PROXY | | | Swap Inexact2Exact (+ unwrap) | +-+--+ | | +------------------------+ | | Swap fee on transfer Exact2Inexact (+ unwrap) |--->-----+USER| +-->-+wrap() +--->----+ | Swap fee on transfer Inexact2Exact (+ unwrap) | +-+--+ +->+onERC1155Received() |--->--------+ ...new operations... | | |onERC1155BatchReceived()+--->------+ | +------------------------+ +---->-+Add liquidity | | Remove liquidity |------------->--------------+ Batch swap (future) | ...new awesome operations... | #+end_src