Locus JSON-RPC

JSON RPC가 무엇일까요?

JSON-RPC는 클라이언트가 JSON 형식의 요청 메시지를 노드에 전송하여 노드는 이를 처리하고 결과를 JSON 형식의 응답 메시지로 반환합니다.

원격 프로시저 호출(Remote Procedure Call) 프로토콜의 약자로써, 통신을 위한 방식입니다.

로커스체인 RPC

Locus Chain 노드는 JSON-RPC API를 제공합니다. 개인이 실행하거나 몇몇의 공적인 서비스로 제공되는 노드를 통해 사용자는 쉽게 블록체인 네트워크의 정보를 조회할 수 있습니다.

호출

단순 조회용 RPC 호출

한 번의 호출로 결과를 받을 수 있습니다.

Tx를 생성하는 RPC 호출

파라메트에 'Sig'가 포함되어 있으면 Tx를 생성하는 RPC입니다. 동일한 RPC를 두 번 호출합니다.
아래와 같이 4단계로 진행하십시오.

[STEP1: 첫번째 호출] 노드에서 Tx와 Hash를 받습니다.
[STEP2: Tx 검증] 받은 Tx를 로커스 라이브러리의 VerifyTx 함수로 검증합니다.
[STEP3: 서명] Tx에 이상이 없으면 로커스 라이브러리나 지갑을 통해 서명을 합니다.
[STEP4: 두 번째 호출] 첫번째 호출 파라메트에 서명을 추가하여 두번째 호출을 하면 Tx가 생성됩니다.

RPC 호출 예시

{
  "jsonrpc": "2.0",
  "method": "locus_getAccountDetail",
  "params": [{ "account": "D4YLP5B3NC3RWVXYDWFPCT6IG2ASCVP32ANLOAD73I" }],
  "id": 1
}

공통 응답 형식

기본적인 응답값은 다음과 같은 형식을 가집니다.
호출된 Function에 따라 result 값이 변경됩니다.

성공

{
  "jsonrpc": "2.0",
  "id": 1, // int
  "result": {} // any
}

실패

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 1, // int
    "message": "" // string
  }
}

함수 목록

locus_echo

RPC 호출에 대해 노드가 응답을 잘 하는지 확인하는 용도로 사용할 수 있습니다.
입력값에 현재 시간을 추가하여 응답합니다.

Request

Key	Type	Description
-	string	문자열

Response

Key	Type	Description
-	string	입력 문자열 + 현재 시간

locus_getSyncState

노드의 현재 동기화 상태를 구합니다.

Request

[없음]

Response

Key	Type	Description
SyncState	string	NODE_STATE_IN_INIT NODE_STATE_IN_SYNC NODE_STATE_IN_RESYNC NODE_STATE_SYNC_COMPLETE NODE_STATE_STABLE Unknown NodeState

locus_getGenesisAccount

제네시스 계정의 주소를 구합니다.

Request

[없음]

Response

Key	Type	Description
Genesis	base32	제네시스 계정의 주소

locus_openAccount

계정을 로커스체인 네트워크에 등록합니다.

Request

Key	Type	Description
Account	base32	대상 계정 주소
Sender	base32	코인을 보낸 계정
Index	int	코인을 보낸 Tx의 height
Pk	base32	Normal public key
KeySign	base32	Master public key
Sig	base64	서명

Response

Key	Type	Description
Hash	base64	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_becomeHost

지정한 계정을 해당 노드의 호스트로 설정합니다. 지정한 계정은 게스트가 없어야 하고, 해당 노드는 호스트가 없는 빈 노드여야 합니다.

Request

Key	Type	Description
Account	base32	호스트가 될 계정
Sig	base64	서명

Response

Key	Type	Description
Hash	base64	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_becomeGuest

지정한 계정을 해당 노드의 게스트로 설정합니다. 지정한 계정은 게스트가 없어야 하고, 해당 노드는 호스트가 존재해야 합니다.

Request

Key	Type	Description
Account	base32	게스트가 될 계정
Sig	base64	서명

Response

Key	Type	Description
Hash	base64	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_changeKey

계정의 노말키를 변경합니다.

Request

Key	Type	Description
Account	base32	키를 변경할 계정
MasterPkey	base32	Master public key
NewNormalPkey	base32	New Normal public key
SignByMasterKey	base64	New Normal public key를 Master public key로 서명한 값
Sig	base64	서명

