Smart Contracts

Vendia Share makes it easy to share data and files among participants in a Uni. But sometimes sharing data alone isn't enough. Smart Contracts allow users to take action on data in a prescribed way, as data changes across a Uni, without having to build or maintain a complex eventing infrastructure.

Smart contracts can be used for various purposes. Examples of smart contract usage include:

• Integrity Constraints: Smart contracts can be used to enforce restrictions or limitations, such as ensuring that the balance across several related accounts never drops below a minimum threshold or ensuring that two flight segments aren't booked closer together than 45 minutes between the arrival of the first and the departure of the second. Making this calculation a smart contract ensures that the data in the Uni can adhere to policy constraints, regardless of its provenance. Participants don't have to just trust that other participants "got it right" when they updated one or more values over time.

• Derived (Computed) Values: Smart contracts can also be used to create data values that are derived from other information. For example, a Uni may be used to store sales information, in which case a smart contract can be used to accurately calculate sales tax and the total amount, rather than requiring every node to maintain a redundant implementation of the tax calculation.

• Third-party System Integration: Because a smart contract can be any code that the parties in the Uni agree is legitimate to use for their shared purposes, it can do things like contact third party systems, retrieve information stored outside the Uni, etc. Smart contracts can also be used to update third-party systems based on the data in the Uni.

When to Use Smart Contracts

Not all data actions need to be captured in a smart contract. The following questions can help determine if a smart contract is indicated:

• Does the action affect the data in the Uni?: If the goal is to add computed values, enforce Uni-wide constraints, or act on behalf of all participants, then a smart contract is likely to be required.

• Is the result of the action stored in the Uni?: If a computation's output is used to update or add to the Uni's data, then a smart contract may be appropriate.

Comparison to Ethereum Smart Contracts

If you are more familiar with Ethereum Smart Contracts there are some key differences and similarities between the two that are important to understand.

What is in a Vendia Smart Contract?

A Vendia Smart Contract contains the following fields:

How Vendia Smart Contracts Work

On many blockchain platforms, smart contracts have to be executed by all nodes in parallel - a costly and redundant approach. Vendia only requires executing a smart contract once, which also frees developers from having to ensure that the code in the contract is idempotent and replayable. This allows for freedom of language choice: On Vendia, smart contracts can be written in literally any language (though sticking to one of the built-in ones does make things a little simpler). Vendia permits flexible use of non-idempotent calculations, including random number generators, time of date, arbitrary API calls, and more. Not all Unis and participants may elect to support those features in the smart contracts they use, but they're available if desired.

Vendia Share expresses smart contracts as AWS Lambda functions. Importantly, these functions must be versioned. Versioning a Lambda function makes it immutable - not even the owner of the function can change its code or configuration. This immutability allows the function to be executed with cross-participant trust, because the function has the same "meaning" regardless of who its owner might be.

Vendia Share executes a smart contract in several steps:

1. Create the input payload from world state. When a smart contract is invoked, an invoke payload is generated by combining the results of static invoke arguments with the results from running the inputQuery defined on the Vendia Smart Contract. See The Invoke Payload for more details.

2. The Lambda function representing the contract is invoked, using the values generated in step one as the arguments.

3. The result of the function is captured and one or more GraphQL mutations are used to update the Uni with the function's outputs. If the function fails, a special status mutation is used to record that fact instead of updating the Uni with the function's result.

The values passed to a function are computed in the same block in which the smart contract invocation is processed. However, since functions can run for up to 14 minutes, transaction processing does not wait for contracts to complete. The results of a contract will be applied asynchronously, once they become available.

Versioning

Smart contracts have two modes of versioning. The first type uses Vendia’s standard object versioning. Whenever any field of a smart contract is updated, the version number will increment by one, and a version update is recorded. Retrieving specific versions of a function can be done buy using the getVendia_Contract API and passing in the version you want.

The second versioning schema happens less frequently, updating of the revisionId. The revisionId tracks any changes to three properties of a smart contract object that change the underlying behavior of what a smart contract does. These fields are inputQuery, outputMutation, and resource.uri. When calling the invokeVendia_Contract API with a specific revisionId parameter, you are guaranteed to be running an immutable grouping of (inputQuery, outputMutation, resource.uri) is the exact properties of the Smart Contract.

Vendia Smart Contract Function Deployment and Permissions

The Lambda function supporting a smart contract is a customer-owned resource. As such it is deployed to an AWS Account outside of Vendia. This allows you to retain complete control over the function configuration, code, versioning, and permissions.

