Vector Engine
The engine wraps the core Vector protocol. It implements business logic for some default types of conditional transfers, converts user-facing parameters/events to protocol parameters/events, and exposes a JSON RPC interface that is consumed by the server-node
, browser-node
or any other node implementation.
Note: because the engine runs behind a JSON RPC interface, it is entirely possible to run the core protocol (incl keys, access to services, etc.) in an isolated environment such as a browser iframe, and then only expose limited functionality for interacting with a user's channel to the outside world. We believe this is the safest way to enable state channel applications that run in the browser.
Contents:
- Developing and Running Tests
- JSON RPC Interface
- Events // TODO
Developing and Running Tests
In ~/vector
(root), run:
-
make engine
to build the protocol -
make test-engine
to run the unit tests
JSON RPC Interface
Methods:
- chan_setup
- chan_deposit
- chan_createTransfer
- chan_resolveTransfer
- chan_withdraw
- chan_getChannelState
- chan_getTransferStateByRoutingId
- chan_getChannelStateByParticipants
- chan_getChannelStates
Example Usage
Request
curl --data '{"method":"chan_setup","params":[...],"id":1,"jsonrpc":"2.0"}' -H "Content-Type: application/json" -X POST localhost:8545
Note: remember to populate params
and method
with the correct fields above.
Response
{
"id": 1,
"jsonrpc": "2.0",
"result": [
{
...
},
...
]
}
chan_setup
Creates a channel with a given counterparty.
Params
-
Object
- EngineParams.Setup object.-
counterpartyIdentifier
:String
- Connext-specific counterparty public identifier. -
chainId
:Number
- ChainId of the chain that you want to create a channel on. -
timeout
:String
- (optional) Dispute timeout for the channel. // TODO must be greater than MIN_TIMEOUT and lower than 2*DEFAULT_TIMEOUT
-
Returns
-
Object
- FullChannelState object.
chan_deposit
Reconciles a deposit that was completed onchain with the offchain channel balance.
NOTE: this method assumes you have first completed the deposit onchain either by sending a tx to contract.depositA
if you are Alice in the channel or sending funds directly to the address if you are Bob. See the note on Depositing and Withdrawing to learn more.
Params
-
Object
- EngineParams.Deposit object.-
channelAddress
:String
- Onchain address of the specific channel that you have deposited to. -
assetId
:String
- Address of the asset (ERC20 token or equivalent) that you deposited. Useethers.constants.AddressZero
(i.e.address(0)
) for the chain's base asset (e.g. Eth).
-
Returns
-
Object
- FullChannelState object.
chan_createTransfer
Creates a conditional transfer with the specified counterparty.
Params
-
Object
- EngineParams.ConditionalTransfer object-
channelAddress
:String
- Address of channel from which the transfer will be made. -
conditionType
:String
- Type of condition which will be used to resolve the transfer. See TransferName, -
amount
:String
- Amount to be locked in the transfer by sender. -
assetId
:String
- Onchain address of asset (ERC20 or equivalent). Useethers.constants.AddressZero
for the chain's base asset (e.g. Eth). -
recipient
:String
- Recipient Connext-specific public identifier -
details
:Object
- TransferType-specific params needed to set up the conditions for the transfer. For instance,lockHash
forHashlockTransfer
. See the schemas to learn more. -
recipientChainId
:Number
- (optional) ChainId of recipient for cross-chain transfers. If none is provided, the engine will assume that the recipient chainId is the same as sender chainId. -
recipientAssetId
:String
- (optional) AssetId of recipient for transfers that include an in-flight swap of assets. If nothing is provided, the engine will assume that the recipient assetId is the same as sender assetId. -
timeout
:String
(optional) Dispute timeout of transfer. Defaults to DEFAULT_TIMEOUT -
meta
:Object
(optional) User defined object that can contain transfer metadata, invoice number, message, etc.
-
Returns
-
Object
- FullChannelState object.
chan_resolveTransfer
Resolves an existing conditional transfer using logic that finalizes/unlocks it.
Params
-
Object
- EngineParams.ResolveTransfer object-
channelAddress
:String
- Address of channel which contains the transfer to be resolved. -
transferId
:String
- Unique Id associated with this transfer. Can get this by listening for theCONDITIONAL_TRANSFER_CREATED
event. -
conditionType
:String
- Condition type of this transfer // TODO do we need this? -
details
:Object
- TransferType-specific params needed to resolve the conditions for the transfer. For instance,preImage
forHashlockTransfer
. See the schema to learn more.
-
Returns
-
Object
- FullChannelState object.
chan_withdraw
Withdraws funds from the channel to a specified address onchain. Note that the withdraw onchain tx itself may be submitted by the counterparty.
Params
-
Object
- EngineParams.Withdraw object.-
channelAddress
:String
- Address of channel from which the withdraw will be made. -
amount
:String
- Amount to be withdrawn // TODO what units is this in? -
assetId
:String
- Onchain address of asset (ERC20 or equivalent). Useethers.constants.AddressZero
for the chain's base asset (e.g. Eth). -
recipient
:String
- Onchain address to send funds to. -
fee
:String
- (optional) Fee charged by counterparty to submit a withdrawal on your behalf to chain. If the counterparty is submitting your withdrawal and doesn't charge a fee, this is not needed. If they are submitting your withdrawal and do charge a fee, adding an incorrect fee will cause the withdraw call to throw an error.
-
Returns
-
Object
- FullChannelState object. - // TODO do we need to add txHash here?
chan_getChannelState
Gets channel state for a given channelAddress
.
Params
-
Object
- EngineParams.GetChannelState object.-
channelAddress
:String
- Address of channel.
-
Returns
-
Object
- FullChannelState object.
chan_getTransferStateByRoutingId
Gets a transfer state for a given routingId
. This method is largely only used by the router.
Params
-
Object
- EngineParams.GetTransferStateByRoutingId object.-
routingId
:String
- Unique Id of transfer routed over multiple channels.
-
Returns
-
Object
- FullTransferState object.
chan_getChannelStateByParticipants
Gets channel state for a given alice
and bob
public identifiers.
Params
-
Object
- EngineParams.GetChannelStateByParticipants object.-
alice
:String
- Connext-specific public identifier of the channel initiator. -
bob
:String
- Connext-specific public identifier of the channel responder. -
chainId
:Number
- Id of the chain that the channel is on.
-
Returns
-
Object
- FullChannelState object.
chan_getChannelStates
Gets all channel states associated with your public identifier in your store.
Params
None.
Result
-
Object[]
- Array of FullChannelState objects.