Native Assets Service - API¶

This document describes using the service as an API. Working knowledge of gRpc is assumed.

Service API¶

This is a partial listing of the NativeAssetsService (v0.3.19)

service NativeAssetsService {
  rpc importPolicy(ImportPolicyRequest) returns (ImportPolicyResponse);
  rpc createPolicy(CreatePolicyRequest) returns (CreatePolicyResponse);
  rpc getPolicy(GetPolicyRequest) returns (GetPolicyResponse);
  rpc listPolicies(ListPoliciesRequest) returns (ListPoliciesResponse);
  rpc deletePolicy(DeletePolicyRequest) returns (DeletePolicyResponse);

  rpc createNativeAsset(CreateNativeAssetRequest) returns (CreateNativeAssetResponse);
  rpc getNativeAsset(GetNativeAssetRequest) returns (GetNativeAssetResponse);
  rpc listNativeAssets(ListNativeAssetsRequest) returns (ListNativeAssetsResponse);
  rpc deleteNativeAsset(DeleteNativeAssetRequest) returns (DeleteNativeAssetResponse);

  rpc mintNativeAsset(MintNativeAssetRequest) returns (stream MintNativeAssetResponse);
  rpc mintNativeAssetWithArbitraryMetadata(MintNativeAssetWithArbitraryMetadataRequest) returns (stream MintNativeAssetResponse);
  rpc transferNativeAsset(TransferNativeAssetRequest) returns (stream TransferNativeAssetResponse);
  rpc burnNativeAsset(BurnNativeAssetRequest) returns (stream BurnNativeAssetResponse);

  rpc sendAirDropBatch(AirDropBatchRequest) returns (AirDropBatchResponse);
  rpc getAirDropStatus(AirDropStatusRequest) returns (AirDropStatusResponse);
}

Create Policy¶

message CreatePolicyRequest {
  string name = 1;
  TimeBounds timeBounds = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
}


message CreatePolicyResponse {
  oneof result {
    AppError problem = 1;
    Policy policy = 2;
  }
}

To create policy the caller provides:

name (unique name of the policy)
timeBounds (time bounds for a policy to be created. Consists of two parts: before and after)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return a new Policy object. In the case of a problem, that problem is described in the problem field of the response.`

Get Policy¶

message GetPolicyRequest {
  string policyId = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message GetPolicyResponse {
  oneof result {
    AppError problem = 1;
    Policy policy = 2;
  }
}

To get policy the caller provides:

policyId (unique id of the policy)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return a new Policy object. In the case of a problem, that problem is described in the problem field of the response.`

List Policies¶

message ListPoliciesRequest {
  iog.psg.service.common.CredentialsMessage credentials = 1;
}

message ListPoliciesResponse {
  AppError problem = 1;
  repeated Policy policies = 2;
}

To get the list of policies the caller provides:

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return the list of created Policy objects.

Delete Policy¶