So that Vendia can securely invoke your lambda function you will need to set up a resource policy on your Lambda function. The specific permissions you will need to grant are lambda:GetFunctionConfiguration and lambda:InvokeFunction. The former permissions are used to get the Lambda function's metadata for validating it passes Share's requirements, while the latter is required to invoke the Lambda function itself.

To ensure that Lambda function has not changed between smart contract invocations we do not support $LATEST. This means you will need need to utilize lambda versioning. For each new Lambda version that is created, you need to explicitly need re-attach the resource policies that are defined below. AWS does not carry over the the resource policies from $LATEST to your new version. As such, you will also need to ensure that :<version> is appended onto the end of each lambda arn. e.g. arn:aws:lambda:us-east-2:123456789012:function:my-function:1

Determining the Vendia Smart Contract Role

To ensure only your node can invoke your Vendia Smart Contract, a special AWS role is created per-node that is used to retrieve metadata and invoke your Vendia Smart Contract's resource. To find this role, you can use either the UI or the share CLI.

Share CLI

share uni get --uni <name-of-uni>

share uni get --uni loonies-twonies.unis.vendia.net

Current logged in user "user@domain.com".
Getting loonies-twonies.unis.vendia.net info...
┌─────────────────────┐
│   Uni Information   │
└─────────────────────┘
Uni Name:    loonies-twonies.unis.vendia.net
Uni Status:  RUNNING
Node Count:  1
Node Info:
└─ ⬢ NodeOne
   ├─ name: NodeOne
   ├─ status: RUNNING
   └─ resources:
      ├─ graphqlApi
      │  ├─ httpsUrl https://some-url.com/graphql/
      │  ├─ apiKey MY_API_KY
      │  └─ websocketUrl wss://some-url.com/graphql
      ├─ smartContracts
      │  └─ aws_Role arn:aws:iam::123456789012:role/loonies-twonies_NodeOne_0e4e6c4cf9d7ed_SmartContractRole
      ├─ aws_AsyncIngressQueue
      │  ├─ url https://sqs.us-west-2.amazonaws.com/1234567889012/ingressQ_loonies-twonies_NodeOne
      │  └─ name ingressQ_loonies-twonies_NodeOne
      ├─ aws_FileStorage
      │  ├─ arn arn:aws:s3:::loonies-twonies-1-nodeone-some-bucket
      │  └─ name loonies-twonies-1-nodeone-some-bucket
      ├─ aws_BlockNotifications
      │  └─ arn arn:aws:sns:us-west-2:123456789012:loonies-twonies-1-NodeOne-BlockTopicSOME_ID
      ├─ aws_DeadLetterNotifications
      │  └─ arn arn:aws:sns:us-west-2:123456789012:loonies-twonies-1-NodeOne-DeadLetterTopicSOME_ID
      └─ aws_Cognito
         ├─ userPoolId null
         ├─ userPoolClientId null
         └─ identityPoolId null

share uni get --uni loonies-twonies.unis.vendia.net --json | jq '.nodes[] | { "node_name": .name, "smart_contract_role_arn": .resources.smartContracts.aws_Role }'

{
  "node_name": "NodeOne",
  "smart_contract_role_arn": "loonies-twonies_NodeOne_0e4e6c4cf9d7ed_SmartContractRole"
}

Share UI

Select the node where you are going to create the Vendia Smart Contract, and the Smart Contract Role should be visible under the resources section.

Adding the Permissions

The fastest way to add the required permissions for your AWS Lambda function is via the AWS CLI. The following code block provides an example of the CLI commands necessary.

aws lambda add-permission --region <lambda-function-region> --function-name <your-lambda-resource-arn> --action lambda:InvokeFunction --statement-id AllowVendiaInvokeFunction --principal <smart-contract-role-arn>

aws lambda add-permission --region <lambda-function-region> --function-name <your-lambda-resource-arn> --action lambda:GetFunctionConfiguration --statement-id AllowVendiaGetFunctionConfiguration --principal <smart-contract-role-arn>

For example, if your AWS Lambda function arn is arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:1 and the Vendia Smart Contract role arn is arn:aws:iam::102930495678:role/loonies-twonie_NodeOne_6f87c1fc2943bf_SmartContractRole, your commands would be:

