celersdk

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2025 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

this file defines externalsigner interface for app to implement and provides common.signer to cnode, also adds new API for create sdk client

Index

Constants

View Source 
const (
	OPCODE_NEWSTATE = 1
	OPCODE_ACK      = 2
)
View Source 
const NUM_PLAYERS = 2
View Source 
const SignTimeout = 60 * time.Second

wait at most 60s for external to return sign result

Variables

View Source 
var (
	ErrMissingSigs         = errors.New("missing sigs from received ack msg")
	ErrDiffAckState        = errors.New("ack msg has different state")
	ErrWrongSeqNum         = errors.New("wrong seqnum")
	ErrDiffAppState        = errors.New("appstate is different")
	ErrWrongOpcode         = errors.New("unknown opcode")
	ErrWrongPlayers        = errors.New("players list is wrong")
	ErrWrongNonce          = errors.New("wrong nonce")
	ErrWrongOnChainTimeout = errors.New("wrong onchain timeout")
	ErrInvalidSession      = errors.New("invalid app session ")
)
View Source 
var (
	ErrNilExtSigner  = errors.New("external signer is nil")
	ErrResultTimeout = errors.New("timeout waiting for sign result")
	ErrInvalidReqID  = errors.New("invalid sign reqid")
	ErrNilResult     = errors.New("sign result is nil")
)

Functions

func GetCelerErrCode 

func GetCelerErrCode(e error) int

GetCelerErrCode is the helper util to return errcode if e is a celersdkintf.E other wise returns -1. meaning -1 is reserved and shouldn't be used by other systems

func GetPlayerIdxForMatch 

func GetPlayerIdxForMatch(matchid, myaddr, players string) int64

GetPlayerIdxForMatch returns a player idx (0 based) for myaddr. myaddr must be in players. players is ETH addresses seperated by comma, eg: ab...12,bc...23 it uses a fair algo for assigning myidx, based on a number generated from matchid players list is sorted first for consistency return -1 on err

func InitClient 

func InitClient(acnt *Account, cfg, dataPath string, cb ClientCallback)

InitClient creates a celer client cfg is the content of profile json file. dataPath is the dir that holds celer data.

func InitClientWithSigner 

func InitClientWithSigner(addr, cfg, dataPath string, cb ClientCallback, signcb ExternalSignerCallback)

InitClientWithSigner creates celer client with external signer addr is hex string of ETH address eg. 0x1234...

func PublishSignedResult 

func PublishSignedResult(reqid int, result []byte) error

SDK API for mobile to call to send back sign result if mobile has error, send nil result so signer will know sign failed

func SetLogCallback 

func SetLogCallback(cb LogCallback)

SetLogCallback set the self-defined writer in the log module. Once set, logs will be written to cb.Onlog() instead of os.Stderr

func Version 

func Version() string

Version returns CelerSDK version

Types

type Account 

type Account struct {
	Keystore string
	Password string
}

type AppBooleanOutcome 

type AppBooleanOutcome struct {
	Finalized bool
	Outcome   bool
}

AppBooleanOutcome has two fields Finalized: if the app is finalized Outcome: the boolean outcome with given query arg

type AppCallback 

type AppCallback interface {
	common.StateCallback
}

type AppData 

type AppData struct {
	Received []byte
	AckMsg   []byte
}

AppData has 2 fields, Received is to be passed to celerx AckMsg is to be sent via nakama with opcode OPCODE_ACK

type AppInfo 

type AppInfo struct {
	DeployedAddr   string
	ContractBin    string
	OnChainTimeout int64
	Callback       AppCallback
}

type AppSession 

type AppSession struct {
	ID string
	// TODO(mzhou): MyIdx should not be enforced
	MyIdx int64 // MyIdx in this appsession, eg. 0 if I'm black on gomoku
	// contains filtered or unexported fields
}

func (*AppSession) GetDeployedAddress 

func (s *AppSession) GetDeployedAddress() (string, error)

GetDeployedAddress get the depolyed address of the app returns error if the app is based on an undeployed virtual contract

func (*AppSession) HandleMatchData 

func (s *AppSession) HandleMatchData(opcode int, data []byte) (*AppData, error)

HandleMatchData process received matchdata via nakama opcode 1: new state with one sig opcode 2: ack msg with new sig appended data should be bytes of AppStateProof for opcode 2, *AppData is empty, just check error for opcode 1, if *AppData isn't nil, both fields should be set

func (*AppSession) OnChainApplyAction 

func (s *AppSession) OnChainApplyAction(action []byte) error

OnChainApplyAction applies an action on chain

