API

API 설명

Ardor API를 이용하면 port 27876을 통해 HTTP로 Ardor 노드와 연결 할 수 있습니다. 대부분의 HTTP 요청엔 GET 또는 POST 메소드를 사용 할 수 있지만, 몇몇 API 호출은 보안상의 이유로 POST 메소드만 사용 가능합니다. 응답은 JSON objects 형태로 반환됩니다.

혹시 Ardor testnet local node와 연결 하고자 하시는 경우, 다른 HTTP port를 사용 하셔야 합니다. 메인넷은 27876 port를 사용하며, 테스트넷은 26876 port를 사용합니다.

각각의 API 호출에 대한 설명은 (전체 API List)에 문서화 되어 있습니다. 각각의 HTTP 요청 매개 변수 및 JSON 응답 필드에 대한 정의가 되어 있으며, 이어서 예제가 수록되어 있습니다 :

• JSON 응답 필드엔 영문 대문자가 붙어 있고, 각각이 뜻하는 바는 다음과 같습니다. S : String, A: Array, O : Object, N : Number, B : Boolean
• 각각의 예제에서 Ardor node는 "localhost"로 표시되며, 요청과 응답은 가독성을 위해 별도의 양식을 사용합니다. ; 줄 바꿈 및 공백은 일부 매개변수에만 사용되며 대부분 실제 사용되지 않습니다. 모든 요청은 HTTP GET 메소드를 의미하는 URL 포맷입니다. GET이 허용되는 경우, 브라우저 URL 입력란에 URL을 입력 할 수 있지만, 적절한 URL Encoding이 필요합니다.(예 : 매개 변수 값의 공백을 + 또는 %20으로 바꿔야 함). 그렇지 않으면 URL은 가이드로 사용되어야 합니다. (예 : URL을 cURL을 이용해 HTTP POST 요청을 준비하는 용도로 사용)

모든 API 호출은 로컬 서버노드가 실행되는 동안 http://localhost:27876/test 에서 확인하고 테스트 할 수 있습니다. 특정 API 호출의 경우 'http://localhost:27876/test?requestType=specificRequestType'을 사용 하십시오.

차일드 체인 트랜잭션에 대한 최상의 번들 비용 계산, 리모트 노드에 의존하지 않고 API를 로컬로 사용하는 것 과 같은 몇가지 Sample Java Programs을 제공하고 있으니 참고 하시면 됩니다.

이 문서에서 다루는 Ardor 플랫폼은 버젼2.4.3 입니다. : 개발자용 Ardor 치트 시트 다운로드

Ardor developers cheat sheet

Java Conversion Functions

From	To	Code
Secret Phrase	Public Key	Crypto.getPublicKey(String s)
Public Key	Numeric ID	Account.getId(byte[] pk)
Numeric ID	Public Key	Account.getPublicKey(long id)
Numeric ID	String ID	Long.toUnsignedString(long id)
String ID	Numeric ID	Convert.parseUnsignedLong(String s)
Numeric ID	RS Format	Convert.rsAccount(id)
RS Format or String ID	Numeric ID	Convert.parseAccountId(String s)
byte[]	Hex String	Convert.toHexString(b)
Hex String	byte[]	Convert.parseHexString(hex)
Full Hash	ID	Convert.fullHashToId(byte[] b)
Epoch Time	Time Millis	Convert.fromEpochTime(int t)
Time Millis	Epoch Time	Convert.toEpochTime(long t)
String	byte[]	Convert.toString(byte[] b, Boolean isText)
byte[]	String	Convert.toBytes(String s, boolean isText)

Java Common Operations

Operation	Code	Return
Sign	Crypto.sign(byte[] message, String secretPhrase)	byte[]
Verify	Crypto.verify(byte[] signature, byte[] message, byte[] publicKey)	Boolean
Encrypt	Account.encryptTo(byte[] publicKey, byte[] data, String senderSecretPhrase, boolean compress)	EncryptedData
Decrypt	Account.decryptFrom(EncryptedData encryptedData, String recipientSecretPhrase, boolean uncompress)	byte[]
Sha256	Crypto.sha256().digest(byte[] b)	byte[]
Compress	Convert.compress(byte[] bytes)	byte[]
Uncompress	Convert.uncompress(byte[] bytes)	byte[]

