Dev:API - Assets

From Nexus Wiki
Jump to navigation Jump to search

An asset is a user-defined data structure or NFT that is stored in a register, owned by a given profile. Assets can hold one or more pieces of data and users can define the fields (name, data, type, mutability) that data is stored in.

Supported Nouns

The following nouns are supported for this API command-set:

Noun Description
any Any asset, raw, or readonly register
asset An editable register with type safety
raw An editable register without type safety
readonly A non-editable register without type safety
schema An asset template for user-defined standards

Example

You can include more than one noun for a command if you separate them by a comma. The following command will return all the assets of type asset, raw, and readonly that the session profile owns.

assets/list/asset,raw,readonly

Supported Verbs

The following verbs are currently supported by this command-set:

Verb Description Nouns
claim Claim ownership of a register any, asset, raw, readonly
create Generate a register of specified type asset, raw, readonly, schema
get Get register of supported type any, asset, raw, readonly, schema
history Generate the history of all last states any, asset, raw, readonly, schema
list List all registers owned by active session any, asset, raw, readonly, partial, schema
tokenize To represent ownership of an asset object with a token object asset
transactions List all transactions that modified specified object any, asset, raw, readonly, schema
transfer Transfer a specified register any, asset, raw, readonly
update Update a specified object any, asset, raw, readonly, schema
verify Verify if a given register has been tokenized partial

Example

The following will show you how to invoke a basic <verb>/<noun> URI. This will return all the assets of type any that the session profile owns.

assets/list/any

Supported Operators

The following verbs are currently supported by this command-set:

Operator Description
array Returns an array of values from the filtered data-set
count Returns the total number of occurrences of a value in the filtered data-set
floor Strips the decimal off of a value or array of values
max Returns the largest value in the filtered data-set
mean Returns the average value of the filtered data-set
min Returns the smallest value in the filtered data-set
mode Returns the most occurring value in the filtered data-set
sum Returns the sum of all the values in the filtered data-set

Example

The following will show you how to invoke a basic <verb>/<noun>/<field>/<operator> URI. This will calculate the average value of the modified field for all assets owned by active session:

assets/list/any/modified/mean

Supported Formats

When creating or modifying a register, a format is required to encode the operations to the given register. The following formats are supported for this command-set:

Format Description
readonly Takes string argument data=, creates raw state
raw Takes string argument data=, creates or updates raw state
basic Takes all additional string arguments as key=value, updates or creates fields of object with string type
json akes string argument json=<json>, updates or creates fields of object for any type and mutability

Please see the Formats page to learn how to use the above formats in more details.

Verbs

claim

This method will claim ownership of the asset to complete the corresponding transfer transaction.

assets/claim/noun

This command supports the asset, raw and readonly nouns.

Parameters

Name Description Required
name Allows the user to rename an item when it is claimed. By default the name is copied from the previous owner and a Name record is created for the item in your user namespace. If you already have an object for this name then you will need to provide a new name in order for the claim to succeed. no
pin PIN for this profile. Required if locked.
session User session ID Required if argument -multiuser=1 is set
txid the transaction ID (hash) of the asset transfer transaction for which is being claimed. yes

Return Values

Name Description
success Boolean flag indicating whether the asset claim was successful.
txid The ID (hash) of the transaction that includes the claimed asset.

Example Response JSON

{
  "success": true,
  "txid": "01f35304d41d00b002ca02d3bd9cf6cfeb134f5c454d4b6f5a355e35ffc557cfb3756834f3cf5cbeaf98da6773adcaaeca80154d15e449d4876ddf35c0b895cf"
}

create

Create a new object register specified by given noun.

assets/create/noun

The supported nouns for this command are asset, raw, readonly, and schema.

NOTE: There is a limit of 1KB for asset data to be saved in the register, excluding the asset name. There is a fee of 1 NXS for creating and an asset and an additional 1 NXS for the optional name object.

Parameters

If any of the required parameters are not set, the command will fail with an error response designating the missing parameters.

