# Scenario

Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section.

## Get scenario

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/getScenario":{"post":{"tags":["Scenario"],"summary":"Get scenario","description":"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.\n\nA 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.\n\nBefore creating a scenario, it's advisable to refer to the relevant guidelines in the following links:\n- https://piriscan.com/scenarios\n- https://whitepaper.pirichain.com/v1.0.3/pirichain-smart-scenario/pirichain-smart-scenario\n\nLooking at the information returned by this endpoint, we have:\n- **countOfExecution**: Stores how many times this scenario has been executed.\n- **address**: The scenario's address.\n- **ownerAddress**: Information about the address that created the scenario.\n- **name**: The descriptive name of the scenario.\n- **description**: Contains descriptions related to the scenario.\n- **tags**: Tags created for the scenario.\n- **createDate**: The creation date of the scenario.\n- **validated**: Information about whether the scenario has been validated by other nodes.\n- **scenarioText**: The JavaScript code associated with the scenario.\n- **byteCode**: Bytecode equivalent of the scenarioText.\n\nThe list of functions related to the scenario can be extracted and read from scenarioText using the JSON.parse method.\n\nSince the scenarios and their structures may vary from system to system, the security of scenarios should be carefully reviewed, rigorously tested, and then published.","operationId":"getScenario","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["address"],"type":"object","properties":{"address":{"type":"string","description":"Scenario Address | It is aslo a PIRI Address"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/getScenario"}}}}},"deprecated":false}}},"components":{"schemas":{"getScenario":{"title":"getScenario","required":["error","data","byteCode"],"type":"object","properties":{"error":{"type":"integer","format":"int32"},"data":{"$ref":"#/components/schemas/ScenarioData"},"byteCode":{"type":"string"}}},"ScenarioData":{"title":"ScenarioData","required":["countOfExecution","_id","address","ownerAddress","name","description","tags","createdDate","validated","scenarioText","__v"],"type":"object","properties":{"countOfExecution":{"type":"integer","format":"int32"},"_id":{"type":"string"},"address":{"type":"string"},"ownerAddress":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"createdDate":{"type":"string"},"validated":{"type":"integer","format":"int32"},"scenarioText":{"type":"string"},"__v":{"type":"integer","format":"int32"}}}}}}
```

## Create scenario

> 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>

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/createScenario":{"post":{"tags":["Scenario"],"summary":"Create scenario","description":"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.\n\nTo 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:\n- https://piriscan.com/scenarios\n- https://whitepaper.pirichain.com/v1.0.3/pirichain-smart-scenario/pirichain-smart-scenario","operationId":"createScenario","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["address","privateKey","scenarioText","name","description","tags"],"type":"object","properties":{"address":{"type":"string","description":"Owner PIRI Address"},"privateKey":{"type":"string","description":"Private Key"},"executeOnlyByMe":{"type":"boolean","default":false,"description":"To Execution Restriction by Owner"},"scenarioText":{"type":"string","description":"Scenario Codes in Javascript | Typescript"},"name":{"type":"string","description":"Scenario name"},"description":{"type":"string","description":"Scenario description"},"tags":{"type":"string","description":"Scenario Tags"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/createScenario"}}}}},"deprecated":false}}},"components":{"schemas":{"createScenario":{"required":["countOfExecution","_id","address","ownerAddress","name","description","tags","createdDate","validated","scenarioText","__v"],"type":"object","properties":{"countOfExecution":{"type":"integer","format":"int32","description":"Number of times this scenario has been executed."},"_id":{"type":"string","description":"Unique database identifier for the created scenario."},"address":{"type":"string","description":"The blockchain address assigned to this scenario."},"ownerAddress":{"type":"string","description":"The PIRI address of the scenario owner/creator."},"name":{"type":"string","description":"The name given to the scenario."},"description":{"type":"string","description":"Description of what the scenario does."},"tags":{"type":"string","description":"Tags associated with the scenario for categorization."},"createdDate":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when the scenario was created."},"validated":{"type":"integer","format":"int32","description":"Validation status of the scenario. 0 = not validated, 1 = validated."},"scenarioText":{"type":"string","description":"The actual scenario code (JavaScript/TypeScript) that was submitted."},"__v":{"type":"integer","format":"int32","description":"Version key used by MongoDB for document versioning."}}}}}}
```

## List my scenarios

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/listMyScenarios":{"post":{"tags":["Scenario"],"summary":"List my scenarios","description":"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.","operationId":"listMyScenarios","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["ownerAddress"],"type":"object","properties":{"ownerAddress":{"type":"string","description":"PIRI Address where scenarios will be listed"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/listMyScenarios"}}}}},"deprecated":false}}},"components":{"schemas":{"listMyScenarios":{"title":"listMyScenarios","required":["error","data"],"type":"object","properties":{"error":{"type":"integer","format":"int32"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ScenarioInfo"},"description":""}}},"ScenarioInfo":{"title":"ScenarioInfo","required":["countOfExecution","_id","address","ownerAddress","name","description","tags","createdDate","validated","scenarioText","__v"],"type":"object","properties":{"countOfExecution":{"type":"integer","format":"int32"},"_id":{"type":"string"},"address":{"type":"string"},"ownerAddress":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"createdDate":{"type":"string"},"validated":{"type":"integer","format":"int32"},"scenarioText":{"type":"string"},"__v":{"type":"integer","format":"int32"}}}}}}
```

## List scenarios

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/listScenarios":{"post":{"tags":["Scenario"],"summary":"List scenarios","description":"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.","operationId":"listScenarios","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"type":"object","properties":{"skip":{"type":"integer","format":"int32","description":"Number of records to skip for pagination"},"limit":{"type":"integer","format":"int32","description":"Maximum number of records to return"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/listScenarios"}}}}},"deprecated":false}}},"components":{"schemas":{"listScenarios":{"title":"listScenarios","required":["error","data","count"],"type":"object","properties":{"error":{"type":"integer","format":"int32"},"data":{"type":"array","items":{"$ref":"#/components/schemas/ScenarioInfo"},"description":""},"count":{"type":"integer","format":"int32"}}},"ScenarioInfo":{"title":"ScenarioInfo","required":["countOfExecution","_id","address","ownerAddress","name","description","tags","createdDate","validated","scenarioText","__v"],"type":"object","properties":{"countOfExecution":{"type":"integer","format":"int32"},"_id":{"type":"string"},"address":{"type":"string"},"ownerAddress":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"tags":{"type":"string"},"createdDate":{"type":"string"},"validated":{"type":"integer","format":"int32"},"scenarioText":{"type":"string"},"__v":{"type":"integer","format":"int32"}}}}}}
```