Useful Constants see nxt.Constants class

Reading from properties file Nxt.getBooleanProperty(), Nxt.getIntProperty(), Nxt.getStringProperty(), Nxt.getStringListProperty()

Javascript Conversion Functions

From	To	Code
Secret Phrase	Public Key	NRS.getPublicKey(converters.stringToHexString(secretPhrase))
Public Key	String ID	NRS.getAccountIdFromPublicKey(publicKeyHexString)
String ID	Public Key	NRS.getPublicKey(id, true)
String ID	RS Format	NRS.convertNumericToRSAccountFormat(id)
byte[]	Hex String	converters.byteArrayToHexString(bytes)
Hex String	byte[]	converters.hexStringToByteArray(hex)
Full Hash	ID	NRS.fullHashToId(fullHash)
Epoch Time	Time Millis	NRS.fromEpochTime(epochTime)
Time Millis	Epoch Time	NRS.toEpochTime(time)
String	byte[]	NRS.getUtf8Bytes(String), converters.stringToByteArray(String)
byte[]	String	converters.byteArrayToString(bytes)
NQT	Chain tokens	NRS.intToFloat(amountNQT, decimals)
NQT	formatted	NRS.formatQuantity(amountNQT, decimals) – many different variants
Chain tokens	NQT	NRS.floatToInt(amountNXT, decimals)

Javascript Common Operations

Operation	Code	Return
Sign	NRS.signBytes(hexStringMessage, secretPhrase)	Hex String
Verify	NRS.verifySignature(hexSignature, hexStringMessage, hexPublicKey, callback)	boolean
Encrypt	NRS.encryptNote(), NRS.encryptData() – see test.nrs.encryption.js	encrypted message, nonce
Decrypt	NRS.decryptNote(), NRS.decryptData() - see test.nrs.encryption.js	Decrypted message, shared key
Sha256	CryptoJS.algo.SHA256.create(), update(), finalize()	word array
Compress	pako.gzip(new Uint8Array(bytes))	byte array
Uncompress	pako.inflate(new Uint8Array(bytes))	byte array

Useful Constants see nrs.constants.js class

Reading account settings NRS.settings[<setting name>] - account specific NRS.mobileSettings[<setting name>] - device specific

General Notes

Flexible Account IDs

All API requests that require an account ID accept either an account number or the corresponding Reed-Solomon address.

Quantity Units amountNQT, QNT and priceNQTPer(Share, Coin, Unit, etc.)

Ardor 시스템은 거래를 통해 보유한 ARDOR 수량에 따라 정의 될 수 있습니다. Ardor Parent Chain엔 시스템에서 포징 수량을 계산하는데 사용되는 ARDR가 존재합니다. 다른 모든 통화처럼, ARDR도 시스템내에서 순환하며 송금을 통해 특정 사용자로부터 다른 사용자에게 이동됩니다. 또한 ARDR가 실제 전송되지 않는 메시지 같은 차일드 체인 트랜잭션을 발생 시키더라도, ARDR 수수료가 필요 하게 됩니다. 이 ARDR수수료는 이 트랜잭션이 포함된 블록을 생성하는(포징하는) 노드에게 지급이 되어야 하는데, 이때 번들러가 차일드 체인 트랜잭션을 하나의 차일드 블록으로 만들고, ARDR 수수료를 포징하는 노드에게 지급합니다. 그리고 번들러는 차일드 체인 토큰으로 차일드 트랜잭션 발생자에게 수수료를 받습니다.

스냅샷을 통해 NXT 홀더들에게 10억개의 ARDR이 1:1 비율로 에어드롭 되었으며, 앞으로 새로운 ARDR는 생성되지 않습니다. ARDR는 소수점 이하 8자리까지 나뉠 수 있으며, 내부적으로는 정수형태로 amountNQT단위로 저장됩니다. 1ARDR = 10⁸ amountNQT. 따라서 API의 모든 매개변수와 필드는 amountNQT 단위로 표시됩니다.(예:"feeNQT")

Ardor System의 소유자는 ARDR를 보유한 모든 사람이라고 할 수 있습니다. 이러한 의미에서 ARDR는 시스템의 소유권 혹은 지분의 수량을 의미 합니다. 홀더는 소유한 ARDR 수량에 비례해 블록을 생성하고, 트랜잭션 수수료를 징수 할 권한이 있습니다.