aws lambda add-permission --region us-west-2 --function-name arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:1 --action lambda:InvokeFunction --statement-id AllowVendiaInvokeFunction --principal arn:aws:iam::102930495678:role/loonies-twonie_NodeOne_6f87c1fc2943bf_SmartContractRole

aws lambda add-permission --region us-west-2 --function-name arn:aws:lambda:us-west-2:123456789012:function:my-lambda-function:1 --action lambda:GetFunctionConfiguration --statement-id AllowVendiaGetFunctionConfiguration --principal arn:aws:iam::102930495678:role/loonies-twonie_NodeOne_6f87c1fc2943bf_SmartContractRole

Invoking the Vendia Smart Contract

To invoke a Vendia Smart Contract, you use the invokeVendia_Contract_async API.

Invoking specific revisionIds

For Vendia Smart Contracts, the node that created the Smart Contract can invoke any revisionId. All other nodes in the Uni are only able to invoke the latest revisionId on the Smart Contract.

A Vendia Smart Contract Example

Building on the inventory track and trace quickstart, smart contracts can be used to check external systems before marking a shipment as delivered. The "Orders" and "Shipments" data models both have a delivered(boolean) property but instead of directly mutating that state, the delivering party can use a smart contract to create a confirmation step for the recipient before a delivered=True state is written to the world state.

A smart contract can be used to check with off-chain systems before putting the data into the ledger permanently. Before introducing our contract we can take a look at the state of the world:

query Statuses {
  list_WarehouseItems {
    Warehouse {
      city
      code
      companyName
    }
  }
  list_ShipmentItems {
    Shipment {
      created
      delivered
      destinationWarehouse
      lastUpdated
      id
      location
      orderId
      originWarehouse
    }
  }
  list_OrderItems {
    Order {
      delivered
      retailerWarehouseCode
      manufacturerWarehouseCode
      orderId
    }
  }
}

First, we create the smart contract with the below mutation that retrieves the order information for a specific shipment and then updates the status of the delivery using the result of the backing resource. Let's break down how that works!

• inputQuery defines a query where we retrieve the up-to-date data about a specific shipment.
• resource.uri points at the lambda function version, in this example arn:aws:lambda:us-west-2:123456789012:function:ContractEnforcement:9, will be passed the result of the inputQuery. The function could be querying a separate backend API to retrieve the order status of the shipment.
• outputMutation defines a mutation that should be run where the inputs come from the result of the resource function. This mutation updates the world state to mark the shipment's delivery status

mutation createConfirmDeliveryContract {
  addVendia_Contract(
    input: {
      name: "update-delivery-status",
      resource: { uri: "arn:aws:lambda:us-west-2:123456789012:function:ContractEnforcement:9" }, 
      description: "a smart contract that updates the delivery status of a shipment",
      inputQuery: "query shipmentDetails($id: ID!) { getShipment(id: $id) { _id orderId destinationWarehouse }}" 
      outputMutation: "mutation m($id: ID!, $delivered: Boolean, $lastUpdated: String, $orderId: String) { updateShipment(id: $id, input: { delivered: $delivered, lastUpdated: $lastUpdated, orderId: $orderId }, syncMode: ASYNC) { transaction { _id } } }" 
    },
    syncMode: ASYNC
  ) {
  transaction {
    _id
    _owner
    transactionId
    version
    submissionTime
    }
  }
}

Once the function is created, we will want to invoke it! We can do this for a specific shipment by using the invokeVendia_Contract_async api. In the following example, we are invoking the Vendia Smart Contract we create above in a node named "MyTestNode", and running it on the shipment id a-very-real-shipment-id.

mutation invokeSmartContract {
  invokeVendia_Contract_async(
    input: {
      id: "vrn:MyTestNode:smart-contract:update-delivery-status",
      input: {
        queryArgs: "{\"id\": \"a-very-real-shipment-id\"}",
      }
    }
  ) {
    result {
      _id
      _owner
      submission_time
      transactionId
    }
  }
}

When invoked, the backing Lambda function will receive a JSON payload containing the result of running your inputQuery, any static arguments passed in the invokeArgs field, and an invocationId. For our example, the inputQuery returns the details of a specific shipment.

{
  "queryResults": {
    "shipmentDetails": {
      "_id": "a-very-real-shipment-id",
      "orderId": "order782",
      "destinationWarehouse": "SEA-52"
    }
  },
  "invokeArgs": {},
  "invocationId": "01FPES7CKM6EEEW2F8B155K0TK"
}

