@connext/vector-engine
v0.2.5-beta.21
Published
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
Downloads
436
Keywords
Readme
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 protocolmake 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 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.
Returns
Object
- FullChannelState object.
chan_resolveTransfer
Resolves an existing conditional transfer using logic that finalizes/unlocks it.
Params
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.
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.