Scenario | Pirichain API

Get scenario

post

/getScenario

This endpoint returns information about a scenario created on the PIRI network. It takes the scenario address as a parameter, and this address also serves as a PIRI address.

A scenario also functions as a wallet. The scenario itself can have its own assets, and transfers of these assets can be made within the scenario based on integrated code.

Before creating a scenario, it's advisable to refer to the relevant guidelines in the following links:

https://piriscan.com/scenarios
https://whitepaper.pirichain.com/v1.0.3/pirichain-smart-scenario/pirichain-smart-scenario

Looking at the information returned by this endpoint, we have:

countOfExecution: Stores how many times this scenario has been executed.
address: The scenario's address.
ownerAddress: Information about the address that created the scenario.
name: The descriptive name of the scenario.
description: Contains descriptions related to the scenario.
tags: Tags created for the scenario.
createDate: The creation date of the scenario.
validated: Information about whether the scenario has been validated by other nodes.
scenarioText: The JavaScript code associated with the scenario.
byteCode: Bytecode equivalent of the scenarioText.

The list of functions related to the scenario can be extracted and read from scenarioText using the JSON.parse method.

Since the scenarios and their structures may vary from system to system, the security of scenarios should be carefully reviewed, rigorously tested, and then published.

Body

addressstringRequired

Scenario Address | It is aslo a PIRI Address

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

byteCodestringRequired

post

/getScenario

POST /getScenario HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 18

"address='text'"

200

OK

{
  "error": 0,
  "data": {
    "countOfExecution": 170,
    "_id": "64d7a7b5599032859f7ab571",
    "address": "PRTMPKQF8LJMEYgn3KcnW6CcHYnZ4q2whLFDfgg4pX4",
    "ownerAddress": "PRTMRKWZ56v4D8mV1oj813bqTgdfUm9J4woVTDMpGxF",
    "name": "final deposit and withdraw swap scenario",
    "description": "final deposit and withdraw swap scenario",
    "tags": "final deposit and withdraw swap scenario",
    "createdDate": "2023-08-12T15:39:33.321Z",
    "validated": 0,
    "scenarioText": "//####PIRICHAIN Smart Scenario v.1.0########\n// PiriChain Smart Scenario Code Blocks Area \n\n // All Functions must be return promise non-blocking async block or await prefix delimitier..  \n\nasync function depositLiqudity(ratio)\n{....",
    "__v": 0
  },
  "byteCode": "002f002..."
}

Create scenario

post

/createScenario

This endpoint allows you to create a Smart Scenario within the PIRI network. PIRIchain Smart Scenarios are permanent pieces of code that automate tasks within the system. They are immutable and cannot be modified.

To code Smart Scenarios, you can use either JavaScript or TypeScript. For more detailed explanations and information about PIRIchain Smart Scenarios, you can access the following links:

https://piriscan.com/scenarios
https://whitepaper.pirichain.com/v1.0.3/pirichain-smart-scenario/pirichain-smart-scenario

Body

addressstringRequired

Owner PIRI Address

privateKeystringRequired

Private Key

executeOnlyByMebooleanOptional

To Execution Restriction by Owner

Default: false

scenarioTextstringRequired

Scenario Codes in Javascript | Typescript

namestringRequired

Scenario name

descriptionstringRequired

Scenario description

tagsstringRequired

Scenario Tags

Responses

200

OK

application/json; charset=utf-8

countOfExecutioninteger · int32Required

Number of times this scenario has been executed.

_idstringRequired

Unique database identifier for the created scenario.

addressstringRequired

The blockchain address assigned to this scenario.

ownerAddressstringRequired

The PIRI address of the scenario owner/creator.

namestringRequired

The name given to the scenario.

descriptionstringRequired

Description of what the scenario does.

tagsstringRequired

Tags associated with the scenario for categorization.

createdDatestring · date-timeRequired

ISO 8601 timestamp when the scenario was created.

validatedinteger · int32Required

Validation status of the scenario. 0 = not validated, 1 = validated.

scenarioTextstringRequired

The actual scenario code (JavaScript/TypeScript) that was submitted.

__vinteger · int32Required

Version key used by MongoDB for document versioning.

post

/createScenario

POST /createScenario HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 133

"address='text'&privateKey='text'&executeOnlyByMe=false&scenarioText='text'&name='text'&description='text'&tags='text'"

200

OK

{
  "countOfExecution": 0,
  "_id": "12345678901234567890abcd",
  "address": "PRTMExampleScenarioAddress1234567890",
  "ownerAddress": "PRTMExampleOwnerAddress1234567890abcd",
  "name": "Example Scenario",
  "description": "This is an example scenario description.",
  "tags": "['Example', 'Demo', 'Test']",
  "createdDate": "2024-08-22T10:00:00.000Z",
  "validated": 0,
  "scenarioText": "async function init(param1, param2, param3) { return 'example'; }",
  "__v": 0
}

List my scenarios

post

/listMyScenarios

This endpoint lists the smart scenarios on the PIRI network associated with the PIRI address provided as a parameter (ownerAddress parameter). The schema returned with "getScenario" is now presented as an array within the "data" this time.

Body

ownerAddressstringRequired

PIRI Address where scenarios will be listed

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

post

/listMyScenarios

POST /listMyScenarios HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 23

"ownerAddress='text'"

200

OK