message DeletePolicyRequest {
  string policyId = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message DeletePolicyResponse {
  AppError problem = 1;
}

To delete policy the caller provides:

policyId (unique id of the policy)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of a problem, that problem is described in the problem field of the response.`

Import Policy¶

message ImportPolicyRequest {
  string name = 1;
  string policyAsString = 2;
  Key policyKey = 3;
  repeated Key moreKeys = 4;
  iog.psg.service.common.CredentialsMessage credentials = 5;
}

message ImportPolicyResponse {
  oneof result {
    AppError problem = 1;
    NativeAssetId assetId = 2;
  }
}

To create policy the caller provides:

name (unique name of the policy)
policyAsString (policy in the form of JSON) JSON structure:

{
 "type": "all",
 "scripts":
 [{
  "keyHash": "d4e661ba09d5748c794b012512ab64d07d347d97fe668f2da01d3b5f",
  "type": "sig"
 }]
}

policyKey (verification and signing keys for the policy)

message Key {
  string verificationKey = 1;
  string signingKey = 2;
}

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return a new NativeAssetId object.

message NativeAssetId {
  string name = 1;
  string policyId = 2;
}

In the case of a problem, that problem is described in the problem field of the response.`

Create Asset¶

message CreateNativeAssetRequest {
  NativeAssetId id = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message CreateNativeAssetResponse {
  oneof result {
    AppError problem = 1;
    NativeAsset asset = 2;
  }
}

To create an asset the caller provides:

id (unique asset name and policy id)

message NativeAssetId {
  string name = 1;
  string policyId = 2;
}

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return a new NativeAsset object.

message NativeAsset {
  NativeAssetId id = 1;
  uint64 amount = 2;
}

In the case of a problem, that problem is described in the problem field of the response.`

Get Asset¶

message GetNativeAssetRequest {
  NativeAssetId id = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message GetNativeAssetResponse {
  oneof result {
    AppError problem = 1;
    NativeAsset asset = 2;
  }
}

To get an asset the caller provides:

nativeAssetId (native asset name and policy id)

message NativeAssetId {
  string name = 1;
  string policyId = 2;
}

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return a new NativeAsset object.

message NativeAsset {
  NativeAssetId id = 1;
  uint64 amount = 2;
}

In the case of a problem, that problem is described in the problem field of the response.`

List Assets¶

message ListNativeAssetsRequest {
  string policyId = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message ListNativeAssetsResponse {
  AppError problem = 1;
  repeated NativeAsset assets = 2;
}

To get the list of policies the caller provides:

policyId (unique policyId)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of success the call will return the list of created NativeAsset objects.

Delete Asset¶

message DeleteNativeAssetRequest {
  NativeAssetId id = 1;
  iog.psg.service.common.CredentialsMessage credentials = 2;
}

message DeleteNativeAssetResponse {
  AppError problem = 1;
}

To delete policy the caller provides:

nativeAssetId (asset name and policy id)

message NativeAssetId {
  string name = 1;
  string policyId = 2;
}

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide

In the case of a problem, that problem is described in the problem field of the response.`

Mint Native Asset¶

message MintNativeAssetRequest {
  NativeAssetId id = 1;
  uint64 amount = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
  repeated Nft nfts = 4;
  uint32 depth = 5;
}
message MintNativeAssetWithArbitraryMetadataRequest {
  NativeAssetId id = 1;
  uint64 amount = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
  google.protobuf.Struct metadata = 4;
  uint32 depth = 5;
}

To mint native asset the caller provides:

nativeAssetId (asset name and policy id)
amount (amount of native asset tokens to mint)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
nfts (optional list of Nft objects to create)

message Nft {
  string assetName = 1;
  string name = 2;
  repeated string image = 3;
  string mediaType = 4;
  repeated string description = 5;
  repeated NftFile files = 6;
}

message NftFile {
  string name = 1;
  string mediaType = 2;
  repeated string src = 3;
}

depth (The value on how many blocks after transaction we need to wait until consider operation successful. Default value is 3)

The result will be a stream of NativeAssetTransaction.

message NativeAssetTransaction {
  NativeAsset asset = 1;
  TxInfo txInfo = 2;
}

message TxInfo {
  string txId = 1;
  BlockInfo block = 2;
}

message BlockInfo {
  uint32 epochNumber = 1;
  uint32 number = 2;
  string hash = 3;
  uint64 height = 4;
}

In the case of a problem, that problem is described in the problem field of the response.`

Mint Native Asset with Arbitrary Metadata¶

message MintNativeAssetWithArbitraryMetadataRequest {
  NativeAssetId id = 1;
  uint64 amount = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
  google.protobuf.Struct metadata = 4;
  uint32 depth = 5;
}

message MintNativeAssetResponse {
  oneof result {
    AppError problem = 1;
    NativeAssetTransaction assetTx = 2;
  }
}

To mint native asset the caller provides:

nativeAssetId (asset name and policy id)
amount (amount of native asset tokens to mint)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
metadata (free form JSON metadata for an asset)
depth (The value on how many blocks after transaction we need to wait until consider operation successful. Default value is 3)

The result will be a stream of NativeAssetTransaction.

message NativeAssetTransaction {
  NativeAsset asset = 1;
  TxInfo txInfo = 2;
}

message TxInfo {
  string txId = 1;
  BlockInfo block = 2;
}

message BlockInfo {
  uint32 epochNumber = 1;
  uint32 number = 2;
  string hash = 3;
  uint64 height = 4;
}

In the case of a problem, that problem is described in the problem field of the response.

Transfer Native Asset¶

message TransferNativeAssetRequest {
  NativeAssetId id = 1;
  uint64 amount = 2;
  string toAddress = 3;
  iog.psg.service.common.CredentialsMessage credentials = 4;
  uint32 depth = 5;
}

message TransferNativeAssetResponse {
  oneof result {
    AppError problem = 1;
    NativeAssetTransaction assetTx = 2;
  }
}

To transfer native asset the caller provides:

nativeAssetId (asset object that contains asset name and policy id)
amount (the amount of native asset tokens to transfer)
toAddress (the address on Cardano blockchain to transfer tokens to)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
depth (The value on how many blocks after transaction we need to wait until consider operation successful. Default value is 3)

The result will be a stream of NativeAssetTransactions.

message NativeAssetTransaction {
  NativeAsset asset = 1;
  TxInfo txInfo = 2;
}

In the case of a problem, that problem is described in the problem field of the response. `

Burn Native Asset¶

message BurnNativeAssetRequest {
  NativeAssetId id = 1;
  uint64 amount = 2;
  iog.psg.service.common.CredentialsMessage credentials = 3;
  uint32 depth = 4;
}

message BurnNativeAssetResponse {
  oneof result {
    AppError problem = 1;
    NativeAssetTransaction assetTx = 2;
  }
}

To burn native asset the caller provides:

nativeAssetId (asset object that contains asset name and policy id)
amount (the amount of native asset tokens to burn)
credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
depth (The value on how many blocks after transaction we need to wait until consider operation successful. Default value is 3)

The result will be a stream of NativeAssetTransactions.

message NativeAssetTransaction {
  NativeAsset asset = 1;
  TxInfo txInfo = 2;
}

In the case of a problem, that problem is described in the problem field of the response.

Send Airdrop Batch¶

message AirDropBatchRequest {
  iog.psg.service.common.CredentialsMessage credentials = 1;
  repeated AirDrop airdrops  = 2;
  google.protobuf.Struct metadata = 3;
}

message AirDropBatchResponse {
  oneof result {
    AppError problem = 1;
    string batchId = 2;
  }
}

To send an airdrop batch the caller provides:

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
airdrop (list of airdrops to send)

message AirDrop {
  string address = 1;
  string policyId = 2;
  string assetName = 3;
  uint64 amountToAirDrop = 4;
  string result = 5;
}

metadata (free form JSON metadata for an asset)

The result will be a unique id of the batch. In the case of a problem, that problem is described in the problem field of the response.

Get Airdrop Status¶

message AirDropStatusRequest {
  iog.psg.service.common.CredentialsMessage credentials = 1;
  string batchId = 2;
}

message AirDropStatusResponse {
  enum Status {
    PENDING = 0;
    RUNNING = 1;
    FINISHED = 2;
  }
  oneof result {
    AppError problem = 1;
    Status status = 2;
    AirDropResults airDropResults = 3;
  }
}

To get the batch status the caller provides:

credentials (these are the credentials generated by the PSG Services Self Serve UI after the user has created a “log in” and paid for use of the services.) new_user_guide
batchId (unique id of the batch)
metadata (free form JSON metadata for an asset)

The result will be a batch status as well as the list of processed airdrops. Batch status can be PENDING, RUNNING and FINISHED. Airdrop result can be either successful or failed. In the case of a problem, that problem is described in the problem field of the response.