## Call scenario

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

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/callScenario":{"post":{"tags":["Scenario"],"summary":"Call scenario","description":"Execute a read-only call to a scenario method without making changes to the blockchain","operationId":"callScenario","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["scenarioAddress","publicKey","address","method","params"],"type":"object","properties":{"scenarioAddress":{"type":"string","description":"The address of the scenario to call"},"publicKey":{"type":"string","description":"Public key of the caller"},"address":{"type":"string","description":"Address of the caller"},"method":{"type":"string","description":"Method name to call in the scenario"},"params":{"type":"string","description":"Parameters to pass to the method"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/callScenario"}}}}},"deprecated":false}}},"components":{"schemas":{"callScenario":{"required":["error","data"],"type":"object","properties":{"error":{"type":"integer","format":"int32","description":"Error status code. 0 indicates success, non-zero indicates an error."},"data":{"$ref":"#/components/schemas/ScenarioCallResult"}}},"ScenarioCallResult":{"required":["result","gasUsed","executionTime"],"type":"object","properties":{"result":{"type":"string","description":"The result returned by the scenario method call."},"gasUsed":{"type":"number","description":"The amount of gas consumed during the scenario execution."},"executionTime":{"type":"number","description":"The time taken to execute the scenario method in milliseconds."}}}}}}
```

## Execute scenario

> 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).

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/executeScenario":{"post":{"tags":["Scenario"],"summary":"Execute scenario","description":"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.\n\nAfter 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:\n- Who created the scenario?\n- Description of the scenario\n- List of functions associated with the scenario\n- Descriptions of the expected outputs at the end of the scenario\n- Whether malicious code is used within the scenario\n- What information the scenario carries\n- Whether the scenario was created by a Domain Verified PIRI Address (DVPA).","operationId":"executeScenario","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["scenarioAddress","address","privateKey","method"],"type":"object","properties":{"scenarioAddress":{"type":"string","description":"Scenario Address | It is aslo a PIRI Address"},"address":{"type":"string","description":"Executer PIRI Address"},"privateKey":{"type":"string","description":"Private Key"},"method":{"type":"string","description":"The method to be run in the scenario"},"params":{"type":"array","items":{"type":"string"},"description":"Parameters | e.g.: [\"value1\", \"value2\", ...]"},"amount":{"type":"number","description":"Amount to send Token to Scenario Address"},"assetID":{"type":"string","description":"Asset ID to send Token to Scenario Address"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/executeScenario"}}}}},"deprecated":false}}},"components":{"schemas":{"executeScenario":{"required":["error","returnedData"],"type":"object","properties":{"error":{"type":"integer","format":"int32","description":"Error status code. 0 indicates success, non-zero indicates an error."},"returnedData":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object"},{"type":"boolean"}]},"description":"The data returned by the executed scenario method. Structure depends on the specific scenario implementation."}}}}}}
```

## Preview scenario

> 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.

```json
{"openapi":"3.0.3","info":{"title":"Pirichain API","version":"1.1.0"},"tags":[{"name":"Scenario","description":"Scenario commands allows executing all modifiable actions by implementer. Before use the scenarios, please be sure than you informed and and fee results. All Scenario commands are below and also explained on their section."}],"servers":[{"url":"https://core.pirichain.com","description":"Pirichain MainNet","variables":{}},{"url":"https://testnet.pirichain.com","description":"Pirichain TestNet","variables":{}},{"url":"https://{URL}","description":"You can only use https protocol for your custom environment.","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}},{"url":"http://{URL}","description":"Custom HTTP endpoint for development environment (not recommended for production).","variables":{"URL":{"default":"custom.network","description":"You can enter your custom endpoint which belong to Pirichain Network"}}}],"paths":{"/previewScenario":{"post":{"tags":["Scenario"],"summary":"Preview scenario","description":"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.\n\nIn other words:\n- It is common for scenario authors to execute it.\n- It may be used to execute changes on a previously saved scenario.\n- It can be used to test the security of a scenario.\n\nWhile 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.","operationId":"previewScenario","requestBody":{"content":{"application/x-www-form-urlencoded":{"encoding":{},"schema":{"required":["scenarioText","address","privateKey","method"],"type":"object","properties":{"scenarioText":{"type":"string","description":"Scenario Text | Javascript or Typescript Code"},"address":{"type":"string","description":"Executer PIRI Address"},"privateKey":{"type":"string","description":"Private Key"},"method":{"type":"string","description":"The method to be run in the scenario"},"params":{"type":"array","items":{"type":"string"},"description":"Parameters | e.g.: [\"value1\", \"value2\", ...]"}}}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json; charset=utf-8":{"schema":{"$ref":"#/components/schemas/previewScenario"}}}}},"deprecated":false}}},"components":{"schemas":{"previewScenario":{"title":"previewScenario","required":["error","returnedData"],"type":"object","properties":{"error":{"type":"integer","format":"int32","description":"Error code (0 for success)"},"returnedData":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"object"},{"type":"array"},{"type":"boolean"}],"description":"Returned data from scenario execution - can be any type"}}}}}}
```