Source: engine.js

  1. /*
  2. * @Author: amitshah
  3. * @Date:   2018-04-17 00:55:47
  4. * @Last Modified by:   amitshah
  5. * @Last Modified time: 2018-04-28 23:43:00
  6. */
  8. const messageLib = require('./message');
  9. const channelLib = require('./channel');
  10. const channelStateLib = require('./channelState');
  11. const stateMachineLib = require('./stateMachine/stateMachine');
  12. const util = require('ethereumjs-util');
  13. const events = require('events');
  16. /** 
  17. * @class GoNetworks Engine encapsualtes off chain interactions between clients and propogation onto the blockchain.  
  18. * The Engine is platform agnostic and adaptble to different blockchains by providing appropriate blockchainService adapters
  19. * Overriding the send callback also allows for custom transport layers and methods (not neccessarily IP network based)
  20. * @extends events.EventEmitter
  21. * @property {BN} msgID=0
  22. * @property {BN} currentBlock=0 - the current block which is synchronized to the onchain mined block value via blockchainService handler callbacks
  23. * @property {Buffer} publicKey - Future Use: ElGamal Elliptic Curve Asymmetric Encryption public key to be sent to channel partners
  24. * @property {InitiatorFactory} initiatorStateMachine=stateMachine.IntiatorFactory - creates a new state machine for mediated transfers you initiate
  25. * @property {TargetFactory} targeStateMachine=stateMachine.TargetFactory - creates a new state machine for mediated transfers that are intended for you 
  26. * @property {object} messageState={} - tracks the state of mediated transfer messages using msgID as the key i.e. this.messageState[msgID] = stateMachine.*
  27. * @property {object} channelByPeer={} - channels by peers ethereum address as hex string no 0x prefix 
  28. * @property {object} channels={} - channels by on-chain contract address hex string no 0x prefix
  29. * @property {object} pendingChannels={} - used to track newChannel requests initiated by the engine
  30. * @property {function} signatureService 
  31. * @property {object} blockchain
  32. */
  33. class Engine extends events.EventEmitter {
  35.   /**
  36.    * @constructror.
  37.    * @param {Buffer} address - your ethereum address; ETH Address is merely the last 20 bytes of the keccak256 hash of the public key given the public private key pair.
  38.    * @param {Function} signatureService - the callback that requests the privatekey for signing of messages.  This allows the user to store the private key in a secure store or other means
  39.    * @param {BlockchainService} blockchainService - a class extending the BlockchainService class to monitor and propogate transactions on chain. Override for different Blockchains
  40.    */
  41.   constructor(address,signatureService,blockchainService){
  42.     super();
  43.    
  44.     //dictionary of channels[peerAddress] that are pending mining
  45.     this.pendingChannels = {};
  46.     this.channels = {};
  47.     //dictionary of channels[peerState.address.toString('hex')];
  48.     this.channelByPeer = {};
  49.     //dictionary of messages[msgID] = statemachine.*
  50.     this.messageState = {};
  52.     this.currentBlock = new util.BN(0);
  53.     this.msgID = new util.BN(0);
  55.     this.publicKey;
  56.     this.address = address;
  57.     this.initiatorStateMachine = stateMachineLib.InitiatorFactory();
  58.     this.targetStateMachine = stateMachineLib.TargetFactory();
  59.     var self = this;
  60.     this.initiatorStateMachine.on("*",function(event,state){
  61.       self.handleEvent(event,state);
  62.     });
  63.     this.targetStateMachine.on("*",function(event,state){
  64.       self.handleEvent(event,state);
  65.     });
  67.     this.signature = signatureService;
  68.     this.blockchain = blockchainService;
  69.     //sanity check
  70.     if(!channelLib.SETTLE_TIMEOUT.gt(channelLib.REVEAL_TIMEOUT)){
  71.       throw new Error("SETTLE_TIMEOUT must be strictly and much larger then REVEAL_TIMEOUT");
  72.     }
  73.     this.currentBlock = new util.BN(0);
  74.   }
  76.   /**
  77.      * Handle an incoming message after it has been deserialized
  78.      * @param {message.SignedMessage} message
  79.      * @returns {message.Ack}
  80.      * @throws "Invalid Message: no signature found"
  81.      * @throws "Invalid Message: uknown message received"
  82.      */
  83.   onMessage(message){
  84.     //TODO: all messages must be signed here?
  85.     if(!message.isSigned()){
  86.       throw new Error("Invalid Message: no signature found");
  87.     }
  89.     if(message instanceof messageLib.RequestSecret){
  90.       this.onRequestSecret(message);
  91.     }else if(message instanceof messageLib.RevealSecret){
  92.       this.onRevealSecret(message);
  93.     }else if(message instanceof messageLib.MediatedTransfer){
  94.       this.onMediatedTransfer(message);
  95.     }else if(message instanceof messageLib.DirectTransfer){
  96.       this.onDirectTransfer(message);
  97.     }else if(message instanceof messageLib.SecretToProof){
  98.       this.onSecretToProof(message);
  99.     }else{
  100.       throw new Error("Invalid Message: uknown message received");
  101.     }
  102.     
  103.     return new messageLib.Ack({msgID:message.msgID, messageHash:message.getHash(), to:message.from});
  104.     
  105.   }
  107.   onRequestSecret(requestSecret){
  108.     if(this.messageState.hasOwnProperty(requestSecret.msgID)){
  109.       this.messageState[requestSecret.msgID].applyMessage('receiveRequestSecret',requestSecret);
  110.     }
  112.   }
  114.   onRevealSecret(revealSecret){
  115.     //handle reveal secret for all channels that have a lock created by it
  116.     //we dont care where it came from unless we want to progress our state machine
  117.     var errors = [];
  118.     Object.values(this.channelByPeer).map(function (channel) {
  119.       try{
  120.         channel.handleRevealSecret(revealSecret);
  121.       }catch(err){
  122.         errors.push(err)
  123.       }
  125.     });
  126.     //update all state machines that are in awaitRevealSecret state
  127.     Object.values(this.messageState).map(function (messageState) {
  128.       try{
  129.         //the state machines will take care of echoing RevealSecrets
  130.         //to channel peerStates
  132.         messageState.applyMessage('receiveRevealSecret',revealSecret);
  133.       }catch(err){
  134.         errors.push(err)
  135.       }
  136.     });
  138.     errors.map(function (error) {
  139.       console.log(error);
  140.     });
  141.   }
  143.   onSecretToProof(secretToProof){
  144.     //handle reveal secret for all channels that have a lock created by it.
  145.     //this is in the case where for some reason we get a SecretToProof before
  146.     //a reveal secret
  148.     //encapsulate in message.RevealSecret type of message, we dont have to sign it
  149.     //it is not required
  150.     var tempRevealSecret = new messageLib.RevealSecret({secret:secretToProof.secret})
  151.     this.signature(tempRevealSecret);
  152.     Object.values(this.channelByPeer).map(function (channel) {
  153.       try{
  155.         channel.handleRevealSecret(tempRevealSecret);
  156.       }catch(err){
  157.         console.log(err);
  158.       }
  160.     });
  162.     Object.values(this.messageState).map(function (messageState) {
  163.       try{
  164.         //the state machines will take care of echoing RevealSecrets
  165.         //to channel peerStates
  166.         messageState.applyMessage('receiveRevealSecret',tempRevealSecret);
  167.       }catch(err){
  168.         console.log(err);
  169.       }
  170.     });
  172.     if(!this.channelByPeer.hasOwnProperty(secretToProof.from.toString('hex'))){
  173.       throw new Error("Invalid SecretToProof: unknown sender");
  174.     }
  176.     var channel = this.channelByPeer[secretToProof.from.toString('hex')];
  177.     channel.handleTransfer(secretToProof,this.currentBlock);
  178.     if(this.messageState.hasOwnProperty(secretToProof.msgID)){
  179.       this.messageState[secretToProof.msgID].applyMessage('receiveSecretToProof',secretToProof);
  180.     }else{
  181.       //Something went wrong with the statemachine :(
  182.     }
  185.   }
  187.   onDirectTransfer(directTransfer){
  188.     if(!this.channelByPeer.hasOwnProperty(directTransfer.from.toString('hex'))){
  189.       throw new Error('Invalid DirectTransfer: channel does not exist');
  190.     }
  192.     var channel = this.channelByPeer[directTransfer.from.toString('hex')];
  193.     if(!channel.isOpen()){
  194.       throw new Error('Invalid Channel State:state channel is not open');
  195.     }
  197.     console.log("EMIT TO UI: transferred:"+directTransfer.transferredAmount.sub(channel.peerState.transferredAmount));
  198.     channel.handleTransfer(directTransfer,this.currentBlock);
  199.   }
  201.   onMediatedTransfer(mediatedTransfer){
  202.     if(!this.channelByPeer.hasOwnProperty(mediatedTransfer.from.toString('hex'))){
  203.       throw new Error('Invalid MediatedTransfer: channel does not exist');
  204.     }
  206.     var channel = this.channelByPeer[mediatedTransfer.from.toString('hex')];
  207.     if(!channel.isOpen()){
  208.       throw new Error('Invalid MediatedTransfer Received:state channel is not open');
  209.     }
  210.     //register the mediated transfer
  212.     channel.handleTransfer(mediatedTransfer,this.currentBlock);
  213.     if(mediatedTransfer.target.compare(this.address)===0){
  214.       console.log("Start targetStateMachine");
  215.       this.messageState[mediatedTransfer.msgID] = new stateMachineLib.MessageState(mediatedTransfer,this.targetStateMachine);
  216.       this.messageState[mediatedTransfer.msgID].applyMessage('init',this.currentBlock);
  217.     }
  218.   }
  220.   /**
  221.      * Send a locked transfer to your channel partner. This method intiatlizes a initator state machine which will queue the message for send via handleEvent
  222.      * @param {Buffer} to - eth address who this message will be sent to.  Only differs from target if mediating a transfer
  223.      * @param {Buffer} target - eth address of the target.
  224.      * @param {BN} amount - amount to lock and send.
  225.      * @param {BN} expiration - the absolute block number this locked transfer expires at.
  226.      * @param {Buffer} secret - Bytes32 cryptographic secret
  227.      * @param {Buffer} hashLock - Bytes32 keccak256(secret) value.
  228.      * @throws "Invalid MediatedTransfer: channel does not exist"
  229.      * @throws 'Invalid Channel State:state channel is not open'
  230.      */
  231.   sendMediatedTransfer(to,target,amount,expiration,secret,hashLock){
  232.     if(!this.channelByPeer.hasOwnProperty(to.toString('hex'))){
  233.       throw new Error("Invalid MediatedTransfer: channel does not exist");
  234.     }
  235.     var channel = this.channelByPeer[to.toString('hex')];
  236.     if(!channel.isOpen()){
  237.       throw new Error('Invalid Channel State:state channel is not open');
  238.     }
  240.     //var expiration = this.currentBlock.add(channel.SETTLE_TIMEOUT);
  241.     var msgID = this.incrementedMsgID();
  242.     var mediatedTransferState = ({msgID:msgID,
  243.       "lock":{
  244.         hashLock:hashLock,
  245.         amount:amount,
  246.         expiration:expiration,
  247.       },
  248.       target:to,
  249.       initiator:this.address,
  250.       currentBlock:this.currentBlock,
  251.       secret:secret,
  252.       to:channel.peerState.address});
  254.     this.messageState[msgID] = new stateMachineLib.MessageState(mediatedTransferState,this.initiatorStateMachine);
  255.     this.messageState[msgID].applyMessage('init');
  256.   }
  260.   /**
  261.      * Send a direct transfer to your channel partner.  This method calls send(directTransfer) and applies the directTransfer to the local channel state.
  262.      * @param {Buffer} to - eth address who this message will be sent to.  Only differs from target if mediating a transfer
  263.      * @param {Buffer} transferredAmount - the monotonically increasing amount to send.  This value is set by taking the previous transferredAmount + amount you want to transfer.
  264.      * @throws "Invalid MediatedTransfer: unknown to address"
  265.      * @throws 'Invalid DirectTransfer:state channel is not open'
  266.      */
  267.   sendDirectTransfer(to,transferredAmount){
  268.     if(!this.channelByPeer.hasOwnProperty(to.toString('hex'))){
  269.       throw new Error("Invalid MediatedTransfer: unknown to address");
  270.     }
  271.     var channel = this.channelByPeer[to.toString('hex')];
  272.     if(!channel.isOpen()){
  273.       throw new Error('Invalid DirectTransfer:state channel is not open');
  274.     }
  275.     var msgID = this.incrementedMsgID();
  276.     var directTransfer = channel.createDirectTransfer(msgID,transferredAmount);
  277.     this.signature(directTransfer);
  278.     this.send(directTransfer);
  279.     channel.handleTransfer(directTransfer);
  280.   }
  282.   incrementedMsgID(){
  283.     this.msgID = this.msgID.add(new util.BN(1));
  284.     return this.msgID;
  285.   }
  288.   /**Send the message. Override this function to define different transport channels
  289.      * e.g integrate this with TELEGRAMS Api and securely transfer funds between users on telegram.
  290.      * Generate qrcodes for revelSecret message
  291.      * or implement webRTC p2p protocol for transport etc.
  292.      * @param {message} msg - A message implementation in the message namespace 
  293.      */
  294.   send(msg){
  295.     console.log("SENDING:"+messageLib.SERIALIZE(msg));
  296.   }
  298.   /** Internal event handlers triggered by state-machine workflows and blockchain events
  299.   * @param {string} event - the GOT.* namespaced event triggered asynchronously by external engine components i.e. stateMachine, on-chain event handlers,etc.
  300.   * @param {object} state - the accompanying object state 
  301.   */
  302.   handleEvent(event, state){
  303.     try{
  305.       if(event.startsWith('GOT.')){
  306.         switch(event){
  307.           case 'GOT.sendMediatedTransfer':
  308.             var channel = this.channelByPeer[state.to.toString('hex')];
  309.             if(!channel.isOpen()){
  310.               throw new Error("Channel is not open");
  311.             }
  313.             //msgID,hashLock,amount,expiration,target,initiator,currentBlock
  314.             var mediatedTransfer = channel.createMediatedTransfer(state.msgID,
  315.               state.lock.hashLock,
  316.               state.lock.amount,
  317.               state.lock.expiration,
  318.               state.target,
  319.               state.initiator,
  320.               state.currentBlock);
  321.             this.signature(mediatedTransfer);
  322.             this.send(mediatedTransfer);
  323.             channel.handleTransfer(mediatedTransfer);
  324.             break;
  325.           case 'GOT.sendRequestSecret':
  326.             var channel = this.channelByPeer[state.to.toString('hex')];
  327.             var requestSecret = new messageLib.RequestSecret({msgID:state.msgID,to:state.from,
  328.               hashLock:state.lock.hashLock,amount:state.lock.amount});
  329.             this.signature(requestSecret);
  330.             this.send(requestSecret);
  331.             break;
  332.           case 'GOT.sendRevealSecret':
  333.             var channel = this.channelByPeer[state.to.toString('hex')];
  334.             //technically, this workflow only works when target == to.  In mediated transfers
  335.             //we need to act more generally and have the state machine tell us where we should
  336.             //send this secret (backwards and forwards maybe)
  337.             var revealSecret = new messageLib.RevealSecret({to:state.revealTo, secret:state.secret});
  338.             this.signature(revealSecret);
  339.             this.send(revealSecret);
  340.             //we dont register the secret, we wait for the echo Reveal
  341.             break;
  342.           case 'GOT.sendSecretToProof':
  343.             var channel = this.channelByPeer[state.to.toString('hex')];
  344.             //OPTIMIZE:technically we can still send sec2proof,
  345.             //it would beneficial to our partner saving $$ for lock withdrawal
  346.             //but for now we act in no interest of the  peer endpoint :( meanie
  347.             if(!channel.isOpen()){
  348.               throw new Error("Channel is not open");
  349.             }
  351.             var secretToProof = channel.createSecretToProof(state.msgID,state.secret);
  352.             this.signature(secretToProof)
  353.             channel.handleTransfer(secretToProof);
  354.             this.send(secretToProof);
  355.             //TODO: in the future, wait to apply secret to proof locally. We basically locked the state up now
  356.             //It makes sense, in a sense.  With this implementation, when a lock secret is revealed and echoed back
  357.             // the peer MUST accept a valid SecretToProof or no more new transfers can take place as the states are unsynced
  358.             //By having the peer echo back, we dont really do much difference, the state is simplex
  359.             
  360.             break;
  361.           case 'GOT.closeChannel':
  362.             var channel = this.channelByPeer[state.from.toString('hex')];
  363.             //TODO emit closing
  364.             return this.closeChannel(channel.channelAddress);
  365.             //channel.handleClose(this.currentBlock);
  366.             break;
  367.           case 'GOT.issueSettle':
  368.             //TODO emit "IssueSettle to ui + channel";
  369.             var channelAddress = state;
  370.             console.log("CAN ISSUE SETTLE:"+channelAddress.toString('hex'));
  371.             break;
  372.           }
  373.           return;
  374.         }
  375.       }
  376.     catch(err){
  377.       this.handleError(err);
  378.     }
  379.   }
  381.    /*** Internal error handler triggered by errors encountered by handleEvent  
  382.     * @param {Error} err - the error caught during handleEvent execution
  383.    */
  384.   handleError(err){
  385.     console.error(err);
  386.   }
  387.    
  388.   /*** Blockchain callback when a new block is mined and blockNumber increases.  
  389.   *This informs the engine of time progression via block number increments crucial for lockedtransfer
  390.   * and channel lifecycle management
  391.   * @param {BN} block - the latest mined block
  392.   */
  393.   onBlock(block){
  394.     if(block.lt(this.currentBlock)){
  395.       throw new Error("Block Error: block count must be monotonically increasing");
  396.     }
  398.     this.currentBlock = block;
  399.     //handleBlock by all the in-flight messages
  400.     //timeout or take action as needed
  401.     var self = this;
  402.     Object.values(this.messageState).map(function (messageState) {
  403.       try{
  404.         console.debug("CALL HANDLE BLOCK ON MESSAGE");
  405.         messageState.applyMessage('handleBlock',self.currentBlock);
  406.       }catch(err){
  407.         console.log(err);
  408.       }
  409.     });
  410.     //handleBlock for each of the channels, perhaps SETTLE_TIMEOUT has passed
  411.     Object.values(this.channels).map(function(channel){
  412.       console.debug("CALL HANDLE BLOCK ON CHANNEL");
  413.       var events  = channel.onBlock(self.currentBlock);
  414.       for(var i=0; i < events.length; i++){
  415.         self.handleEvent.apply(events[i]);
  416.       }
  417.     });
  418.   }
  420.   /** Create a new channel given the peer ethereum address 
  421.   * @param {Buffer} peerAddress - eth address
  422.   * @returns {Promise} - the promise is settled when the channel is mined.  If there is an error during any point of execution in the mining
  423.   * the onChannelNewError(peerAddress) is called
  424.   */
  425.   newChannel(peerAddress){
  426.     //is this a blocking call?
  427.     if(!this.pendingChannels.hasOwnProperty(peerAddress.toString('hex')) &&
  428.      this.channelByPeer.hasOwnProperty(peerAddress.toString('hex')) 
  429.       && this.channelByPeer[peerAddress.toString('hex')].state !== channelLib.CHANNEL_STATE_SETTLED){
  430.       throw new Error("Invalid Channel: cannot create new channel as channel already exists with peer and is unsettled");
  431.     }
  432.     this.pendingChannels[peerAddress.toString('hex')] = true;
  433.     var self = this;
  434.     var _peerAddress = peerAddress;
  435.     return this.blockchain.newChannel(peerAddress,channelLib.SETTLE_TIMEOUT).then(function(vals) {
  436.       // ChannelNew(address netting_channel,address participant1,address participant2,uint settle_timeout);
  437.       // var channelAddress = vals[0];
  438.       // var addressOne = vals[1];
  439.       // var addressTwo = vals[2];
  440.       // var timeout = vals[3];
  441.       //self.onChannelNew(channelAddress,addressOne,addressTwo,timeout);
  442.     }).catch(function (err) {
  443.       self.onChannelNewError(_peerAddress);
  444.     });
  445.     
  446.   };
  448.    /** close a channel given the peer ethereum address.  The close proof in the state is transferred during the call to close.
  449.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  450.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  451.   * the onChannelCloseError(channelAddress) is called
  452.   */
  453.   closeChannel(channelAddress){
  454.     if(!this.channels.hasOwnProperty(channelAddress.toString('hex'))){
  455.       throw new Error("Invalid Close: unknown channel");
  456.     }
  457.     var channel = this.channels[channelAddress.toString('hex')];
  458.     if(!channel.isOpen()){
  459.       throw new Error("Invalid Close: Cannot reissue Closed");
  460.     }
  462.     var proof = channel.issueClose(this.currentBlock);
  463.     var self = this;
  464.     var _channelAddress = channelAddress;
  466.     return this.blockchain.closeChannel(channelAddress,proof).then(function(closingAddress){
  467.       //channelAddress,closingAddress,block
  468.       //TODO: @Artur, only call this after the transaction is mined i.e. txMulitplexer 
  469.       // return self.onChannelClose(_channelAddress,closingAddress);
  470.     }).catch(function(error){
  471.       return self.onChannelCloseError(_channelAddress);
  472.     });
  473.   
  474.     
  475.   }
  477.   /** Update the proof after you learn a channel has been closed by the channel counter party 
  478.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  479.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  480.   * the onTransferUpdatedError(channelAddress) is called
  481.   */
  482.   transferUpdate(channelAddress){
  483.     if(!this.channels.hasOwnProperty(channelAddress.toString('hex'))){
  484.       throw new Error("Invalid TransferUpdate: unknown channel");
  485.     }
  486.     var channel = this.channels[channelAddress.toString('hex')];
  487.     if(channel.isOpen()){
  488.       throw new Error("Invalid TransferUpdate: Cannot issue update on open channel");
  489.     }
  490.     var proof = channel.issueTransferUpdate(this.currentBlock);
  491.     var self = this;
  492.     var _channelAddress = channelAddress;
  493.     
  494.     return this.blockchain.updateTransfer(channelAddress, proof).then(function(nodeAddress){
  495.       //self.onTransferUpdated(nodeAddress)
  496.     }).catch(function(err) {
  497.       self.onTransferUpdatedError(_channelAddress);
  498.     })
  499.     
  500.   }
  502.    /** Issue withdraw proofs on-chain for locks that have had their corresponding secret revealed.  Locks can be settled on chain once a proof has been sent on-chain.
  503.    * Locks can only be withdrawn once.
  504.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  505.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  506.   * the onChannelSecretRevealedError(channelAddress) is called for each lock that was not successfully withdrawn on-chain and must be reissued
  507.   */
  508.   withdrawPeerOpenLocks(channelAddress){
  509.     if(!this.channels.hasOwnProperty(channelAddress.toString('hex'))){
  510.       throw new Error("Invalid Withdraw: unknown channel");
  511.     }
  512.     var channel = this.channels[channelAddress.toString('hex')];
  513.     if(channel.isOpen()){
  514.       throw new Error("Invalid Withdraw: Cannot issue withdraw on open channel");
  515.     }
  516.     var openLockProofs = channel.issueWithdrawPeerOpenLocks(this.currentBlock);
  517.     var withdraws = [];
  518.     for(var i=0; i< openLockProofs.length; i++){
  519.         var p = openLockProofs[i];
  520.         //nonce,gasPrice,nettingChannelAddress, encodedOpenLock, merkleProof,secret)
  521.         var _secret = p.openLock.secret;
  522.         var _channelAddress = channelAddress;
  523.         var self = this;
  524.         var promise = this.blockchain.withdrawLock(channelAddress,p.encodeLock(),p.merkleProof,_secret)
  525.         .then(function(vals){
  526.           // var secret = vals[0];
  527.           // var receiverAddress = vals[1];
  528.           //  //channelAddress, secret, receiverAddress,block
  529.           //  return self.onChannelSecretRevealed(_channelAddress,secret,receiverAddress)
  530.         })
  531.         .catch(function(err){              
  532.            return self.onChannelSecretRevealedError(_channelAddress,_secret);
  533.         })
  534.         withdraws.push(promise);
  535.     }
  536.     return Promise.all(withdraws);
  537.     
  538.   }
  540.   /** Settle the channel on-chain after settle_timeout time has passed since closing, unlocking the on-chain collateral and distributing the funds
  541.   * according to the proofs and lock withdrawals on chain. 
  542.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  543.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  544.   * the onChannelSettledError(channelAddress) is called
  545.   */
  546.   settleChannel(channelAddress){
  547.     if(!this.channels.hasOwnProperty(channelAddress)){
  548.       throw new Error("Invalid Settle: unknown channel");
  549.     }
  550.     var channel = this.channels[channelAddress.toString('hex')];
  551.     if(channel.isOpen()){
  552.       throw new Error("Invalid Settle: cannot issue settle on open channel");
  553.     }
  555.     var _channelAddress = channelAddress;
  556.     var self = this;
  557.     channel.issueSettle(this.currentBlock);
  558.     var _channelAddress = channelAddress;
  559.     return self.blockChain.settle(_channelAddress).then(function () {
  560.       //return self.onChannelSettled(_channelAddress);
  561.     }).catch(function(err){
  562.       return self.onChannelSettledError(_channelAddress);
  563.     });
  564.   }
  566.   /** Deposit an amount of the ERC20 token into the channel on-chain.  After the transaction is mined successfully,
  567.   * that amount will be available for net transfer in the channel. This is effectively the collateral locked up during the 
  568.   * channel lifetime and cannot be freed until the channel is closed and settled.
  569.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  570.   * @param {BN} amount - the amount of the ERC20 token to deposit.  The maxium amount of the cumulative deposits is determined by the allowance setup for the channel.
  571.   * @see Engine.approveChannel
  572.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  573.   * the onChannelNewBalanceError(channelAddress) is called
  574.   */
  575.   depositChannel(channelAddress,amount){
  576.     if(!this.channels.hasOwnProperty(channelAddress)){
  577.       throw new Error("Invalid Settle: unknown channel");
  578.     }
  579.     var channel = this.channels[channelAddress.toString('hex')];
  580.     if(!channel.isOpen()){
  581.       throw new Error("Invalid Deposite: cannot issue settle on open channel");
  582.     }
  583.     var _channelAddress = channelAddress;
  584.     var self = this;
  585.     return self.blockChain.depoist(_channelAddress,amount).then(function (vals) {
  586.       // event ChannelNewBalance(address token_address, address participant, uint balance);
  587.       // var tokenAddress = vals[0];
  588.       // var nodeAddress = vals[1];
  589.       // var balance = vals[2];
  590.       // return self.onChannelNewBalance(_channelAddress,nodeAddress,balance);
  591.     }).catch(function(err){
  592.       return self.onChannelNewBalanceError(_channelAddress);
  593.     });
  594.   }
  596.   /** approve the channel to take ERC20 deposits.  This must be called before a deposit can be made successfully.  This utlimately creates and allowance
  597.   * for the channel on the ERC20 contract.
  598.   * @param {Buffer} channelAddress - the on-chain nettingchannel address of the channel
  599.   * @param {BN} amount - the maximum amount of the ERC20 token to allow the channel to transfer when making a deposit.  
  600.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  601.   * the onApprovalError(channelAddress) is called
  602.   */
  603.   approveChannel(channelAddress,amount){
  604.     if(!this.channels.hasOwnProperty(channelAddress)){
  605.       throw new Error("Invalid approve Channel: unknown channel");
  606.     }
  607.     var channel = this.channels[channelAddress.toString('hex')];
  608.     var _channelAddress = channel.channelAddress;
  609.     return self.blockChain.approve(self.blockchain.tokenAddress,channel.channelAddress,amount)
  610.     .then(function (vals) {
  611.       //event Approval(address indexed _owner, address indexed _spender, uint256 _value);
  612.       // var owner = vals[0];
  613.       // var spender = vals[1];
  614.       // var value = vals[2];
  615.      
  616.       // return self.onApproval(owner,spender,value);
  617.     }).catch(function(err){
  618.       return self.onApprovalError(_channelAddress);
  619.     });
  620.   }
  622.   /** Approve the channelManager to take the flat fee in GOT ERC20 tokens when a channel is created.  This only needs to be called once when the engine is initialized
  623.   * @param {BN} amount - the maximum allowance of GOT ERC20 tokens to allow the channelManager to transfer.  
  624.   * @returns {Promise} - the promise is settled when the channel close request is mined.  If there is an error during any point of execution in the mining
  625.   * the onApprovalError() is called
  626.   */
  627.   approveChannelManager(amount){
  628.     return self.blockChain.approve(self.blockchain.gotokenAddress,
  629.       self.blockchain.chanelManagerAddress,
  630.       amount)
  631.     .then(function (vals) {
  632.       //event Approval(address indexed _owner, address indexed _spender, uint256 _value);
  633.       // var owner = vals[0]; 
  634.       // var spender = vals[1];
  635.       // var value = vals[2];
  636.       // return self.onApproval(owner,spender,value);
  637.     }).catch(function(err){
  638.       return self.onApprovalError();
  639.     });
  640.   }
  641.   
  642.   /** Callback when a ERC20 token approves someone for an allowance
  643.   * @param {String} owner - ethereum address hexString
  644.   * @param {String} spender - ethereum address hexString
  645.   * @param {BN} value - the allowance that was set
  646.   */
  647.   onApproval(owner,spender,value){
  648.     return true;
  649.   };
  651.   onApprovalError(address){
  652.     return true;
  653.   }
  655.   /** Callback when a new channel is created by the channel manager
  656.   * @param {String} channelAddress - ethereum address hexString
  657.   * @param {String} addressOne - ethereum address hexString
  658.   * @param {String} addressTwo - ethereum address hexString
  659.   * @param {BN} settleTimeout- the settle_timeout for the channel
  660.   */
  661.   onChannelNew(channelAddress,addressOne,addressTwo,settleTimeout){
  662.     var peerAddress = null;
  663.     if(addressOne.compare(this.address)===0){
  664.       peerAddress = addressTwo;
  665.     }else if(addressTwo.compare(this.address)===0){
  666.       peerAddress = addressOne;
  667.     }else{
  668.       //something very wrong
  669.       throw new Error("Invalid Channel Event:unknown new channel");
  670.     }
  672.     
  673.     var existingChannel = this.channelByPeer[peerAddress.toString('hex')];
  674.     if(existingChannel && existingChannel.state !== channelLib.CHANNEL_STATE_SETTLED){
  675.       throw new Error("Invalid Channel: cannot add new channel as it already exists");
  676.     }
  678.     var stateOne = new channelStateLib.ChannelState({
  679.       address:this.address
  680.     });
  682.     var stateTwo = new channelStateLib.ChannelState({
  683.         address:peerAddress
  684.     });
  685.     
  686.       //constructor(peerState,myState,channelAddress,settleTimeout,revealTimeout,currentBlock){
  687.     var channel = new channelLib.Channel(stateTwo,stateOne,channelAddress,
  688.        this.currentBlock);
  689.     this.channels[channel.channelAddress.toString('hex')] = channel;
  690.     this.channelByPeer[channel.peerState.address.toString('hex')] = channel;
  692.     if(this.pendingChannels.hasOwnProperty(peerAddress.toString('hex'))){
  693.       delete this.pendingChannels[peerAddress.toString('hex')] ;
  694.     }
  695.     return true;
  696.   }
  698.   onChannelNewError(peerAddress){
  699.     if(this.pendingChannels.hasOwnProperty(peerAddress.toString('hex'))){
  700.       delete this.pendingChannels[peerAddress.toString('hex')] ;
  701.     }
  702.     return;
  703.     //TODO: emit UnableToCreate Channel with Peer
  704.   }
  706.   /** Callback when a channel has tokens deposited into it on-chain
  707.   * @param {String} channelAddress - ethereum address hexString
  708.   * @param {String} address - the particpants ethereum address in hexString who deposited the funds
  709.   * @param {String} balance - the new deposited balance for the participant in the channel
  710.   */
  711.   onChannelNewBalance(channelAddress,address,balance){
  712.     this.channels[channelAddress.toString('hex')].onChannelNewBalance(address,balance);
  713.     return true;
  714.   }
  716.   onChannelNewBalanceError(){
  717.     return false;
  718.   }
  720.   /** Callback when a  channel is closed on chain identifying which of the partners initiated the close
  721.   * @param {String} channelAddress - ethereum address hexString
  722.   * @param {String} closingAddress - ethereum address hexString
  723.   */
  724.   onChannelClose(channelAddress,closingAddress){
  726.    var channel = this.channels[channelAddress.toString('hex')];
  727.    channel.onChannelClose(closingAddress, this.currentBlock)
  728.    if(closingAddress.compare(this.address) !==0){
  730.     return this.transferUpdate(channelAddress)
  731.    }
  732.    return true;
  733.   }
  735.   onChannelCloseError(channelAddress,proof){
  736.     var channel = this.channels[channelAddress.toString('hex')];
  737.     return channel.onChannelCloseError();
  738.   }
  740.   /** Callback when a the counterpary has updated their transfer proof on-chain
  741.   * @param {String} channelAddress - ethereum address hexString
  742.   * @param {String} nodeAddress - the party who submitted the proof
  743.   */
  744.   onTransferUpdated(channelAddress,nodeAddress){
  745.     return this.channels[channelAddress.toString('hex')].onTransferUpdated(nodeAddress,this.currentBlock);
  746.   }
  748.   onTransferUpdatedError(channelAddress){
  749.     return this.channels[channelAddress.toString('hex')].onTransferUpdatedError();
  750.   }
  752.   /** Callback when a channel is settled on-chain
  753.   * @param {String} channelAddress - ethereum address hexString
  754.   */
  755.   onChannelSettled(channelAddress){
  756.     return this.channels[channelAddress.toString('hex')].onChannelSettled(this.currentBlock);
  757.   }
  758.   onChannelSettledError(channelAddress){
  759.    return this.channels[channelAddress.toString('hex')].onChannelSettledError();;
  760.   }
  762.   /** Callback when a lock has been withdrawn on-chain.  If a user was withholding the secret in a mediate transfer,
  763.   * the party can now unlock the pending locks in the other channels.  This is why it is essential in a mediated transfer setting
  764.   * that each hop decrements the expiration by a safe margin such that they may claim a lock off chain in case of byzantine faults
  765.   * @param {String} channelAddress - ethereum address hexString
  766.   * @param {String} secret - the 32 byte secret in hexString
  767.   * @param {String} receiverAddress - ethereum address hexString which unlocked the lock on-chain
  768.   */
  769.   onChannelSecretRevealed(channelAddress, secret, receiverAddress){
  770.     return this.channels[channelAddress.toString('hex')].onChannelSecretRevealed(secret,receiverAddress,this.currentBlock);
  771.   };
  772.   onChannelSecretRevealedError(channelAddress, secret){
  773.     return this.channels[channelAddress.toString('hex')].onChannelSecretRevealedError(secret);
  774.   };
  776.   /** Callback when a channel has been closed and the channel lifetime exceeds the refund interval.
  777.   * i.e. channel.closedBlock - channel.openedBlock > refundInterval.  This is in hopes to incentives longer lived state channels
  778.   * by reducing the cost of their deployment for longer periods.
  779.   * @param {String} channelAddress - ethereum address hexString
  780.   * @param {String} receiverAddress - ethereum address hexString of the party that received the refund
  781.   * @param {BN} amount- the amount of GOT refunded
  782.   */
  783.   onRefund(channelAddress,receiverAddress,amount){
  784.     return true;
  785.   }
  786.   
  788. }
  790. module.exports = {
  791.   Engine
  792. }