Response

Key	Type	Description
Hash	base64	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_transferCoin

코인을 다른 계정에 보냅니다.

Request

Key	Type	Description
From	base32	보내는 계정
To	base32	받는 계정
Amount	string	보낼 수량
Sig	base64	서명

Response

Key	Type	Description
Hash	base64	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_getTx

계정의 특정 Height의 Tx 정보를 구합니다.

Request

Key	Type	Description
Account	base32	계정
Height	int	계정의 Height

Response

Key	Type	Description
Tx	string	Tx 정보

locus_getAccountsHeights

계정들의 Height 목록을 구합니다.

Request

Key	Type	Description
Accounts	[]base32	Height를 구하고자 하는 계정 목록

Response

Key	Type	Description
Heights	[]string	Height 값은 파라메트의 계정 순서와 동일

locus_getAccountHistory

계정의 Tx 목록을 구합니다.

Request

Key	Type	Description
Account	base32	계정
Height	int	구하고자 하는 시작 Height Height가 -1이면, 최상위 Tx 부터.
Count	int	구하고자 하는 Tx 갯수 (시작 위치에서 이전 몇개)

Response

Key	Type	Description
Txs	[]string	Tx string list

locus_getAccountDetail

계정의 상세정보를 구합니다.

Request

Key	Type	Description
Account	base32	계정

Response

Key	Type	Description
Identity	string	Host : 해당 노드의 호스트 계정 Guest : 해당 노드의 게스트 계정 Neighbor : 해당 노드가 속한 샤드의 이웃 계정. 질의 당시의 상태이며, 동기 상태에 따라서 부정확한 값일 수도 있다. no identity : 위의 것에 아무 것도 해당되지 않음, 즉 존재하지 않거나, 다른 샤드에 속했거나
FromNoAlive	bool	OpenAccount 를 했지만, 아직 합의에 포함되지 않은 경우에 이 flag 가 true 가 된다.
Balance	string	보유한 로커스 코인
UnactBalance	string	아직은 Activate 되지 않아 사용할 수 없는 Balance
Representative	base32	위임한 계정 (Host 계정)
Grant	uint64	보유한 Grant
PublickKey	base32	계정의 Normal public key
TxChainHeight	int	계정의 Height
TxLink	string	마지막 Tx link

locus_getWorldRoundStatesList

World Round State (WRS) 목록을 구합니다.

Request

Key	Type	Description
Round	int	구하고자 하는 시작 Round
Count	int	구하고자 하는 갯수 (시작 위치에서 이전 몇개), Max 500.

Response

Key	Type	Description
NextRoundList	[]int	WRS 목록

locus_getWorldRoundState

World Round State (WRS) 상세 정보를 구합니다.

Request

Key	Type	Description
Round	int	구하고자 하는 Round

Response