Name Description Required
format Required to identify the format used to define the asset. Values can be readonly, raw, basic and JSON. yes
name A UTF-8 encoded string that will generate a name object register that points to new object. This will cost an additional 1 NXS if on the mainnet. no
pin This is the PIN that was used when creating master profile. Required if not unlocked for transactions
session User session ID Required if argument -multiuser=1 is set

Return Values

Name Description
address The register address for the register that was just created.
success Boolean flag indicating whether the asset was created successfully.
txid The hash of the transaction that was generated for this tx.

Example Response JSON

The following object will be returned under the JSON object results if the command succeeded:

{
  "success": true,
  "address": "87VmNhitFJv3WA3Yrovt9A3hts2MoXcfExyy9LiXyhK1sdThwYM",
  "txid": "01230bbc8f0d72aaaff13471e34520d17902290de9a1e5ce1f320f0883024e2d96e21b59a3e48b8d2b5ba2874e93d5d3b4f412e06dc92440c2e12682c958fe34"
}

get

Retrieves information for an asset and returns a JSON structured object with the fields. You must choose the correct noun in order to have command execute.

assets/get/noun

The supported nouns for this command are any, asset, raw, readonly, or schema. If you are unsure of the correct noun then you can use the any keyword, or aggregate nouns using the comma as separator.

Parameters

If any of the required parameters are not set, the command will fail with an error response designating the missing parameters.

Name Description Required
address register address of the asset Required if name is not provided
name In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. Required if address is not provided
pin This is the PIN that was used when creating master profile. Required if not unlocked for transactions
session User session ID Required if argument -multiuser=1 is set

Return Values

Name Description
address The register address that is currently assigned to given asset.
created The UNIX timestamp when the asset was created.
data If the register is raw or readonly the raw data will be returned under this key.
<key>=<value> If the register is asset or schema it will return the fields as key/value pairs.
modified The UNIX timestamp when the asset was last modified.
name The name that is currently pointed to the given register, if any are assigned.
owner The username hash of the owners profile.
type Asset register type. Can be OBJECT, RAW or READONLY.
version The serialization version of the transaction.

Example Response JSON

[
  {
    "owner": "b7392196b83aca438567558462cd0c5d982569c7cefa668500c4bf3e61a03b7a",
    "version": 1,
    "created": 1655279431,
    "modified": 1655279431,
    "type": "OBJECT",
    "Location": "Meta World ",
    "Owner Name": "John Doe",
    "Registration Details": "MRG/05/478564",
    "address": "87Wai2JoS4hNAEVXZVmejLS6pK21XQWKoLAkaep5aXFdrYnJJyk",
    "name": ":Meta_World"
  }
]

history

This will get the history of changes to an asset, including both the data and it's ownership.

assets/history/noun

This command supports the asset, raw, readonly and any nouns.

Parameters

Name Description Required
address register address of the asset Required if name is not provided
name Name of the asset in the format username:name (for local names) or namespace::name (for names in a namespace). Required if address is not provided
session User session ID Required if argument -multiuser=1 is set

Return Values

Name Description
action MODIFY | TRANSFER | CLAIM.
address The register address of the asset.
created The UNIX timestamp when the asset was created.
data The data stored in a raw or readonly asset object.
<key>=<value> If format is basic, then the caller can provide additional = pairs for each piece of data to store in the asset.
modified The UNIX timestamp when the asset was last modified.
name The name that is currently pointed to the given register, if any are assigned.
owner The username hash of the owner profile.
type Asset register type. Can be OBJECT, RAW or READONLY.
version The serialization version of the transaction.

Example Response JSON

[
  {
    "owner": "b7a57ddfb001d5d83ab5b25c0eaa0521e6b367784a30025114d07c444aa455c0",
    "version": 1,
    "created": 1656614448,
    "modified": 1656614448,
    "type": "OBJECT",
    "Assetname": "Bugatti Veyron",
    "Chassis_No": "BV45648784634546",
    "Purchased Date": "22/06/2022",
    "Engine_No": "BVE54864660",
    "Owner": "John Doe",
    "Registration_No": "DL01EK0001",
    "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi",
    "name": "local:Asset0001",
    "action": "CREATE"
  }
]

list

Retrieves a list of all the asset objects owned by the profile specified by the noun.