{
  "error": 0,
  "data": [
    {
      "countOfExecution": 0,
      "_id": "632b10e81ca0c3ae24ebe5b7",
      "address": "PRTMPGC6pVU8sZFWK9CS5ZrnCzCBUfDEdrPfYMKoRAS",
      "ownerAddress": "PRTMR5pDravSYmAdohUNSoGoEgwyEg2mG8xbWuAfb47",
      "name": "Test",
      "description": "This is test description.",
      "tags": "['Business', 'Development', 'Schedule', 'RSS Feed', 'Lab Study']",
      "createdDate": "2022-09-21T13:26:00.454Z",
      "validated": 0,
      "scenarioText": "002f002f002...",
      "__v": 0
    }
  ]
}

List scenarios

post

/listScenarios

This endpoint lists all smart scenarios in the PIRI network. It takes "skip" and "limit" as parameters. The use of these parameters is recommended for pagination.

Body

skipinteger · int32Optional

Number of records to skip for pagination

limitinteger · int32Optional

Maximum number of records to return

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

countinteger · int32Required

post

/listScenarios

POST /listScenarios HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 20

"skip=1&limit=1"

200

OK

{
  "error": 0,
  "data": [
    {
      "countOfExecution": 0,
      "_id": "632b10e81ca0c3ae24ebe5b7",
      "address": "PRTMPGC6pVU8sZFWK9CS5ZrnCzCBUfDEdrPfYMKoRAS",
      "ownerAddress": "PRTMR5pDravSYmAdohUNSoGoEgwyEg2mG8xbWuAfb47",
      "name": "Test",
      "description": "This is test description.",
      "tags": "['Business', 'Development', 'Schedule', 'RSS Feed', 'Lab Study']",
      "createdDate": "2022-09-21T13:26:00.454Z",
      "validated": 0,
      "scenarioText": "002f002f00230...",
      "__v": 0
    }
  ],
  "count": 1
}

Call scenario

post

/callScenario

Execute a read-only call to a scenario method without making changes to the blockchain

Body

scenarioAddressstringRequired

The address of the scenario to call

publicKeystringRequired

Public key of the caller

addressstringRequired

Address of the caller

methodstringRequired

Method name to call in the scenario

paramsstringRequired

Parameters to pass to the method

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

Error status code. 0 indicates success, non-zero indicates an error.

post

/callScenario

POST /callScenario HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 94

"scenarioAddress='text'&publicKey='text'&address='text'&method='text'&params='text'"

200

OK

{
  "error": 0,
  "data": {
    "result": "success",
    "gasUsed": 1500,
    "executionTime": 25
  }
}

Execute scenario

post

/executeScenario

This endpoint allows the execution of an intelligent scenario within the PIRI network. The result to be returned after the execution of the scenario may differ from the template specified below. This is because each scenario may have its own output structure.

After running the scenario, it may not produce any output or may generate parameters for another scenario. Therefore, it is beneficial to have information about the scenario before running it. These include:

Who created the scenario?
Description of the scenario
List of functions associated with the scenario
Descriptions of the expected outputs at the end of the scenario
Whether malicious code is used within the scenario
What information the scenario carries
Whether the scenario was created by a Domain Verified PIRI Address (DVPA).

Body

scenarioAddressstringRequired

Scenario Address | It is aslo a PIRI Address

addressstringRequired

Executer PIRI Address

privateKeystringRequired

Private Key

methodstringRequired

The method to be run in the scenario

paramsstring[]Optional

Parameters | e.g.: ["value1", "value2", ...]

amountnumberOptional

Amount to send Token to Scenario Address

assetIDstringOptional

Asset ID to send Token to Scenario Address

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

Error status code. 0 indicates success, non-zero indicates an error.

post

/executeScenario

POST /executeScenario HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 125

"scenarioAddress='text'&address='text'&privateKey='text'&method='text'&params=['text']&amount=1&assetID='text'"

200

OK

{
  "error": 0,
  "returnedData": [
    "Example Result"
  ]
}

Preview scenario

post

/previewScenario

This endpoint is built on the principle of executing before saving to the PIRI network for a scenario. Unlike the "executeScenario" endpoint, it focuses on temporarily running specified functions within the provided code.

In other words:

It is common for scenario authors to execute it.
It may be used to execute changes on a previously saved scenario.
It can be used to test the security of a scenario.

While alternative usage methods not covered in these examples may exist, it is advisable to refer to the "executeScenario" section for considerations before testing a scenario.

Body

scenarioTextstringRequired

Scenario Text | Javascript or Typescript Code

addressstringRequired

Executer PIRI Address

privateKeystringRequired

Private Key

methodstringRequired

The method to be run in the scenario

paramsstring[]Optional

Parameters | e.g.: ["value1", "value2", ...]

Responses

200

OK

application/json; charset=utf-8

errorinteger · int32Required

Error code (0 for success)

returnedDataany ofRequired

Returned data from scenario execution - can be any type

stringOptional

or

numberOptional

or

objectOptional

or

arrayOptional

or

booleanOptional

post

/previewScenario

POST /previewScenario HTTP/1.1
Host: core.pirichain.com
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 94

"scenarioText='text'&address='text'&privateKey='text'&method='text'&params=['text']"

200

OK

{
  "error": 0,
  "returnedData": [
    "AHMET"
  ]
}

hashtagGet scenario

hashtagCreate scenario

hashtagList my scenarios

hashtagList scenarios

hashtagCall scenario

hashtagExecute scenario

hashtagPreview scenario

Get scenario

Create scenario

List my scenarios

List scenarios

Call scenario

Execute scenario

Preview scenario