차일드 체인 내의자산 발행 기능을 사용하여 ARDR를 이용해 다른 자산을 발행 할 수도 있습니다. 발행자는 우선 자산을 수량화 할때 사용할 소수 자리수와 발행할 양을 QNT(Quant)의 수량으로 정해야 합니다. 자산의 수량은 내부적으로 QNT단위의 정수로 저장되기 때문에, 자산 가격은 NQTper(Share, Coin, Unit 등)으로 책정이 됩니다.

예를 들어 비트코인을 의미하는 ABTC라는 자산이 있다면, 원래 BTC처럼 소수 점 8자리로 나눌 수 있을 것입니다. 따라서 ABTC의 QNT는 사토시(10^-8 BTC)와동일합니다. 25,000,000 QNT를 20,000 priceNQTperShare의 가격으로 매도 주문을 넣으려 한다면 API 호출은 Ignis 체인에서 다음과 같이 진행하면 됩니다. requestType=placeAskOrder, quantityQNT=25000000 and priceNQTPerShare=20000 매도 주문 자산 거래소에서 수량 전체가 판매될 경우, 판매자는 구매자로부터 500,000,000,000 NQT (quantityQNT * priceNQT)를 수령하게 됩니다. 이 거래는 0.25 ABTC를 5,000 IGNIS에 판매 하는 것과 동일하며, 이 방식을 통해 NRS client에 거래 내역이 표시 됩니다. 이 경우 priceNQTperShare로 표시된 20,000은 곧 Ignis/ABTC가격과 동일합니다. 따라서 해당 주문 내역은 ABTC 형태로든, IGNIS 형태로든 소수점 8자리로 표시 할 수 있습니다.

Ardor 통화 시스탬내에서의 통화들은 실제 통화 기능에 적합한 속성과 거래 기능을 지원하는 특수한 형태의 자산입니다. 수량, 환율, 소수 자리수 정보와 관련해 통화 시스템의 API 호출은 amountNQT, QNT, priceNQTPer(Share, Coin, Unit 등)을 사용하며, 이는 자산의 API호출 방식과 동일합니다.

서명하지 않은 트랜잭션 생성하기

새로운 트랜잭션을 생성하게되는 모든 API 요청은 암호문구(secretPhrase) 나 퍼블릭키(publicKey) 매개변수를 받을 것 입니다. :

• 만약 비밀문구(secretPhrase)를 받게되면 서버에서 서명되어 트랜잭션이 생성되고, 이를 전파 할 것입니다.
• 만약 64-dibit(32-byte)의 16진수 문자열인 퍼블릭키(publicKey)만 제공된다면 서버에선 트랜잭션을 서명없이 transactionJSON처럼 JSON 형태로 보낼 것입니다. 이 JSON 객체와 비밀 문구가 함께 제공이 되면 트랜잭션 서명을 할 수 있으며 형태는 unsignedTransactionJSON이 될 것입니다. 그리고 결과물은 서명된 transactionJSON이 되고 이제 트랜잭션 전파를 할 수 있습니다. 이러한 절차를 통해 트랜잭션에 오프라인 서명 하는 것이 가능해지고, 따라서 비밀문구가 노출 될 염려가 없습니다.
• 만약 암호화된 메시지가 필요 하지 않을 경우엔 서명되지 않은 transactionJSON 대신 unsignedTransactionBytes를 사용 할 수 있을 것입니다. 메시지를 암호화하기 위해선 비밀문구가 필요하므로 암호화 메시지는 unsignedTransactionBytes에 포함 될 수 없습니다.

에스크로 운영

신규 트랜잭션을 생성하는 모든 API 요청은 연결된 트랜잭션을 생성하는 referencedTransactionFullHash 매개 변수를 선택적으로 받습니다. 여기에서 말하는 연결된 트랜잭션이란 참조된 트랜잭션이 컨펌 되지 않으면, 신규 트랜잭션도 컨펌 될 수 없는 트랜잭션을 의미합니다. 이 기능을 통해 트랜잭션 에스크로를 간단히 구현 할 수 있게 됩니다. :