assets/list/noun

This command supports the any, asset, list, partial, raw, and readonly nouns. The partial noun lists partial ownership details for tokenized assets.

Parameters

Name Description Required
session User session ID Required if argument -multiuser=1 is set
where An array of clauses to filter the JSON results. More information can be found on Queries page. no

Return Values

Name Description
address The register address of the asset.
created The UNIX timestamp when the asset was created.
data The data stored in a raw or readonly asset object.
<key>=<value> The key-value pair for each piece of data stored in the asset.
modified The UNIX timestamp when the asset was last modified.
name The name that is currently pointed to the given register, if any are assigned.
owner The username hash of the owner profile.
type Asset register type. Can be OBJECT, RAW or READONLY.
version The serialization version of the transaction.

Example Response JSON

[
  {
    "owner": "b7392196b83aca438567558462cd0c5d982569c7cefa668500c4bf3e61a03b7a",
    "version": 1,
    "created": 1655279431,
    "modified": 1655279431,
    "type": "OBJECT",
    "Location": "Margoa",
    "Owner Name": "Ageon",
    "Registration Details": "MRG/05/478564",
    "address": "87Wai2JoS4hNAEVXZVmejLS6pK21XQWKoLAkaep5aXFdrYnJJyk",
    "name": "local:Asset2"
  }
]

tokenize

This method will tokenize an asset into fungible tokens that represent ownership:

assets/tokenize/noun

This command only supports the asset noun.

NOTE: Create the token before using tokenize.

Parameters

Name Description Required
address register address of the asset to be tokenised Required if name is not provided
name Name of the asset to be tokenised in the format username:name (for local names) or namespace::name (for names in a namespace). Required if address is not provided
pin PIN for this profile. Required if locked.
session User session ID Required if argument -multiuser=1 is set
token Required to identify the token to tokenize the asset. It can be the name (for global names) username:tokenname ( for local names) or the register address of the token.

Return Values

Name Description
success Boolean flag indicating whether the asset tokenization was successful.
txid The ID (hash) of the transaction that includes the asset.

Example Response JSON

{
  "success": true,
  "txid": "01f35304d41d00b002ca02d3bd9cf6cfeb134f5c454d4b6f5a355e35ffc557cfb3756834f3cf5cbeaf98da6773adcaaeca80154d15e449d4876ddf35c0b895cf"
}

transactions

This will list off all of the transactions for the specified noun.

assets/transactions/noun

This command supports all nouns.

Parameters

Name Description Required
address register address of the asset Required if name is not provided
name In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. Required if address is not provided
session User session ID Required if argument -multiuser=1 is set
verbose determines the transaction data included in the response. Supported values are default, summary, and detail. no

Return Values

Name Description
blockhash The hash of the block that this transaction is included in. Blank if not yet included in a block.
confirmations The number of confirmations that this transaction obtained by the network.
contracts Described in the contracts table below.
sequence The sequence number of this transaction within the signature chain.
timestamp The Unix timestamp of when the transaction was created.
txid The transaction ID hash of the transaction for the credit/claim.
type tritium base | trust | genesis | user)
version The serialization version of the transaction.
contracts
Name Description
address The register address of the asset object.
contract Contract ID within the transaction for the credit/claim.
id The sequential ID of this contract within the transaction.
<key>=<value> The key-value pair for each piece of data stored in the asset.
object The data stored in the asset.
OP MODIFY | TRANSFER | CLAIM.
recipient The transfer recipient's profile username hash.
standard The type of object. Can be NONSTANDARD or JSON.
tokenized Boolean flag indicating if the asset is tokenized or not.
txid The transaction ID hash of the transaction for the credit/claim.
type The type of register. Can be OBJECT, RAW or READONLY.

Example Response JSON