func (*AppSession) OnChainFinalizeOnActionTimeout 

func (s *AppSession) OnChainFinalizeOnActionTimeout() error

OnChainFinalizeOnActionTimeout finalizes the app on action timeout

func (*AppSession) OnChainGetActionDeadline 

func (s *AppSession) OnChainGetActionDeadline() (int64, error)

OnChainGetActionDeadline gets the app onchain action deadline

func (*AppSession) OnChainGetBooleanOutcome 

func (s *AppSession) OnChainGetBooleanOutcome(query []byte) (*AppBooleanOutcome, error)

OnChainGetBooleanOutcome returns app boolean outcome

func (*AppSession) OnChainGetSeqNum 

func (s *AppSession) OnChainGetSeqNum() (int64, error)

OnChainGetSeqNum gets the app onchain sequence number

func (*AppSession) OnChainGetSettleFinalizedTime 

func (s *AppSession) OnChainGetSettleFinalizedTime() (int64, error)

OnChainGetSettleFinalizedTime gets the app onchain settle finalized time

func (*AppSession) OnChainGetState 

func (s *AppSession) OnChainGetState(key int64) ([]byte, error)

OnChainGetState gets the app onchain state associated with the given key

func (*AppSession) OnChainGetStatus 

func (s *AppSession) OnChainGetStatus() (int8, error)

OnChainGetStatus gets the app onchain status (0:IDLE, 1:SETTLE, 2:ACTION, 3:FINALIZED)

func (*AppSession) SettleByInvalidState 

func (s *AppSession) SettleByInvalidState(oracleProof []byte, cosignedStateProof []byte) error

SettleByInvalidState settle an app channel due to invalid state

func (*AppSession) SettleByInvalidTurn 

func (s *AppSession) SettleByInvalidTurn(oracleProof []byte, cosignedStateProof []byte) error

SettleByInvalidTurn settle an app channel due to invalid turn

func (*AppSession) SettleByMoveTimeout 

func (s *AppSession) SettleByMoveTimeout(oracleProof []byte) error

SettleByMoveTimeout settle an app channel due to movement timeout

func (*AppSession) SettleBySigTimeout 

func (s *AppSession) SettleBySigTimeout(oracleProof []byte) error

SettleBySigTimeout settle an app channel due to signature timeout

func (*AppSession) SignAppData 

func (s *AppSession) SignAppData(in []byte) ([]byte, error)

SignAppData takes app data, add proper metadata and return final bytes ready to be sent via nakama note this func will incr session seq number and set expect new state from peer to true

func (*AppSession) SwitchToOnchain 

func (s *AppSession) SwitchToOnchain(stateproof []byte) error

SwitchToOnchain submits offchain stateproof to onchain and starts onchain play

type Balance 

type Balance struct {
	Available    string
	Pending      string
	ReceivingCap string
}

offchain balance struct

type BooleanCondition 

type BooleanCondition struct {
	OnChainDeployed     bool
	OnChainAddress      string // onchain contract address if OnChainDeployed is true
	SessionID           string // offchain session hex string from NewAppSession
	ArgsForQueryOutcome []byte
	TimeoutBlockNum     int // timeout of one session. add current block num for pay deadline
}

type CSharedRandom 

type CSharedRandom struct {
	// contains filtered or unexported fields
}

func NewSharedRandom 

func NewSharedRandom(matchID string) *CSharedRandom

func (*CSharedRandom) GetSharedRandom 

func (sr *CSharedRandom) GetSharedRandom() float64

type CelerStatus 

type CelerStatus struct {
	JoinStatus  int32
	FreeBalance string
}

CelerStatus defines a struct to store the join status and free balance of a celer endpoint For field JoinStatus, it has three values which are 0, 1 and 2. 0 means address queried does not join Celer Network. 1 means this address has a channel with Osp responsing this query(Local). 2 means this address has a channel with another Osp in Celer Network(Remote). For field FreeBalance, it uses a decimal string to represent the receiving capacity of address queried. When receiving this status, developers should first check JoinStatus, if it is not 1(Local), you should just ignore FreeBalance. Only when JoinStatus is 1 could the developer further use FreeBalance.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Celer mobile client. must define before methods! gobind has a bug to clear method doc if struct is defined after methods

func (*Client) ConfirmOnChainResolvedPays 

func (mc *Client) ConfirmOnChainResolvedPays(tk *Token) error

ConfirmOnChainResolvedPays confirms pays that have been onchain resolved, if tk is nil, means ETH

func (*Client) ConfirmPay 

func (mc *Client) ConfirmPay(payID string) error

ConfirmPay settles the condpay, ie. actually paid to pay dest

