Data Anchoring

This page introduces how to anchor service chain data to Klaytn main chain with Anchor API.

Before Getting Started

The x-chain-id value for calling the API is 8217 (Cypress) or 1001 (Baobab).
Essential parameters for calling APIs are described in individual examples.

Values that a user needs to enter for calling APIs will be represented with one pair of braces ({}). A user must enter the following values.

Item

Description

Note

chain-id

8217 or 1001

Cypress(Klaytn mainnet) or Baobab(Klaytn testnet

access-key-id

Auth ID

accessKeyId obtained from KAS Console - Security - Credential

secret-access-key

Auth Password

secretAccessKey obtained from KAS Console - Security - Credential

krn

(optional) ID of Account Pool

Unnecessary when using Default Account Pool

A KAS API Authentication Key (API Auth Key) provides access to all KAS services and all the rights to a Klaytn account which was created by calling Wallet API via this API Auth Key. The rights here include accessing and transferring all the assets (KLAY, etc.) of or sending a transaction from a Klaytn account. If you shared your API Auth Key with any unauthorized personnel, your Klaytn account could be compromised and might cause unwanted transaction execution.

DO NOT share your API Auth Key (Secret AccessKey or Authorization) with any unauthorized personnel. DO PUT efforts necessary to keep your API Auth Key safe for the security of your KAS/Klaytn account.

For details about service chain, please visit here. For details about data anchoring of service chain, please visit here.

Create Operator

KAS Console - Service - Anchor - Operator

Click the “Create” button on the KAS Console - Service - Anchor - Operator menu. Click the button to display the screen for creating operators as follows.

Configure Transaction Fee Payments for Data Anchoring Transaction

For creating an operator on the KAS Console, set the account that would pay the anchoring transaction fee for data to be sent by the operator.

Parameter

Description

feepayer

User fee delegation payment account address. Used when paying data anchoring transaction fees using the fee-payer account.

useOperator

Whether the operator or KAS will pay data anchoring transaction fee (the transaction fee will be charged to the user)

useGlobalFeepayer

Whether the fee payer account provided by KAS first pays the bill (the transaction fee will be charged to the user later)

Use useGlobalFeepayer to send the data anchoring transaction even if the KLAY balance is insufficient.
An error will occur if all thee parameters are not set.
The data anchoring transaction fee will be delegated according to the following priorities if one or more parameters are entered.

To ensure smooth execution of the anchoring transaction, use useGlobalFeepayer.

To use feepayer, first create a Fee Delegation Account Pool and Fee Delegation Account. The fee-payer account address (address) and KRN value of the fee delegation Account Pool are required to use the feepayer.

The fee payment priority will be as follows if several parameters are used together to send anchoring transactions.

Priority

Parameter

the transaction fee payer

feepayer

User’s separate fee-payer account

useOperator

Operator

useGlobalFeepayer

KAS (transaction fee will be charged to the user later)

The account with higher priority will pay the anchoring transaction fee first if all three parameters are used. If the operator struggles to pay the transaction fee because of insufficient feepayer account balance, the operator that sends an anchoring transaction will directly pay the fee as it has the next priority.

Expected Results by Parameter Settings

useGlobalFeepayer

feepayer

useOperator

Priority

false

Error

true

false

KAS

false

true

Operator

true

Operator > KAS

false

User fee payer

false

true

User fee payer > Operator

true

User fee payer > Operator > KAS

true

false

User fee payer > KAS

Create Operator

Once the parameters are set, create an operator. The operator must have a different name from other operators on the current KAS account.

Operator You can check the created operator in the operator list. Or you can call all operator list search APIs and search.

For inquires about this document or KAS, please visit KAS Developer forum.

Get Operator List

API Request

Search for the list of created operators and setting values of each one. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

Query Parameter

You can receive API response values with Cursor-based Pagination. The search range can also be set by second.

Parameter

Description

Example

Required or Not

size

the number of items in the API response (min=1, max=1000, default=100)

size=100

False

cursor

the cursor required to get the next batch of response items

cursor=J9Ag...VM6z

False

to-timestamp

Search Range: The last timestamp (sec)

to-timestamp=15921809920

False

from-timestamp

Search Range: The first timestamp (sec)

from-timestamp=1592360291

False

curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator?&size=100&cursor=J9Ag...VM6z&from-timestamp=1592360291&to-timestamp=15991809920" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"

const query = caver.kas.anchor.queryOptions.constructFromObject({ fromTimestamp: 1501576981, toTimestamp: 1601876982, size: 3, cursor: '' })
const result = await caver.kas.anchor.getOperatorList(query)

AnchorQueryOptions anchorQueryParams = new AnchorQueryOptions();
anchorQueryParams.setSize((long)3);
anchorQueryParams.setFromTimestamp((long)1592360291);
anchorQueryParams.setToTimestamp((long)15991809920);

Operators operators = caver.kas.anchor.getOperatorList(anchorQueryParams);
System.out.println(operators);

x-chain-id is the id of the chain to which the operator was registered.

API Response

Here is the response of the Operator List Search API.

{
  "cursor": "",
  "items": [
    {
      "operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    },
    {
      "operator": "0x60A4B9342D439ED9D2DbdFf08aB9ceE1eFb73D10",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    },
    {
      "operator": "0x002909B4C40a874a5587aa0D15cc847F7E79aD76",
      "setting": {
        "useGlobalFeePayer": true,
        "useOperator": true
      }
    }
  ]
}

Operators {
  cursor: 'eyJjcmVhdGVkX2F0IjoxNTk4NTk2MTMzLCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweDAwODBFNDZEOEEwZmUxNGY4Mjk3OUM3MWNEZTM1QzhEN0MyYmZmOTAiLCJycG4iOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdCIsInR5cGUiOiJPUFIifQ==',
  items: [ 
    Operator {
      createdAt: 1598596270,
      operator: '0x371E04979132C23330eE777601C981453f7f542e',
      setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
    },
    Operator {
      createdAt: 1598596140,
      operator: '0xFb1f3B40BD102323d18ADC308D5B1bA91701156d',
      setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
    },
    Operator {
      createdAt: 1598596133,
      operator: '0x0080E46D8A0fe14f82979C71cDe35C8D7C2bff90',
      setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
    }
  ]
}

class Operators {
    cursor: 
    items: [class Operator {
        createdAt: 1597897525
        operator: 0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB
        setting: class OperatorSetting {
            useGlobalFeePayer: true
            useOperator: false
        }
    }, class Operator {
        createdAt: 1597897530
        operator: 0x60A4B9342D439ED9D2DbdFf08aB9ceE1eFb73D10
        setting: class OperatorSetting {
            useGlobalFeePayer: true
            useOperator: false
        }
    }, class Operator {
        createdAt: 1597897535
        operator: 0x002909B4C40a874a5587aa0D15cc847F7E79aD76
        setting: class OperatorSetting {
            useGlobalFeePayer: true
            useOperator: false
        }
    }]
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Get Operator Information

Or you can search for the created operator information with the operator’s Klaytn account address (operator-id).

API Request

Search for the settings and account balance of the operator above. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"

const result = await caver.kas.anchor.getOperator('0x371E04979132C23330eE777601C981453f7f542e')

Operator operator = caver.kas.anchor.getOperator("0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB");
System.out.println(operator);

x-chain-id is the id of the chain to which the operator was registered.

API Response

The response example of this API is as follows.

{
  "operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
  "setting": {
    "useGlobalFeePayer": true,
    "useOperator": true
  }
}

Operator {
  createdAt: 1598596270,
  operator: '0x371E04979132C23330eE777601C981453f7f542e',
  setting: OperatorSetting { useGlobalFeePayer: true, useOperator: false }
}

class Operator {
    createdAt: 1597897525
    operator: 0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB
    setting: class OperatorSetting {
        useGlobalFeePayer: true
        useOperator: false
    }
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Send Data Anchoring Transaction

A user must call the Data Anchoring API to anchor the service chain data to the main chain. Request for the data anchoring transaction with the Klaytn account address of the operator created above.

Payload

The “payload” is the “data itself to anchor to the main chain.” Here are examples of “custom_field1” and “custom_field2” entered in the following payload value. Enter the required data to anchor to the main chain in JSON format (key:value), similar to “custom_field1” and “custom_field2,” to use the payload.

Enter the string in the “id” field to Search Anchoring Transaction using the string.

API Request

Call the Data Anchoring API as follows. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

curl --location --request POST "https://anchor-api.klaytnapi.com/v1/anchor" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}" \
--header "Content-Type: application/json" \
--data-raw "{
  "operator": "0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026",
  "payload": {
    "id": "{$guid}",
    "customField1": "field1",
    "customField2": "field2"
  }
}"

const data = { id: '891825', custom_field: 'This is test custom field for anchoring'}
const result = await caver.kas.anchor.sendAnchoringData('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', data)

AnchorBlockPayload payload = new AnchorBlockPayload();
payload.put("id", Integer.toString(random.nextInt()));
payload.put("field", "1");
payload.put("filed2", 4);

AnchorBlockStatus response = caver.kas.anchor.sendAnchoringData(operatorID, payload);
System.out.println(response);

For details about data anchoring, please visit here.

If you want to use fee-delegation for sending this transaction, go to KAS Console - Anchor - Operator menu and configure fee-delegation. If you want to guarantee sending the anchoring transaction, please set UseGlobalFeePayer and use Anchor API.

API Response

A notification on whether the data anchoring is successful is returned as an API response.

{
"status": "succeed"
}

AnchorBlockStatus { status: 'succeed' }

class AnchorBlockStatus {
    status: succeed
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum. ㅏ

Get List of Anchoring Transaction by Operator Address

Search for the list of data anchoring transactions sent by this operator with the operator’s Klaytn account address.

API Request

Call the Anchoring Transaction Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

Query Parameter

You can receive API response values with Cursor-based Pagination. The search range can also be set by second.

Parameter

Description

Example

Required or Not

size

the number of items in the API response (min=1, max=1000, default=100)

size=100

False

cursor

the cursor required to get the next batch of response items

cursor=J9Ag...VM6z

False

to-timestamp

Search Range: The last timestamp (sec)

to-timestamp=15921809920

False

from-timestamp

Search Range: The first timestamp (sec)

from-timestamp=1592360291

False

curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/tx?&size=100&cursor=J9Ag...VM6z&from-timestamp=1592360291&to-timestamp=15991809920" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}" \
--header "Content-Type: application/json" \

const query = caver.kas.anchor.queryOptions.constructFromObject({ fromTimestamp: 1501576981, toTimestamp: 1601876982, size: 3, cursor: '' })
const result = await caver.kas.anchor.getAnchoringTransactionList('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', query)

AnchorQueryOptions anchorQueryParams = new AnchorQueryOptions();
anchorQueryParams.setSize((long)3);
anchorQueryParams.setFromTimestamp((long)1599142860);
anchorQueryParams.setToTimestamp((long)1599142845);

AnchorTransactions res = caver.kas.anchor.getAnchoringTransactionList(operatorID, anchorQueryParams);
System.out.println(res);

API Response

Here is the response of the Anchoring Data Search API.

{
  "cursor": "",
  "items": [
    {
      "createdAt": 1599142860,
      "payloadId": "c61cc0d0-5878-450e-bec8-bf73d6184798",
      "transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
    },
    {
      "createdAt": 1599142859,
      "payloadId": "d4f1a11f-4609-40f5-9d59-2313a5799508",
      "transactionHash": "0x70f6f6745ad0b0f4ce5908f40d20a1f44bd34871e0428be782d84f9a53ea2ba0"
    },
    {
      "createdAt": 1599142857,
      "payloadId": "48b59825-82b2-4595-abfb-c465112618cc",
      "transactionHash": "0x3f90cd2e02576fd85572ab76aff49b87b9cf3efb623f34bb8d6354ee1b88869f"
    },
    {
      "createdAt": 1599142841,
      "payloadId": "b315de34-52cb-41c0-9383-3260ceafd3b2",
      "transactionHash": "0x8a73a00f04a1f6e8d8af101487bd35f8dbcce6fcb3ddd95059f42b8f7fbc3345"
    }
  ]
}

AnchorTransactions {
  cursor: 'eyJjcmVhdGVkX2F0IjoxNTk5NjEyNzg5LCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6OGU3NmQwMDMtZDZkZC00Mjc4LThkMDUtNTE3MmQ4ZjAxMGNhOm9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweGM4QWEwNzNFMkE5MjRGYzQ2OTMzOUZmMGNCMkVjNEE3ODM4ODg4RDA6NTI3MzM5NDUzMiIsInF1ZXJ5X2lkIjoia3JuOjEwMDE6YW5jaG9yOjhlNzZkMDAzLWQ2ZGQtNDI3OC04ZDA1LTUxNzJkOGYwMTBjYTpvcGVyYXRvci1wb29sOmRlZmF1bHQ6QU5DSF9UWDoweGM4QWEwNzNFMkE5MjRGYzQ2OTMzOUZmMGNCMkVjNEE3ODM4ODg4RDAiLCJ0eXBlIjoiQU5DSF9UWCJ9',
  items: [
    AnchorTransaction {
      createdAt: 1599626680,
      payloadId: '5593367445',
      transactionHash: '0x93607f7f3a0131f804d0b847c18311ccb8b9aa6526b21febf19db9759038b0a6'
    },
    AnchorTransaction {
      createdAt: 1599614650,
      payloadId: '6201274638',
      transactionHash: '0x0bd1961ba478aae4d64ecb6b4d45fcd0edc76249bdcf7ef0d6feb0b4b1080591'
    },
    AnchorTransaction {
      createdAt: 1599612789,
      payloadId: '5273394532',
      transactionHash: '0xd3b5de1c8e15be76491fffa58c241b292a714df91d611a26811bc0df906390b5'
    }
  ]
}

class AnchorTransactions {
    cursor: eyJjcmVhdGVkX2F0IjoxNTk4MzQ1ODYxLCJkb2NfaWQiOiJrcm46MTAwMTphbmNob3I6ZDVjMzQ2ZjUtYmI4MC00ZjQ1LTkwOTMtNTdlMjUyMDVjZGM4Om9wZXJhdG9yLXBvb2w6ZGVmYXVsdDoweDBFYTU2M0E4MGY1ZWEyMkMxNzQwMzA0MTZFN2ZDZGJlRDkyMEQ1RUI6Y3VzdG9tX2lkMTExMTE0IiwicXVlcnlfaWQiOiJrcm46MTAwMTphbmNob3I6ZDVjMzQ2ZjUtYmI4MC00ZjQ1LTkwOTMtNTdlMjUyMDVjZGM4Om9wZXJhdG9yLXBvb2w6ZGVmYXVsdDpBTkNIX1RYOjB4MEVhNTYzQTgwZjVlYTIyQzE3NDAzMDQxNkU3ZkNkYmVEOTIwRDVFQiIsInR5cGUiOiJBTkNIX1RYIn0=
    items: [class AnchorTransaction {
        createdAt: 1598345953
        payloadId: 77777
        transactionHash: 0xf2777b31f99d268eecc356409a45b2bf916cc63d629f270f21b3e197bc11e851
    }, class AnchorTransaction {
        createdAt: 1598345931
        payloadId: custom_id111115
        transactionHash: 0x534e9b6e40c483d5eec379a6bd034726daf78acb7d000b15c975606c5a7ad113
    }, class AnchorTransaction {
        createdAt: 1598345861
        payloadId: custom_id111114
        transactionHash: 0xb976f868b4b5f1208a24d783603ddb784d91d72b9643ddd64ded1e8444175dc3
    }]
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum. ㅏ

Get Anchoring Transaction Information By Transaction Hash and Operator Address

You can use the transaction hash and operator address to search for payload details of anchoring transactions.

API Request

Call the Anchoring Transaction Details Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/tx/0xf7db6019fcb9621ed01baf7d27d2f8cfd58b9aa24e5a1e73276ed84e254b54c0" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"

const result = await caver.kas.anchor.getAnchoringTransactionByTxHash('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f')

String operatorID = "0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB";
String txHash = "0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de";

AnchorTransactionDetail res = caver.kas.anchor.getAnchoringTransactionByTxHash(operatorID, txHash);
System.out.println(res);

API Response

Here is the response of the Anchoring Transaction Payload Details Search API.

{
  "payload": {
    "customField1": "field1",
    "customField2": "field2",
    "id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
  },
  "transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}

AnchorBlockTransactions {
  payload: { 
    custom_field: 'This is test custom field for anchoring',
    id: '891825'
  },
  transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}

class AnchorTransactionDetail {
    payload: class AnchorBlockPayload {
        {filed2=4.0, field=1}
    }
    transactionHash: 0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

Get Payload by Operator Address and Payload ID

You can use the payload ID and operator address to search for the payload details of anchoring transactions.

API Request

Call the Anchoring Transaction Details Search API. You may use the REST API or KAS SDKs (caver-js, caver-java extensions) for this.

curl --location --request GET "https://anchor-api.klaytnapi.com/v1/operator/0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026/payload/c61cc0d0-5878-450e-bec8-bf73d6184798" \
-u {access-key-id}:{secret-access-key} \
--header "x-chain-id: {chain-id}"

const result = await caver.kas.anchor.getAnchoringTransactionByPayloadId('0xc8Aa073E2A924Fc469339Ff0cB2Ec4A7838888D0', '891825')

String operatorID = "0x0Ea563A80f5ea22C174030416E7fCdbeD920D5EB";
String payloadId = "0xca0577c2f7f2537d499357c2bd08c72a808d7bb718a336b69fd37f640c73ba6d";

AnchorTransactionDetail res = caver.kas.anchor.getAnchoringTransactionByPayloadId(operatorID, payloadId);

API Response

Here is the response of the Anchoring Transaction Payload Details Search API.

{
  "payload": {
    "customField1": "field1",
    "customField2": "field2",
    "id": "c61cc0d0-5878-450e-bec8-bf73d6184798"
  },
  "transactionHash": "0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d"
}

AnchorBlockTransactions {
  payload: { 
    custom_field: 'This is test custom field for anchoring',
    id: '891825'
  },
  transactionHash: '0x9b67fb089d942af13db118932d62a605371978df754d1a97807df305d6a1a08f'
}

class AnchorTransactionDetail {
    payload: class AnchorBlockPayload {
        {filed2=4.0, field=1}
    }
    transactionHash: 0x74ee2fcf41b7bee3cb6ff0e9d5facb877cf9da178236d5ccc371318cbf09d6de
}

For details about this API, please visit here. For inquires about this document or KAS, please visit KAS Developer forum.

PreviousNFT Ownership NextKAS BApp Examples

Last updated 2 years ago