External invocations

A new need has arisen: the certification of the organic origin of wine. To carry out this task, a laboratory will need to visit our lands or vineyards and conduct a series of analyses and tests that will determine whether the wine’s origin is organic or not. However, there are many companies that offer this service, and it’s not efficient to incorporate all of them into the governance or require them to have their own node.

To solve this problem, we will use a new function of kore called external invocations. To perform these invocations on the network, it’s not necessary to have a complete node; it will be enough to have access to one of the existing nodes and have a pair of keys that allow us to sign the request to certify the invocation’s identity.

To achieve this update, modifications will be made to the roles within the governance properties. First, let’s review its current state:

The change we want to make will apply to the roles section and will be as follows:

{
    "roles": [

        ...

        {
            "namespace": "",
            "role": "ISSUER",
            "schema": {
                "ID": "Wine"
            },
            "who": "NOT_MEMBERS"
        }
    ]
}

We’ll use our kore-Patch tool to generate these changes, following the procedure below:

kore-patch '{"roles":[{"namespace":"","role":"WITNESS","schema":{"ID":"governance"},"who":"MEMBERS"},{"namespace":"","role":"APPROVER","schema":{"ID":"governance"},"who":{"NAME":"WPO"}},{"namespace":"","role":"CREATOR","schema":{"ID":"Wine"},"who":{"NAME":"PremiumWines"}},{"namespace":"","role":"APPROVER","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"VALIDATOR","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"EVALUATOR","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"WITNESS","schema":{"ID":"Wine"},"who":{"NAME":"WFO"}}]}' '{"roles":[{"namespace":"","role":"WITNESS","schema":{"ID":"governance"},"who":"MEMBERS"},{"namespace":"","role":"APPROVER","schema":{"ID":"governance"},"who":{"NAME":"WPO"}},{"namespace":"","role":"CREATOR","schema":{"ID":"Wine"},"who":{"NAME":"PremiumWines"}},{"namespace":"","role":"APPROVER","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"VALIDATOR","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"EVALUATOR","schema":{"ID":"governance"},"who":{"NAME":"WFO"}},{"namespace":"","role":"WITNESS","schema":{"ID":"Wine"},"who":{"NAME":"WFO"}},{"namespace":"","role":"ISSUER","schema":{"ID":"Wine"},"who":"NOT_MEMBERS"}]}'

Once the process is completed, we’ll get the following result:

[
    {
        "op": "add",
        "path": "/roles/7",
        "value": {
            "namespace": "",
            "role": "ISSUER",
            "schema": {
                "ID": "Wine"
            },
            "who": "NOT_MEMBERS"
        }
    }
]

Next, we’ll proceed to invoke the method of the governance contract responsible for updating its properties. To do this, we’ll execute the following:

curl --request POST 'http://localhost:3000/event-requests' \
--header 'Content-Type: application/json' \
--data-raw '{
    "request": {
        "Fact": {
            "subject_id": "{{GOVERNANCE-ID}}",
            "payload": {
                "Patch": {
                    "data": [{
                        "op": "add",
                        "path": "/roles/7",
                        "value": {
                            "namespace": "",
                            "role": "ISSUER",
                            "schema": {
                                "ID": "Wine"
                            },
                            "who": "NOT_MEMBERS"
                        }
                    }]
                }
            }
        }
    }
}'

After submitting the governance update request, we need to obtain an approval request again:

curl --request GET 'http://localhost:3000/approval-requests?status=Pending'

We’ll copy the value of the id field. However, this time, approval from WFO is also required. Therefore, we’ll perform the following two actions:

curl --request PATCH 'http://localhost:3000/approval-requests/{{PREVIUS-ID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"state": "RespondedAccepted"}'

curl --request PATCH 'http://localhost:3002/approval-requests/{{PREVIUS-ID}}' \
--header 'Content-Type: application/json' \
--data-raw '{"state": "RespondedAccepted"}'

With all these actions, upon querying our governance once more, the new corresponding version should appear:

curl --silent --request GET 'http://localhost:3002/subjects?subject_type=governances'

Now, we’ll proceed to test the external executions. To do this, we’ll generate the signature of the event we want to emit using kore-Sign with the following command. Replace subject_id with the identifier of our Wine subject:

kore-sign 'f855c6736463a65f515afe7b85d1418c096ed73852b42bbe4c332eb43d532326' '{"Fact":{"subject_id":"{{SUBJECT-ID}}","payload":{"OrganicCertification":{"fertilizers_control":true,"pesticides_control":true,"analytics":true,"additional_info":"test"}}}}'

The result of this execution will be included in the following request:

curl --request POST 'http://localhost:3001/event-requests' \
--header 'Content-Type: application/json' \
--data-raw '{
    "request": {
        "Fact": {
            "subject_id": "{{SUBJECT-ID}}",
            "payload": {
                "OrganicCertification": {
                "additional_info": "test",
                "analytics": true,
                "fertilizers_control": true,
                "pesticides_control": true
                }
            }
        }
    },
    "signature": {
        "signer": "EzzmRjc8CtjzHu3MKmuTgnmOTgrJlYZj1D2DCZ9nN7Vk",
        "timestamp": 1689842680899014786,
        "value": "SEE-Mx-t9xXHCy6SPllVADy3-LrWk91N6btpAPFGAqi8eie3kAF4Q0WokMtt0Z_A7gIeik7b_64R_asyTavsL4Dg"
    }
}'

If everything has gone correctly, running the following command should update the subject with an sn value of 2 and reflect the changes mentioned above:

curl --request GET 'http://localhost:3001/subjects/{{SUBJECT-ID}}'

{
    "subject_id": "{{SUBJECT-ID}}",
    "governance_id": "{{GOVERNANCE-ID}}",
    "sn": 2,
    "public_key": "E-_PigfpbWeFsQzMXENgEQPQR5ea4FfoSFAqdZtx7lS0",
    "namespace": "",
    "name": "Wine",
    "schema_id": "Wine",
    "owner": "{{CONTROLLER-ID}}",
    "creator": "{{CONTROLLER-ID}}",
    "properties": {
        "grape": "CabernetSauvignon",
        "harvest": 1,
        "organic_certified": true,
        "origin": "spain",
        "temperature_control": {
            "last_check": 0,
            "temperature_ok": true
        }
    },
    "active": true
}
Last modified: June 6, 2024