This is passed to the backing Lambda function, where the business logic begins to run. Below, we are taking the incoming shipment details stored in the Uni, reaching out to an external API, and returning the status of the delivery.

import json
from datetime import datetime, timezone

def _get_status_of_delivery(order_id: str, warehouse_id: str) -> bool:
  """Get the delivery status of an order"""

  # Here, we can reach out to a backend database or API, get the delivery status, and return the result
  return True

def lambda_handler(event, context):
    # printing out the event is useful for development, but you may not want to
    # do this for customer data
    print(json.dumps(event, sort_keys=True))
    # read the incoming arguments to get information about the order
    shipment_details = event["queryResults"]["shipmentDetails"]

    warehouse_id = shipment_details.get("_id")
    order_id = shipment_details.get('orderId')

    delivery_received = _get_status_of_delivery(warehouse_id, order_id)

    return {
        "id": warehouse_id,
        "delivered": delivery_received,
        "lastUpdated": datetime.now(timezone=timezone.utc).isoformat(),
        "orderId": order_id,
    }

Once the function returns, the response of the Lambda function is passed in as is to the outputMutation mutation as variables (see Graphql Variable definitions for more on how variables work with GraphQL mutations).

The call to the smart contract and the mutation result will be saved to the ledger, making it easy to resolve any future disputes and audit the usage of the smart contract. Supporting Lambda execution makes it easy to integrate any external system into your Uni's consensus process and leave a trail of decisions auditable by any node.

Smart Contract Reference

Schema

For reference, here is the full JSON schema for a contract expression. This can also be reviewed in GraphQL format from your node's GraphQL Explorer.

"Contract": {
  "description": "Smart Contracts",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "pattern": "[a-zA-Z0-9\\-_\\.]+"
      },
      "description": {
        "type": "string",
        "maxLength": 256
      },
      "revisionId": {
        "type": "string",
        "readOnly": true
      },
      "resource": {
        "type": "object",
        "properties": {
          "uri": {
            "type": "string"
          },
          "csp": {
            "type": "string",
            "enum": [
              "aws"
            ],
            "readOnly": true
          },
          "metadata": {
            "type": "array",
            "readOnly": true,
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          }
        },
        "required": [
          "uri"
        ]
      },
      "inputQuery": {
        "type": "string"
      },
      "outputMutation": {
        "type": "string"
      }
    },
    "required": [
      "name",
      "resource",
      "outputMutation"
    ]
  },
  "uniqueItems": true
}

Vendia Smart Contract APIs

Mutations

Add

addVendia_Contract(
  input: {
    name: String!,
    description: String,
    inputQuery: String,
    outputMutation: String!,
    resource: {uri: String!}
  },
  aclInput: Vendia_Acls_Input_,
  syncMode: Vendia_SyncMode
) {
  transaction {
    _id
    _owner
    submissionTime
    transactionId
    version
  }
 result {
    _id
    _owner     
    name
    description
    inputQuery
    outputMutation
    resource
 }
}

Update

updateVendia_Contract(id: ID!
  input: {
    description: String,
    inputQuery: String,
    outputMutation: String,
    resource: {uri: String}
  },
  aclInput: Vendia_Acls_Input_,
  syncMode: Vendia_SyncMode
) {
  transaction {
    _id
    _owner
    submissionTime
    transactionId
    version
  }
 result {
    _id
    _owner     
    name
    description
    inputQuery
    outputMutation
    resource
 }
}

Remove

removeVendia_Contract(id: ID!
  condition: Vendia_Contract_ConditionInput_,
  syncMode: Vendia_SyncMode
) {
  transaction {
    _id
    _owner
    submissionTime
    transactionId
    version
  }
}

Invoke

invokeVendia_Contract_async(id: ID!
  revisionId: String,
  input: {
    invocationId: String,
    queryArgs: String,
    invokeArgs: String
  }
) {
  result {
    _id
    _owner
    submissionTime
    transactionId
    version
  }
  error
}

Queries

Get

getVendia_Contract(id: ID!, version: int) {
  Vendia_Contract_PartialUnion
}

List Contracts

listVendia_ContractItems(filter: Vendia_Contract_FilterInput_, limit: int, nextToken: String) {
  [Vendia_Contract_PartialUnion]
  nextToken
}

List Contract Versions

listVendia_ContractVersions(id: ID!, filter: Vendia_Contract_FilterInput_, limit: int, nextToken: String) {
  Vendia_Version
  nextToken
}

Limits