Key	Type	Description
NextRound	int	Round
AddShardRound	int	0 : 샤드 분할 예정 없음. 1 : 샤드 분할해야 하는 상황이지만, 언제인지 정해지지 않았음. 2 이상 : 해당 Round에 샤드 분할 예정됨.
RootHash	string
EvictedHash	string
CurrentHash	string
PrevLink	string
PrevNextRound	int
SigHash	string	아래 서명 정보의 해시값. 아래의 서명 정보는 프루닝 될 수 있다.
ValidatorsWeight	int	Validator의 Weight 총합
Validators	[]{base32,uint16,string}	{Validator's Addr, Weight, Sign}
MultiSign	string	멀티서명
AggregatedNonce	string	멀티서명의 aggregated nonce
CoSigners	[]base32	멀티서명 참가자의 계정

locus_getInactivateTxList

계정의 아직 Activate되지 않은 Tx 목록을 구합니다.

Request

Key	Type	Description
Account	base32	계정

Response

Key	Type	Description
TimeOutTxs	[]{Sender base32, Index int32, Tx string}	1차 Target 이 Activation 하지 않아, Time out 되어 들어온 Tx 목록.
Txs	[]{Sender base32, Index int32, Tx string}	Sender 쪽의 합의가 완료된 Tx 목록.
UnconfirmedTxs	[]{Sender base32, Index int32, Tx string}	Sender 쪽의 합의를 대기중인 Tx 목록.
PendingTxs	[]{Sender base32, Index int32, Tx string}	Propose 된지 10초 미만의 Tx 목록.
ConflictedTxs	[]{Sender base32, Index int32, Tx string}	충돌난 Tx 목록.

locus_getMontInfoList

계정의 Mont(MOnitoring seNT) 목록을 구합니다. 노드의 호스트/게스트 계정의 것만 구할 수 있습니다.

Request

Key	Type	Description
Account	base32	계정

Response

Key	Type	Description
ActivatedTxs	[]{Index int32, Tx string}	Receiver쪽 샤드의 Recv list 에 포함되어 합의가 완료된 Tx 목록. 아직 Receiver의 체인에 write 되지 않았을 수도 있음.
ProofedTxs	[]{Index int32, Tx string}	Sender 쪽의 합의가 완료된 Tx 목록.
PendingTxs	[]{Index int32, Tx string}	Propose만 된 Tx 목록.

locus_createToken

시스템 토큰을 생성합니다.
계정당 하나의 시스템 토큰을 생성할 수 있습니다.

Request

Key	Type	Description
Account	base32	토큰을 생성할 계정
TokenBalance	string	생성할 토큰 갯수
Sig	base64	서명

Response

Key	Type	Description
TokenID	base32	생성된 토큰 ID
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_transferToken

토큰을 다른 계정에 보냅니다.

Request

Key	Type	Description
From	base32	토큰을 보내는 계정
To	base32	토큰을 받을 계정
Amount	string	보낼 토큰 갯수
TokenID	base32	보낼 토큰 ID
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_getAccountTokenList

계정이 소유한 토큰 목록과 Balance를 구합니다.

Request

Key	Type	Description
Account	base32	토큰을 생성할 계정

Response

Key	Type	Description
TokenList	map[base32]string	{"TokenID": Balance}

locus_hasSystemToken

계정이 생성한 시스템 토큰이 존재하는 여부와 존재하면 토큰 ID를 구합니다.

Request

Key	Type	Description
Account	base32	계정

Response

Key	Type	Description
Having	bool	시스템 토큰이 존재하는지 여부
TokenID	string	Having 이 true 이면, 시스템 토큰 ID를 돌린다.

locus_postData

데이터를 게시합니다.

Request

Key	Type	Description
Account	base32	계정
Label	int	체인 내에서 같은 라벨의 Tx끼리 링크됨. 해당 Tx에 대해 Proof를 Verify할 때 같은 라벨의 더 최신의 Tx가 있는지를 확인하는 용도로 사용됨.
Data	base64	게시할 데이터
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_readTxListWithProof

계정의 Tx 목록과 Proof를 함께 구합니다.

Request

Key	Type	Description
Account	base32	계정
BaseHeight	int	시작 Height
Count	uint	구하고자 하는 갯수 (시작 위치에서 이전 몇개)

Response

Key	Type	Description
Account	base32	계정
Txs	[]string	Tx string 목록
Proof	MerkleProof	요청한 Tx 목록의 Merkle Proof
CheckRoundP1	int	Proof 가 생성된 Round + 1

locus_verifyTxListWithProof

Tx 목록의 Proof를 검증합니다.

Request

Key	Type	Description
Account	base32	계정
Txs	[]string	검증할 Tx 목록
Proof	MerkleProof	검증할 Tx 목록의 Merkle Proof
CheckRoundP1	int	proof 가 생성된 Round + 1

Response

Key	Type	Description
-	bool	검증 성공 여부

locus_generateLatestStoredDataProof

특정 label의 TxPostData가 가장 최신인지 증명하는 Proof를 생성합니다.

Request

Key	Type	Description
Account	base32	계정
BaseHeight	int	Proof를 생성할 첫번째 TxPostData의 height

Response

Key	Type	Description
Account	base32	계정
CheckRoundP1	int	LatestProof 가 생성된 Round + 1
Tx	string	Proof 의 대상이 된 TxPostData
TxProof	MerkleProof	Tx의 존재에 대한 proof
LatestProof	MerkleProofMulti	Tx가 최신 StoredDataHash에 포함되어 있다는 Proof
LatestTxs	[]string	마지막 TxPostData 이후에 다른 TxPostData가 없음을 증명
LatestTxsProof	MerkleProof	LatestTxs의 존재에 대한 Proof
SummaryDataHash	base64	Ledger 안에 TxPostData가 없거나 Tx가 하나도 없는 경우, Summary의 Data Hash
SummaryTxLink	base64	Ledger 안에 TxPostData가 없거나 Tx가 하나도 없는 경우, Summary의 Tx Link

locus_verifyLatestStoredDataProof

locus_generateLatestStoredDataProof RPC로 생성한 Proof를 검증합니다.

Request

Key	Type	Description
ValidityRound	int	해당 Proof 가 유효한 Round 수 0 이면, 생성된 그 Round에서만 유효하다. 1 이면, 생성된 Round와 그 다음 Round까지 유효하다. n 이면, 생성된 Round +n Round 까지 유효한다.
Account	base32	Tx 목록의 Proof를 생성할 계정
CheckRoundP1	int	LatestProof가 생성된 Round + 1
Tx	string	Proof의 대상이 된 TxPostData
TxProof	MerkleProof	Tx의 존재에 대한 Proof
LatestProof	MerkleProofMulti	Tx가 최신 StoredDataHash에 포함되어 있다는 Proof
LatestTxs	[]string	마지막 TxPostData 이후에 다른 TxPostData가 없음을 증명
LatestTxsProof	hex	LatestTxs 의 존재에 대한 Proof
SummaryDataHash	hex	Ledger 안에 TxPostData가 없거나 Tx가 하나도 없는 경우, Summary의 Data Hash
SummaryTxLink	hex	Ledger 안에 TxPostData가 없거나 Tx가 하나도 없는 경우, Summary의 Tx Link

Response

Key	Type	Description
-	bool	검증 성공 여부

locus_lockStake

Stake를 Lock합니다.

Request

Key	Type	Description
Account	base32	계정
LockAmount	uint32	Lock할 Stake 수량 (1 UnitStakeLock = 100 Locus)
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_unlockStake

Stake를 unlock합니다.

Request

Key	Type	Description
Account	base32	계정
UnlockAmount	uint32	Unlock할 Stake (1 UnitStakeLock = 100 Locus)
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_provideScript

Core Script를 배포합니다.

Request

Key	Type	Description
Provider	base32	배포할 계정
Target	base32	Time lock 이내에 Core script를 실행하여, provider가 send한 coin 이나 token을 activation할 계정
TargetAfterTimeLock	base32	Time lock 이후에 provider가 send한 coin 이나 token을 자동으로 activation할 계정
TimeLock	int	Time lock 이 걸리는 round duration, 현재 Max = 30, Min = 3 으로 설정되어 있음.
Args	[]hex	Target이 provider의 script (ScriptSig)를 실행할 때, 사용될 아규먼트, 최대 4개까지 입력가능.
ScriptProvide	hex	Target이 실행할 provider의 script, 현재 MaxSize = 32 bytes
ScriptAccept	hex	Target이 실행할 target의 script, 현재 MaxSize = 32 bytes
Amount	string	Target이 Core script 실행에 성공할 경우, activation 시킬 수 있는 coin amount
TokenAmounts	[]{TokenID base32, AmountToken string}	Target이 Core script 실행에 성공할 경우, activation 시킬 수 있는 token amounts
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_acceptScript

Core Script를 실행합니다.

Request

Key	Type	Description
Acceptor	base32	TxProvideScript에서 Target으로 지정된, Core Script를 activation 시킬 계정 Time lock 이내에만 activation이 가능함.
Provider	base32	TxProvideScript를 배포한 계정
Index	int	LeadTx(TxProvideScript)의 height
Args	[]hex	Target이 Target의 script (ScriptSig)를 실행할 때 사용될 아규먼트., 최대 4개까지 입력가능.
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

locus_queryAddress

Key Address로 Full Address를 조회합니다.

Request

Key	Type	Description
Addr	base32	Key Address

Response

Key	Type	Description
Addr	base32	Full Address

debug_createContract

Contract를 생성합니다.

Request

Key	Type	Description
Account	base32	address of creator
ContractAccount	base32	첫번째 call의 리턴값을 두번째 call에 넣습니다. 혹시 주소를 외부에서 생성한 경우에는 첫번째 call에 넣으면, 그 주소로 생성합니다.
FuelLimit	uint32	contract 생성에 소모할 fuel의 한계치
Amount	string	생성된 contract account에 deposite 해 놓을 코인. creator의 코인에서 차감된다.
TokenAmounts	[]{TokenID base32, AmountToken string}	contract에 전송할 token 정보
SysId	base32	VME Id
Code	base64	소스의 binary code
Sig	base64	서명

Response

Key	Type	Description
ContractAccount	base32	생성된 contract의 주소. 첫번째 call의 리턴값을 두번째 call의 인자로 넣으세요.
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

debug_callContract

Contract의 합수를 호출합니다.

Request

Key	Type	Description
CallerAccount	base32	contract를 호출하는 계정
ContractAccount	base32	contract의 주소
FuelLimit	uin32	contract 실행에 소모할 fuel의 한계치
Amount	string	contract에 전송할 coin 수
TokenAmounts	[]{TokenID base32, AmountToken string}	contract에 전송할 token 정보
Func	base64	호출할 함수명의 바이트 코드
ArgData	base64	호출할 때 인자
Sig	base64	서명

Response

Key	Type	Description
Hash	Tx Hash
Tx	string	생성된 Tx
Success	bool	성공 여부

debug_viewContract

Contract의 변수 또는 View함수를 읽기 전용으로 호출 합니다.
트랙젝션을 만들지 않으며 노드의 VM을 실행하여 결과 값을 가져 옵니다.
deubg_callContract 와 파라메터가 동일하나 Balance 와 Grant 등은 소비하지 않습니다.

Request

Key	Type	Description
CallerAccount	base32	contract를 호출하는 계정
ContractAccount	base32	contract의 주소
FuelLimit	uin32	contract 실행에 소모할 fuel의 한계치
Amount	string	contract에 전송할 coin 수
TokenAmounts	[]{TokenID base32, AmountToken string}	contract에 전송할 token 정보
Func	base64	호출할 함수명의 바이트 코드
ArgData	base64	호출할 때 인자
Sig	base64	서명

Response

Key	Type	Description
Result	base64	호출한 결과 값
Err	string	오류 발생 시 내용

JSON RPC가 무엇일까요?​

로커스체인 RPC​

호출​

단순 조회용 RPC 호출​

Tx를 생성하는 RPC 호출​

RPC 호출 예시​

공통 응답 형식​

함수 목록​

locus_echo​

Request​

Response​

locus_getSyncState​

Request​

Response​

locus_getGenesisAccount​

Request​

Response​

locus_openAccount​

Request​

Response​

locus_becomeHost​

Request​

Response​

locus_becomeGuest​

Request​

Response​

locus_changeKey​

Request​

Response​

locus_transferCoin​

Request​

Response​

locus_getTx​

Request​

Response​

locus_getAccountsHeights​

Request​

Response​

locus_getAccountHistory​

Request​

Response​

locus_getAccountDetail​

Request​

Response​

locus_getWorldRoundStatesList​

Request​

Response​

locus_getWorldRoundState​

Request​

Response​

locus_getInactivateTxList​

Request​

Response​

locus_getMontInfoList​

Request​

Response​

locus_createToken​

Request​

Response​

locus_transferToken​

Request​

Response​

locus_getAccountTokenList​

Request​

Response​

locus_hasSystemToken​

Request​

Response​

locus_postData​

Request​

Response​

locus_readTxListWithProof​

Request​

Response​

locus_verifyTxListWithProof​

Request​

Response​

locus_generateLatestStoredDataProof​

Request​

Response​

JSON RPC가 무엇일까요?

로커스체인 RPC

호출

단순 조회용 RPC 호출

Tx를 생성하는 RPC 호출

RPC 호출 예시

공통 응답 형식

함수 목록

locus_echo

Request

Response

locus_getSyncState

Request

Response

locus_getGenesisAccount

Request

Response

locus_openAccount

Request

Response

locus_becomeHost

Request

Response

locus_becomeGuest

Request

Response

locus_changeKey

Request

Response

locus_transferCoin

Request

Response

locus_getTx

Request

Response

locus_getAccountsHeights

Request

Response

locus_getAccountHistory

Request

Response

locus_getAccountDetail

Request

Response

locus_getWorldRoundStatesList

Request

Response

locus_getWorldRoundState

Request

Response

locus_getInactivateTxList

Request

Response

locus_getMontInfoList

Request

Response

locus_createToken

Request

Response

locus_transferToken

Request

Response

locus_getAccountTokenList

Request

Response

locus_hasSystemToken

Request

Response

locus_postData

Request

Response

locus_readTxListWithProof

Request

Response

locus_verifyTxListWithProof

Request

Response

locus_generateLatestStoredDataProof

Request

Response