func (*Client) ConfirmSettlePaymentChannel 

func (mc *Client) ConfirmSettlePaymentChannel(tokenInfo *TokenInfo) error

func (*Client) ConfirmWithdraw 

func (mc *Client) ConfirmWithdraw(tokenInfo *TokenInfo) error

func (*Client) CreateAppSessionOnDeployedContract 

func (mc *Client) CreateAppSessionOnDeployedContract(
	contractAddress string,
	nonce uint64,
	onChainTimeout uint64,
	participants string,
	callback AppCallback) (*AppSession, error)

func (*Client) CreateAppSessionOnVirtualContract 

func (mc *Client) CreateAppSessionOnVirtualContract(
	contractBin string,
	constructor string,
	nonce uint64,
	onChainTimeout uint64,
	callback AppCallback) (*AppSession, error)

func (*Client) DepositERC20 

func (mc *Client) DepositERC20(
	token *Token, amount string, callback DepositCallback) (string, error)

func (*Client) DepositETH 

func (mc *Client) DepositETH(amount string, callback DepositCallback) (string, error)

func (*Client) Destroy 

func (mc *Client) Destroy()

Destroy tries best to do clean up of current client note after this returns, all API calls to same client will crash. This is by design to catch invalid call flow. So caller should be careful about the lifecycle management. There is no need to call Destroy if client isn't init correctly

func (*Client) EndAppSession 

func (mc *Client) EndAppSession(sessionid string) error

func (*Client) GetAllPayments 

func (mc *Client) GetAllPayments() (*celersdkintf.PaymentList, error)

GetAllPayments returns all payments info. **CAUTION**: This function costs heavy lookup on several tables and joins information from those tables, please take performance into consideration before using this. PaymentList.PayList is list of all payments. But due to gomobile limitation (no return list). mobile app needs to do following payList = GetAllPayments() 

for i=0; i<payList.Length; i++ {
    pay = payList.Get(i)
}

func (*Client) GetBalance 

func (mc *Client) GetBalance() (*Balance, error)

Get celer offchain ETH balance

func (*Client) GetBalanceERC20 

func (mc *Client) GetBalanceERC20(tokenAddr string) (*Balance, error)

GetBalanceERC20 gets celer offchain tokenAddr balance

func (*Client) GetChannelState 

func (mc *Client) GetChannelState(tk *Token) string

GetChannelState returns a string for channel state for given token

func (*Client) GetCurrentBlockNumber 

func (mc *Client) GetCurrentBlockNumber() int64

func (*Client) GetDataDir 

func (mc *Client) GetDataDir() string

GetDataDir returns dataPath when InitClient, so cxc can share same folder

func (*Client) GetIncomingPaymentStatus 

func (mc *Client) GetIncomingPaymentStatus(payId string) int

Get incoming payment status code

func (*Client) GetOnChainPaymentInfo 

func (mc *Client) GetOnChainPaymentInfo(paymentID string) (*OnChainPaymentInfo, error)

func (*Client) GetOutgoingPaymentStatus 

func (mc *Client) GetOutgoingPaymentStatus(payId string) int

Get outgoing payment status code

func (*Client) GetPayHistoryIterator 

func (mc *Client) GetPayHistoryIterator() (*PayHistoryIterator, error)

GetPayHistoryIterator returns a celer crypto pay history iterator. Caller can call "NextPage" to get paginated pay history.

func (*Client) GetPayment 

func (mc *Client) GetPayment(paymentID string) (*celersdkintf.Payment, error)

GetPayment returns the related payment info of a specified payment ID

func (*Client) GetSettleFinalizedTimeForPaymentChannel 

func (mc *Client) GetSettleFinalizedTimeForPaymentChannel(tokenInfo *TokenInfo) (int64, error)

func (*Client) HasPendingOpenChanRequest 

func (mc *Client) HasPendingOpenChanRequest(tk *Token) bool

HasPendingOpenChanRequest is expected to be called when GetChannelState returns NOT_FOUND in this case, it's helpful to know whether client has a pending onchain open channel request so app can update UI and/or try open again. Note pending true is only possible for client iniated onchain openchannel, not TCB

Internally we save the blockNum when start openchan request, if current blockNum <= saved+OpenChannelTimeout we return true. The value is set to 0 in openchan callback so future calls will return false (assume real blkNum is much larger than OpenChannelTimeout)

func (*Client) InstantiateChannelForToken 

func (mc *Client) InstantiateChannelForToken(tk *Token, cb ClientCallback)

func (*Client) IntendSettlePaymentChannel 