[
  {
    "txid": "0167d11ebea68f68e2c6591a9d94c236a60c312cf70d596492002a3e4d9a95a4f4e859c498fa6ac17c56cb4db1043abacdfd44f669112641fc4add15bb3efefa",
    "type": "tritium user",
    "version": 4,
    "sequence": 4,
    "timestamp": 1656614805,
    "blockhash": "9b2c063b2e8766ce9b55c5b75524b13c12c7006e0c67423dbfe1539ed4f62cd0c764f63fbbc6cb41ab9fc785ce6f88ae92e6a82e3151c4c956fa65eac524db3e1922bdced7bdd4cd97a4563dd21f011a310d062440300b2a7532fe21f6df55c7e3ba9046a982b99af97acddd768569d3cf5368cb91dcb0138cf5af7f1a6f391b",
    "confirmations": 95,
    "contracts": [
      {
        "id": 0,
        "OP": "TRANSFER",
        "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi",
        "recipient": "8Dnn5LUeffcRCqZLpboCHnzw5AkfwzkM5hjVScjSDHVKhFpVzCB",
        "tokenized": true
      }
    ]
  },
  {
    "txid": "01e4eff49cadbd887511c6302d5fe8e89ead4caa87bcec2dfd55e18cb201a8fc8db9726571d3bebe554a81f579b22e2794a0e86756be326f362964e95ab28f23",
    "type": "tritium user",
    "version": 4,
    "sequence": 2,
    "timestamp": 1656614448,
    "blockhash": "e9b46f5dcf3c321f8a2dc672a6c47a5c6b763bc9d1f001722bc446b186afda3566f04cc739253696a3f232e036bc273ca68c18d84213186a1317d246ec86a165ba152838a2eca4425c19472dc8fb1b762f4413c5a633c4fef5494378b9858da34129dcd5bc556110c1e79aa42f01f8bae6f4938a6e87a63b6d30e2ee6025d507",
    "confirmations": 97,
    "contracts": [
      {
        "id": 0,
        "OP": "CREATE",
        "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi",
        "type": "OBJECT",
        "standard": "NONSTANDARD",
        "object": {
          "Assetname": " Bugatti Veyron",
          "Chassis_No": "BV45648784634546",
          "Purchased Date": "22/06/2022",
          "Engine_No": "BVE54864660",
          "Owner": "John Doe",
          "Registration_No": "DL01EK0001"
        }
      }
    ]
  }
]

transfer

This will initiate ownership transfer of the specified noun:

assets/transfer/noun

This command supports the asset, raw and readonly nouns.

Parameters

Name Description Required
address Register address of the asset Required if name is not provided
expires Number of seconds until the transaction can no longer be claimed by the recipient no
name In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. Required if address is not provided
pin PIN for this profile. Required if locked.
recipient The profile username or genesis hash of the recipient account
session User session ID Required if argument -multiuser=1 is set

Return Values

Name Description
address Register address of the asset
success Boolean flag indicating whether the asset transfer was successful.
txid The ID (hash) of the transaction that includes the asset transfer.

Example Response JSON

{
  "success": true,
  "address": "87VmNhitFJv3WA3Yrovt9A3hts2MoXcfExyy9LiXyhK1sdThwYM",
  "txid": "01bc48f80792fd4b97d43555d5993f0edfb0998ab14bcf159404f52e34a64abd6769f61014f006703100aa040a27aca65227133b2b5a71617efac3bc5640e361"
}

update

This method provides the user with the ability to update the object data specified by the noun:

assets/update/noun

This command only supports the asset and raw nouns.

Parameters

Name Description Required
address Register address of the asset Required if name is not provided
data input for the data object Required if format is readonly or raw
format Format of the asset to update. Values can be readonly, raw, basic and JSON. yes
<key>=<value> 'key=value' pairs to update each piece of data for the asset for format basic no
name In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. Required if address is not provided
pin PIN for this profile. Required if locked.
session User session ID Required if argument -multiuser=1 is set

Return Values

Name Description
success Boolean flag indicating whether the asset was saved successfullly.
txid The ID (hash) of the transaction that includes the asset transfer.

Example Response JSON

{
  "success": true,
  "txid": "01bc48f80792fd4b97d43555d5993f0edfb0998ab14bcf159404f52e34a64abd6769f61014f006703100aa040a27aca65227133b2b5a71617efac3bc5640e361"
}

verify

Verify if a given register has been tokenized.

assets/verify/partial

This command only supports the partial noun.