API

From ArdorDocs
Jump to: navigation, search
This page is a translated version of the page API and the translation is 100% complete.

Other languages:
English • ‎한국어

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.2.5 입니다. : 개발자용 Ardor 치트 시트 다운로드

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 = 108 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에 포함 될 수 없습니다.

'

프루닝 가능한 데이터

프루닝 가능한 데이터는 블록체인의 무결성에 영향을 미치지 않고도 블록체인에서 제거가 가능합니다. 프루닝 가능한 데이터를 포함하는 트랜잭션이 생성되면, 이 데이터는 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 StatusGet 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 요청은 사용 할 수 없습니다.