func (mc *Client) IntendSettlePaymentChannel(tokenInfo *TokenInfo) error

func (*Client) IntendWithdraw 

func (mc *Client) IntendWithdraw(tokenInfo *TokenInfo, amount string) error

func (*Client) MonitorCooperativeWithdrawJob 

func (mc *Client) MonitorCooperativeWithdrawJob(
	withdrawHash string, callback CooperativeWithdrawCallback)

func (*Client) MonitorDepositJob 

func (mc *Client) MonitorDepositJob(jobID string, callback DepositCallback)

func (*Client) NewAppSessionOnDeployedContract 

func (mc *Client) NewAppSessionOnDeployedContract(capp *AppInfo, matchid string, players string) (*AppSession, error)

NewAppSession creates app session object for deployed contract deployedAddr is eth address bytes of deployed app contract matchid is the matchid string from nakama server players is players ETH addresses seperated by comma, eg: ab...12,bc...23 due to gobind type limitation. return AppSession and AppSession.ID can be used to end session

func (*Client) OpenETHChannel 

func (mc *Client) OpenETHChannel(dep *Deposit, cb ClientCallback)

func (*Client) OpenTokenChannel 

func (mc *Client) OpenTokenChannel(tk *Token, dep *Deposit, cb ClientCallback)

TODO(erctype): use proper enum based on tk.Erctype string

func (*Client) QueryReceivingCapacity 

func (mc *Client) QueryReceivingCapacity(addr string) (*CelerStatus, error)

QueryReceivingCapacity Check whether address has also joined Celer and returns its join status and free balance in a decimal string. It is useful for checking the state of the intended receiver. If the given address has not joined Celer, an empty string will be returned.

func (*Client) QueryReceivingCapacityOnToken 

func (mc *Client) QueryReceivingCapacityOnToken(tokenAddr string, addr string) (*CelerStatus, error)

QueryReceivingCapacityOnToken Check whether address has also joined Celer on tokenAddr and returns its join status and free balance in a decimal string. It is useful for checking the state of the intended receiver. If the given address has not joined Celer, an empty string will be returned.

func (*Client) RejectPay 

func (mc *Client) RejectPay(payID string) error

RejectPay cancels the pay, ie. ask OSP and pay src to not pay

func (*Client) RemoveCooperativeWithdrawJob 

func (mc *Client) RemoveCooperativeWithdrawJob(withdrawHash string)

func (*Client) RemoveDepositJob 

func (mc *Client) RemoveDepositJob(jobID string)

func (*Client) RemoveExpiredPays 

func (mc *Client) RemoveExpiredPays(tk *Token) error

RemoveExpiredPays clears pending pays that have expired, if tk is nil, means ETH

func (*Client) ResolveIncomingPaymentOnChain 

func (mc *Client) ResolveIncomingPaymentOnChain(payId string) error

func (*Client) ResolvePayOnChain 

func (mc *Client) ResolvePayOnChain(payID string) error

ResolvePayOnChain settles the payment onchain and receives the payment from OSP

func (*Client) SendConditionalPayment 

func (mc *Client) SendConditionalPayment(
	tokenInfo *TokenInfo,
	destination string,
	amount string,
	transferLogicType TransferLogicType,
	conditions []*Condition,
	timeout int64,
	note *any.Any) (string, error)

func (*Client) SendETH 

func (mc *Client) SendETH(receiver string, amtWei string, noteTypeUrl string, noteValueByte []byte) (string, error)

noteTypeUrl should be type url of any.Any. noteStr should be string representation of []byte in note (any.Any)

func (*Client) SendETHWithCondition 

func (mc *Client) SendETHWithCondition(receiver string, amtWei string, cond *BooleanCondition) (string, error)

func (*Client) SendToken 

func (mc *Client) SendToken(tk *Token, receiver string, amtWei string, noteTypeUrl string, noteValueByte []byte) (string, error)

SendETH sends ERC20/ETH token to receiver. Caller can optionally add a note in the pay.

func (*Client) SendTokenWithCondition 

func (mc *Client) SendTokenWithCondition(tk *Token, receiver string, amtWei string, cond *BooleanCondition) (string, error)

When should we call onSent? or do we need a new callback func?

func (*Client) SetDelegation 

func (mc *Client) SetDelegation(tks []*Token, duration int64) error

func (*Client) SetMsgDropper 

func (mc *Client) SetMsgDropper(dropRecv, dropSend bool)

SetMsgDropper will drop grpc msgs, used for testing only

func (*Client) SettleExpiredPayments 

func (mc *Client) SettleExpiredPayments(tokenInfo *TokenInfo) error