• Alice는 트랜잭션 A를 생성하고 서명하지만, broadcast 파라미터를 false로 설정하여 브로드캐스트 하지는 않습니다. 그리고 Alice는 Bob에게 unsignedTransactionBytes, 트랜잭션의 fullHash, and signatureHash를 보냅니다. 이 모든 것들은 API 요청에 의해 반환되는 JSON에 포함되어 있습니다.(경고: 서명된 transactionBytes나 signature를 그대로 보내면 안됩니다. Bob이 임의대로 트랜잭션 A를 브로드캐스트 할 수 있기 때문입니다.).
• Bob은 트랜잭션 B를 준비하여 서명하고 브로드 캐스트 합니다. 이때, referencedTransactionFullHash 파라미터는 Alice가 제공한 A 트랜잭션의 fullHash가 되도록 설정합니다. 이후 Bob이 (Alice로 부터 받은) unsignedTransactionBytes 와 signatureHash를 사용하여 Full 해시를 계산하면, Alice로부터 예상했던 트랜잭션의 해시인지 검증 할 수 있습니다. 뿐만 아니라 Bob이 트랜잭션 파싱을 진행하면 서명되지 않은 바이트를 해독하고, 모든 트랜잭션 항목을 검사 할 수도 있습니다.
• 트랜잭션 B는 미확인 트랜잭션 풀에 포함되었지만, A가 서명 되지 않는 한 B는 컨펌 되지 않습니다.(블록체인에 포함되지 않습니다.) 만약 A 트랜잭션이 영원히 제출되지 않는다면, B 트랜잭션은 결국 만료 될 것입니다. - 따라서 Bob은 트랜잭션 만료 기한을 32767 분처럼 최대로 설정해 놓는 것이 좋습니다.
• B 트랜잭션이 미확인 트랜잭션 풀에 들어가면, Bob은 이 트랜잭션을 되돌 릴 수 없습니다. 따라서 Alice는 처음에 살펴 보았던 signedTransactionBytes를 브로드 캐스트 함으로써 트랜잭션 A를 안전하게 제출 할 수 있습니다. 트랜잭션 A가 먼저 블록체인에 포함된 이후에 다음 블록에 Bob의 트랜잭션 B가 포함 될 것입니다.

위에서 설명한 체계는 간단한 에스크로에서는 충분하지만, 블록체인은 A가 포함되면 B 또한 포함되도록 강제하지 않습니다. 때론 포크나 블록체인 재구성으로 인해 발생 할 수도 있지만, 트랜잭션 A가 블록체인에 있는 한 B는 포함되거나 컨펌되지 않은 상태로 만료 될 일은 없습니다. 하지만, Bob이 의도적으로 이러한 일련의 이벤트를 발생시켜 트랜잭션 B가 컨펌 되는 것을 막을 수는 없습니다.

프루닝 가능한 데이터

프루닝 가능한 데이터는 블록체인의 무결성에 영향을 미치지 않고도 블록체인에서 제거가 가능합니다. 프루닝 가능한 데이터를 포함하는 트랜잭션이 생성되면, 이 데이터는 sha256 함수의 결과값인 32-byte의 해시값만 transactionBytes에 포함되고, 데이터는 자체는 포함 않습니다. 프루닝 할 수 없는 서명된 transactionBytes는 서명을 검증하고 트랜잭션의 fullHash와 ID를 생성하는데 사용됩니다. ; 따라서 이후 트랜잭션의 프루닝 가능한 부분이 제거 되도라도, 전체 시스템에는 아무런 영향을 미치지 않게 됩니다.

프루닝 가능한 데이터는 트랜잭션 타임스탬프로부터 미리 정해진 2주(Testnet에선 24시간)의 수명을 가지게 됩니다. 이 시간이 경과하기 전에 프루닝 가능한 데이터가 누락된 경우, 피어 노드로부터 받은 트랜잭션이나 블록은 승인되지 않습니다. 만약 이 기간이 지났다면, 프루닝 가능한 데이터는 더이상 트랜잭션과 블록에 포함되어 전파되지 않아도 되며, GET Transaction과 같은 범용 API호출에 의해 반환된 JSON 트랜잭션에 포함되지 않아도 됩니다. ; 시간이 지나 프루닝된 데이터를 검색 할 수 있는 유일한 방법은 Get Prunable Messabe같은 특수 목적의 API 호출을 사용 하는 것입니다.

