@connext/cf-core¶
Exported Classes:
Classes¶
CFCore¶
The Counterfactual protocol runner.
class CFCore {
static create(
messagingService: IMessagingService,
storeService: IStoreService,
networkContext: NetworkContext,
nodeConfig: NodeConfig,
provider: JsonRpcProvider,
signer: IChannelSigner,
lockService?: ILockService,
blocksNeededForConfirmation?: number,
logger?: ILoggerService,
): Promise<CFCore>;
}
Constructor Params¶
CFCore doesn’t have a traditional constructor because some required setup steps are asynchronous. Instead, all instances are created via the static method create
. This method takes the parameters:
messagingService
:IMessagingService
storeService
:IStoreService
networkContext
:NetworkContext
nodeConfig
:NodeConfig
: Basically just the store prefix which idk if this is even needed any more.provider
:JsonRpcProvider
signer
:IChannelSigner
lockService
?:ILockService
blocksNeededForConfirmation
?:number
: This should probably just be hard coded.logger
?:ILoggerService
Properties¶
rpcRouter
!:RpcRouter
networkContext
:NetworkContext
blocksNeededForConfirmation
:number
log
:ILoggerService
signerAddress
:string
publicIdentifie
:string
Methods¶
injectMiddleware(opcode: Opcode, middleware: ValidationMiddleware): void
on(event: EventNames | MethodName, callback: (res: any) => void)
off(event: EventNames | MethodName, callback?: (res: any) => void)
once(event: EventNames | MethodName, callback: (res: any) => void)
emit(event: EventNames | MethodName, req: MethodRequest)
async call(method: MethodName, req: MethodRequest): Promise<MethodResponse>
Legacy Docs: Probably out of date
Message Format¶
A “message” is a return value of an RPC call or the value passed to an event listener. Messages have the following fields:
type: string
Name of the Method or Event that this message represents e.g. “getAppInstances”, “install”
requestId?: string
Unique ID for a Method request.
Only required for Methods. Leave empty for Events.
data: { [key: string]: any }
Data payload for this message.
See “Result” section of a Method and “Data” section of an Event for details.
Public RPC Methods¶
Method: getAppInstances
¶
Returns all app instances currently installed on the Node.
NOTE: This is terrible from a security perspective. In the future this method will be changed or deprecated to fix the security flaw.
Params: None
Result:
appInstances:
AppInstanceInfo
[]
All the app instances installed on the Node
Method: proposeInstall
¶
Requests that a peer start the install protocol for an app instance. At the same time, authorize the installation of that app instance, and generate and return a fresh ID for it. If the peer accepts and the install protocol completes, its ID should be the generated appIdentityHash.
Params:
proposedToIdentifier: string
Public identifier of the peer responding to the installation request of the app
appDefinition: string
On-chain address of App Definition contract
abiEncodings:
AppABIEncodings
ABI encodings used for states and actions of this app
initiatorDeposit: BigNumber
Amount of the asset deposited by this user
initiatorDepositTokenAddress?: string
An optional string indicating whether an ERC20 token should be used for funding the proposer’s side of the app. If not specified, this defaults to ETH.
responderDeposit: BigNumber
Amount of the asset deposited by the counterparty
responderDepositTokenAddress?: string
An optional string indicating whether an ERC20 token should be used for funding the peer’s side of the app. If not specified, this defaults to ETH.
timeout: BigNumber
Number of blocks until a submitted state for this app is considered finalized
initialState:
AppState
Initial state of app instance
Result:
appIdentityHash: string
Generated appIdentityHash
Errors: (TODO)
Not enough funds
Method: rejectInstall
¶
Reject an app instance installation.
Params:
appIdentityHash: string
ID of the app instance to reject
Result: “OK”
Errors: (TODO)
Proposed app instance doesn’t exist
Method: install
¶
Install an app instance.
Params:
appIdentityHash: string
ID of the app instance to install
Counterparty must have called
proposedInstall
and generated this ID
Result:
appInstance:
AppInstanceInfo
Successfully installed app instance
Errors: (TODO)
Counterparty rejected installation
Method: getState
¶
Get the latest state of an app instance.
Params:
appIdentityHash: string
ID of the app instance to get state of
Result:
state:
AppState
Latest state of the app instance
Errors: (TODO)
App not installed
Method: getAppInstanceDetails
¶
Get details of an app instance.
Params:
appIdentityHash: string
ID of the app instance to get details of
Result:
appInstance:
AppInstanceInfo
App instance details
Method: getProposedAppInstance
¶
Get details of a proposed app instance.
Params:
appIdentityHash: string
ID of the app instance to get details of
Result:
appInstance:
AppInstanceInfo
App instance details
Method: takeAction
¶
Take action on current app state to advance it to a new state.
Params:
appIdentityHash: string
ID of the app instance for which to take action
action:
SolidityValueType
Action to take on the current state
Result:
newState:
AppState
New app state
Errors: (TODO)
Illegal action
Method: uninstall
¶
Uninstall an app instance, paying out users according to the latest signed state.
Params:
appIdentityHash: string
ID of the app instance to uninstall
Result: “OK”
Errors: (TODO)
App state not terminal
Method: proposeState
¶
TODO
Method: acceptState
¶
TODO
Method: rejectState
¶
TODO
Method: createChannel
¶
Creates a channel and returns the determined address of the multisig (does not deploy).
Params:
owners: string[]
the addresses who should be the owners of the multisig
Result:
CreateChannelTransactionResult
multisigAddress: string
the address which will hold the state deposits
Method: deployStateDepositHolder
¶
Deploys a multisignature wallet contract for use by the channel participants. Required step before withdrawal.
Params:
multisigAddress: string
address of the multisignature wallet
retryCount?: number
the number of times to retry deploying the multisig using an expontential backoff period between each successive retry, starting with 1 second. This defaults to 3 if no retry count is provided.
Result:
DeployStateDepositHolderResult
transactionHash: string
the hash of the multisig deployment transaction
This can be used to either register a listener for when the transaction has been mined or await the mining.
Method: getChannelAddresses
¶
Gets the (multisig) addresses of all the channels that are open on the Node.
Result:
addresses: string[]
the list of multisig addresses representing the open channels on the Node.
Method: deposit
¶
If a token address is specified, deposits the specified amount of said token into the channel. Otherwise it defaults to ETH (denominated in Wei).
Params:
multisigAddress: string
amount: BigNumber
tokenAddress?: string
Result:
multisigBalance: BigNumber
the updated balance of the multisig
Error:
“Insufficient funds”
Method: getStateDepositHolderAddress
¶
Retrieves the address for the state deposit used by the specified owners.
Params:
owners: string[]
the addresses who own the state deposit holder
Result:
multisigAddress: string
the address of the multisig (i.e. the state deposit holder)
Method: withdraw
¶
If a token address is specified, withdraws the specified amount of said token from the channel. Otherwise it defaults to ETH (denominated in Wei). The address that the withdrawal is made to is either specified by the recipient
parameter, or if none is specified defaults to ethers.utils.computeAddress(ethers.utils.HDNode.fromExtendedKey(nodePublicIdentifier).derivePath("0").publicKey)
. deployStateDepositHolder
must be called before this method can be used to withdraw funds.
Params:
multisigAddress: string
amount: BigNumber
recipient?: string
tokenAddress?: string
Result:
recipient: string
The address to whom the withdrawal is made
txHash: string
The hash of the transaction in which the funds are transferred from the state deposit holder to the recipient
Error(s):
“Insufficient funds”
“Withdraw Failed”
Method: withdrawCommitment
¶
This behaves similarly to the withdraw
call, except it produces a commitment for the withdrawal and returns the commitment instead of sending the commitment to the network.
Params:
multisigAddress: string
amount: BigNumber
recipient?: string
tokenAddress?: string
Result:
transaction: { to: string; value: BigNumberish; data: string; }
Error(s):
“Insufficient funds”
Method: getFreeBalance
¶
Gets the free balance AppInstance of the specified channel for the specified token. Defaults to ETH if no token is specified.
Params:
multisigAddress: string
tokenAddress?: string
Result:
{
[s: string]: BigNumber;
};
Returns a mapping from address to balance in wei. The address of a node with public identifier publicIdentifier
is defined as fromExtendedKey(publicIdentifier).derivePath("0").address
.
Note: calling this with a specific token address will return Zero even if the channel has never had any deposits/withdrawals of that token.
Method: getTokenIndexedFreeBalanceStates
¶
Gets the free balances for the ETH and ERC20 assets that have been deposited, indexed by token address.
Params:
multisigAddress: string
Result:
{
[tokenAddress: string]: {
[beneficiary: string]: BigNumber;
}
};
Returns a doubly-nested mapping. The outer mapping is the address of the token for which there is free balance in the channel. The inner mapping is a mapping from address to balance in wei. The address of a node with public identifier publicIdentifier
is defined as fromExtendedKey(publicIdentifier).derivePath("0").address
.
Events¶
Event: depositEvent
¶
Fired if a deposit has been made by a counter party.
Data:
multisigAddress: string
The address of the channel that the deposit was made into.
amount: BigNumber
The amount that was deposited by the counter party.
Event: installEvent
¶
Fired if new app instance was successfully installed.
Data:
appInstance:
AppInstanceInfo
Newly installed app instance
Event: rejectInstallEvent
¶
Fired if installation of a new app instance was rejected.
Data:
appInstance:
AppInstanceInfo
Rejected app instance
Event: updateStateEvent
¶
Fired if app state is successfully updated.
Data:
appIdentityHash: string
ID of app instance whose app state was updated
newState:
AppState
action?:
SolidityValueType
Optional action that was taken to advance from the old state to the new state
Event: uninstallEvent
¶
Fired if app instance is successfully uninstalled
Data:
appInstance:
AppInstanceInfo
Uninstalled app instance
Event: proposeStateEvent
¶
TODO
Event: rejectStateEvent
¶
TODO
Event: createChannelEvent
¶
Fired when a Node receives a message about a recently-created channel whose multisignature wallet’s list of owners includes this (i.e. the receiving) Node’s address.
Note: On the Node calling the creation of the channel, this event must have a registered callback to receive the multisig address before the channel creation call is made to prevent race conditions.
Data:
CreateChannelResult
counterpartyXpub: string
Xpub of the counterparty that the channel was opened with
multisigAddress: string
The address of the multisig that was created
owners: string[]
The list of multisig owners of the created channel
Data Types¶
Data Type: AppInstanceInfo
¶
An instance of an installed app.
id: string
Opaque identifier used to refer to this app instance
No two distinct app instances (even in different channels) may share the same ID
appDefinition: string
On-chain address of App Definition contract
abiEncodings:
AppABIEncodings
ABI encodings used for states and actions of this app
initiatorDeposit: BigNumber
Amount of the asset deposited by this user
responderDeposit: BigNumber
Amount of the asset deposited by the counterparty
timeout: BigNumber
Number of blocks until a submitted state for this app is considered finalized
Data Type: AppABIEncodings
¶
stateEncoding: string
ABI encoding of the app state
For example, for the Tic Tac Toe App (https://github.com/counterfactual/monorepo/blob/master/packages/apps/contracts/TicTacToeApp.sol), the state encoding string is
"tuple(uint256 versionNumber, uint256 winner, uint256[3][3] board)"
.
actionEncoding?: string
Optional ABI encoding of the app action
If left blank, instances of the app will only be able to update state using
proposeState
If supplied, instances of this app will also be able to update state using
takeAction
Again, for the Tic Tac Toe App, the action encoding string is
"tuple(uint8 actionType, uint256 playX, uint256 playY, tuple(uint8 winClaimType, uint256 idx) winClaim)"
.
Data Type: AppState
¶
Plain Old Javascript Object representation of the state of an app instance.
ABI encoded/decoded using the
stateEncoding
field on the instance’sAppABIEncodings
.
Data Type: SolidityValueType
¶
Plain Old Javascript Object representation of the action of an app instance.
ABI encoded/decoded using the
actionEncoding
field on the instance’sAppABIEncodings
.