func (*Client) SettleOnChainResolvedIncomingPayment 

func (mc *Client) SettleOnChainResolvedIncomingPayment(payId string) error

func (*Client) SignData 

func (mc *Client) SignData(data []byte) ([]byte, error)

SignData signs arbitrary data and returns the signature

func (*Client) SyncOnChainChannelStates 

func (mc *Client) SyncOnChainChannelStates(tk *Token) error

func (*Client) TcbOpenETHChannel 

func (mc *Client) TcbOpenETHChannel(peerAmtWei string, cb ClientCallback)

func (*Client) TcbOpenTokenChannel 

func (mc *Client) TcbOpenTokenChannel(tk *Token, peerAmtWei string, cb ClientCallback)

func (*Client) WithdrawERC20 

func (mc *Client) WithdrawERC20(
	token *Token, amount string, callback CooperativeWithdrawCallback) (string, error)

func (*Client) WithdrawETH 

func (mc *Client) WithdrawETH(amount string, callback CooperativeWithdrawCallback) (string, error)

type ClientCallback 

type ClientCallback interface {
	HandleClientReady(c *Client)
	HandleClientInitErr(e *celersdkintf.E)
	HandleChannelOpened(token, cid string)
	HandleOpenChannelError(token, reason string)
	// Callback triggered when secret revealed.
	HandleRecvStart(pay *celersdkintf.Payment)
	// Callback triggered when pay settle request processed.
	HandleRecvDone(pay *celersdkintf.Payment)
	HandleSendComplete(pay *celersdkintf.Payment)
	HandleSendErr(pay *celersdkintf.Payment, e *celersdkintf.E)
}

type Condition 

type Condition struct {
	// Whether the condition is based on an on-chain deployed contract
	OnChainDeployed bool
	// On-chain contract address bytes if OnChainDeployed is true, or virtual contract address
	ContractAddress []byte
	// Args to isFinalized()
	IsFinalizedArgs []byte
	// Args to getOutcome()
	GetOutcomeArgs []byte
}

type CooperativeWithdrawCallback 

type CooperativeWithdrawCallback interface {
	OnWithdraw(withdrawHash string, txHash string)
	OnError(withdrawHash string, err string)
}

type Deposit 

type Deposit struct {
	Myamtwei   string
	Peeramtwei string
}

type DepositCallback 

type DepositCallback interface {
	OnDeposit(jobID string, txHash string)
	OnError(jobID string, err string)
}

type ExternalSignerCallback 

type ExternalSignerCallback interface {
	OnSignMessage(reqid int, msg []byte)
	// OnSignTransaction rawtx is RLP encoded bytes of Eth transaction
	OnSignTransaction(reqid int, rawtx []byte)
}

mobile needs to implement this as callback, corresponding cb will be called when need to sign stuff

type LogCallback 

type LogCallback interface {
	// msg is the log output
	OnLog(msg string)
}

type OnChainPaymentInfo 

type OnChainPaymentInfo struct {
	Amount          string
	ResolveDeadline uint64
}

type OnchainCallback 

type OnchainCallback interface {
	OnSubmitted(uid string)
	OnMined(tx string)
	OnErr(e *celersdkintf.E)
}

type PayHistoryIterator 

type PayHistoryIterator struct {
	// contains filtered or unexported fields
}

PayHistoryIterator is an iterator to get pay history.

func (*PayHistoryIterator) HasMoreResult 

func (iter *PayHistoryIterator) HasMoreResult() bool

HasMoreResult returns false if the iterator has gone over all pays in history.

func (*PayHistoryIterator) NextPage 

func (iter *PayHistoryIterator) NextPage(itemsPerPage int32) (string, error)

NextPage returns next (earlier) batch of pay history in JSON string and error. itemsPerPage specifies the max number of pays in the response. History entries returned in json encoding string and reverse-chronological order. If there is more to retrieve, hasMoreResult filed in iterator is set to true . Note that hasMoreResult could be true when #(entries left for retrival before calling the func) happens to be same as itemsPerPage. In this case, the next time calling NextPage will return empty history set and set hasMoreResult field in iterator to false.

type Token 

type Token struct {
	Erctype string // ERC20, ERC721 etc.
	Addr    string // token contract addr
	Symbol  string // short name like gt, celr
}

type TokenInfo 

type TokenInfo struct {
	TokenType    TokenType
	TokenAddress string
}

type TokenType 

type TokenType int32

type TransferLogicType 

type TransferLogicType int32

type UserInfo 

type UserInfo struct {
	WalletAddr string
	EmailAddr  string
	Name       string
}

UserInfo defines user info to send fiat-related request

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.