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
In ~/vector
(root), run:
make engine
to build the protocolmake test-engine
to run the unit tests
Methods:
- chan_setup
- chan_deposit
- chan_createTransfer
- chan_resolveTransfer
- chan_withdraw
- chan_getChannelState
- chan_getTransferStateByRoutingId
- chan_getChannelStateByParticipants
- chan_getChannelStates
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": [
{
...
},
...
]
}
Creates a channel with a given counterparty.
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
Object
- FullChannelState object.
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.
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).
Object
- FullChannelState object.
Creates a conditional transfer with the specified counterparty.
Object
- EngineParams.ConditionalTransfer objectchannelAddress
: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 identifierdetails
: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_TIMEOUTmeta
:Object
(optional) User defined object that can contain transfer metadata, invoice number, message, etc.
Object
- FullChannelState object.
Resolves an existing conditional transfer using logic that finalizes/unlocks it.
Object
- EngineParams.ResolveTransfer objectchannelAddress
: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.
Object
- FullChannelState object.
Withdraws funds from the channel to a specified address onchain. Note that the withdraw onchain tx itself may be submitted by the counterparty.
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.
Object
- FullChannelState object.- // TODO do we need to add txHash here?
Gets channel state for a given channelAddress
.
Object
- EngineParams.GetChannelState object.channelAddress
:String
- Address of channel.
Object
- FullChannelState object.
Gets a transfer state for a given routingId
. This method is largely only used by the router.
Object
- EngineParams.GetTransferStateByRoutingId object.routingId
:String
- Unique Id of transfer routed over multiple channels.
Object
- FullTransferState object.
Gets channel state for a given alice
and bob
public identifiers.
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.
Object
- FullChannelState object.
Gets all channel states associated with your public identifier in your store.
None.
Object[]
- Array of FullChannelState objects.