만료된 프루닝 가능한 데이터는 파생 테이블이 트리밍되어 제거 될 때 까지만 블록체인에 저장이 됩니다. 그리고 이 작업은 기본적으로 매 1000블록마다 실행이 됩니다. 만료된 프루닝 가능한 데이터를 즉시 제거하려면 파생 테이블 잘라내기를 사용하면 됩니다.

프루닝 가능한 데이터를 최소 수명인 2주 이상으로 보관하기 위해선 nxt.maxPrunableLifetime 속성을 2주보다 더 큰 값으로 변경하면 되며, -1로 설정하면 무기한 보존할 수 있습니다. 트랜잭션과 블록이 피어 노드로 전송 될 때 노드가 보존하고 있는 프루닝 가능한 데이터를 함께 전송하려 하려면 nxt.includeExpiredPrunables 속성을 true로 변경하면 되고, 이러한 노드가 아카이브 노드(Archival Node)가 됩니다.

현재 NXT 시스템의 프루닝 가능한 데이터는 총 두가지 종류 입니다. : 임의 메시지(Arbitrary Messages), 태그된 데이터. 이 두가지 유형 모두 최대 42KB의 데이터를 가질 수 있습니다.

속성 파일

일부 API 호출의 동작은 Ardor 서버 초기화시에 ardor/conf 디렉토리에 있는 파일들로부터 불러온 속성 설정에 영향을 받습니다. 이 디렉토리에는 문서와 함께 기본 속성 설정을 포함하는 nxt-default.properties 파일과 logging-default.properties파일이 있습니다. 일부 속성 설정은 서버가 Get Blockchain Status나 Get State를 호출 할 경우 얻을 수 있습니다.

소프트웨어 업데이트 중에 덮어쓰기가 진행 될 수 있으므로, 기본 등록 정보 파일은 수정 하지 않는 것이 좋습니다. 대신 기본 파일의 속성정보를 동일한 디렉토리의 옵션으로 제공되는 nxt.properties파일과 logging.properties 파일에 포함하면 무시 할 수 있습니다. 예를 들어, nxt.properties파일은 다음 내용으로 생성 할 수 있습니다.:

nxt.isTestnet=true

이렇게 설정하게 되면 Ardor 서버는 Mainnet 대신 Testnet과 연결하게 됩니다.

관리자 비밀번호

일부 API 함수는 adminPassword 매개 변수를 사용합니다. 이 매개 변수는 nxt.disableAdminPassword 속성이 true로 설정되어 있지 않거나 API 서버가 localhost 인터페이스에서만 수신하지 않는 경우( nxt.apiServerHost 속성이 127.0.0.1로 설정 되어 있는 경우) nxt.adminPassword 속성과 일치해야 합니다.

모든 Debug Operations 에는 일부 권한이 필요하기 때문에 adminPassword가 필요 합니다. 일부 기능에서 adminPassword가 사용되므로, lastIndex매개변수에 허용된 최대 값(기본적으로 100으로 되어있는 nxt.maxAPIRecords 속성)을 무시 할 수 있습니다. 이렇게 되면 요청당 Object 이상을 검색 할 수 있습니다.

로밍 및 라이트 클라이언트 모드

로밍(Full 노드가 되기 위해 블록체인을 다운받을 경우) 및 라이트 클라이언트 모드에서 사용할 수 있는 리모트 노드는 임의로 선택되지만, UI에서 수동으로 변경하거나 API Proxy Peer 설정을 사용하거나 nxt.forceAPIProxyServerURL 속성을 변경해 특정 피어에 접속 할 수 있습니다.

리모트 노드는 블랙리스트에 올려 질 수도 있는데요, UI에서 진행하거나, API Proxy Peer 블랙리스트를 통해 진행 할 수 있습니다. 이 블랙리스트는 피어 블랙리스트와는 별개의 리스트입니다. API Proxy 블랙리스트 기간은 nxt.apiProxyBlacklistingPeriod 속성을 사용해 변경 할 수 있습니다. (기본셋팅은 1800000 밀리초 입니다).

로밍 또는 라이트 클라이언트 모드에서는 포징, 셔플링, 자금 모니터 실행과 같은 기능을 사용할 때 필요한 비밀문구, 퍼블릭키, 관리자 비밀번호를 서버에 보내야 하는 API 요청은 사용 할 수 없습니다.