Uploading Smart Contracts for Grid on Splinter
This procedure summarizes how to use the scabbard
command-line interface to
package a compiled smart contract with a manifest, create a contract registry,
upload the smart contract to a Splinter circuit, and configure the contract
registry and namespace.
The examples in this procedure use the sawtooth_xo
smart contract, which
allows users to play a distributed game of tic-tac-toe, storing player data and
game moves in shared state. For information about writing and compiling new
smart contracts, see the Sabre
documentation.
Prerequisites
-
Two or more working Grid nodes. (See Running Grid on Splinter for the procedure to set up and run Grid in Docker containers.) This procedure assumes that there are two nodes,
alpha-node-000
andbeta-node-000
, running in a Docker environment. -
An approved Splinter circuit with two or more member nodes. (See Creating Splinter Circuits for more information.) This procedure assumes that there is a circuit with
alpha-node-000
andbeta-node-000
as members. -
A fully qualified service ID for the scabbard service on this circuit, in the format
CircuitID::ServiceString
. (See Determine the Service ID for the commands to display this information.) This procedure uses the example ID01234-ABCDE::gsAA
. -
The endpoint for the Splinter (
splinterd
) REST API. This example useshttp://splinterd-alpha:8085
. -
The public/private key pair for the smart contract owner. This example assumes that Grid daemon (
gridd
) will be the smart contract owner and will sign transactions with a private key in/root/.splinter/keys/gridd.priv
. -
A smart contract that has been compiled to WASM (as described in the Sabre Application Developer’s Guide. This example uses the
sawtooth_xo
smart contract that is already packaged in a smart contract archive (scar) file.
Important Notes
The examples in this procedure use the node hostnames, container names, node
IDs, and URLs that are defined in the example docker-compose file,
examples/splinter/docker-compose.yaml
. If you are not using this example
environment, replace these items with the actual values for your nodes.
Procedure
Package the Smart Contract
The examples in this procedure uses a pre-packaged smart contract,
sawtooth_xo
, which is available at
files.splinter.dev/scar/xo_0.4.2.scar.
To use a different smart contract, follow these steps to package the smart contract.
-
Create a
manifest.yaml
file that specifies the smart contract name, version, and the inputs and outputs (the addresses in state that the smart contract will read from and write to).The example smart contract has a manifest with the following contents:
name: sawtooth_xo version: '1.0' inputs: - '5b7349' outputs: - '5b7349'
-
Package the smart contract WASM file and the manifest in a smart contract archive (a tar file with the
.scar
extension).$ tar -jcvf mycontract_0.1.0.scar mycontract.wasm manifest.yaml
IMPORTANT: The name of the scar file must use the format
name_version
, where version is a valid semantic versioning version number (see semver.org), such asmycontract_0.1.0
in this example. This name corresponds to the contract argument used with thescabbard contract upload
command in a later step.
Connect to the scabbard-cli Container
-
Start a bash session in your node’s
scabbard-cli
Docker container (such asscabbard-cli-alpha
). You will use this container to run thescabbard
commands to upload and configure the smart contract.$ docker exec -it scabbard-cli-alpha bash root@scabbard-cli-alpha:/#
-
To simplify entering the
scabbard
commands in this procedure, setSERVICE_ID
to the fully qualified service ID for the scabbard service on this circuit (such as01234-ABCDE::gsAA
).root@scabbard-cli-alpha:/# export SERVICE_ID=01234-ABCDE::gsAA
Download the Smart Contract Package
-
Download the scar file (such as
xo_0.4.2.scar
) to thescabbard-cli
container.root@scabbard-cli-alpha:/# curl -OLsS https://files.splinter.dev/scar/xo_0.4.2.scar
Create a Contract Registry
Each smart contract requires a contract registry that specifies the contract’s name and owner. You must create a contract registry before you can upload the smart contract to the circuit.
-
Create a contract registry for the new smart contract.
This example creates a smart contract registry for
sawtooth_xo
, with the Grid daemon as the owner (thegridd
public key is used as the owner ID). The Grid daemon’s private key is used to sign this transaction.root@scabbard-cli-alpha:/# scabbard cr create sawtooth_xo \ --owners $(cat /root/.splinter/keys/gridd.pub) \ -k gridd \ -U 'http://splinterd-alpha:8085' \ --service-id $SERVICE_ID
Upload the Smart Contract
-
Upload the smart contract to the Splinter circuit by specifying the smart contract name and version (such as
xo:0.4.2
) and the path to the scar file.root@scabbard-cli-alpha:/# scabbard contract upload xo:0.4.2 \ --path . \ -k gridd \ -U 'http://splinterd-alpha:8085' \ --service-id $SERVICE_ID
IMPORTANT: The smart contract name and version must match the scar file name (with
:
instead of_
). You can use a*
character in place of a specific version number; see the scabbard-contract-upload(1) man page for more information.
Create a Namespace Registry
-
Create the namespace registry for the smart contract.
This example creates a new namespace with the
5b7349
address prefix andgridd
as the owner.root@scabbard-cli-alpha:/# scabbard ns create 5b7349 \ --owners $(cat /root/.splinter/keys/gridd.pub) \ -k gridd \ -U 'http://splinterd-alpha:8085' \ --service-id $SERVICE_ID
-
Grant the appropriate contract namespace permissions.
This example lets the
sawtooth_xo
smart contract read from and write to the namespace with the state address prefix5b7349
.root@scabbard-cli-alpha:/# scabbard perm 5b7349 sawtooth_xo --read --write \ -k gridd \ -U 'http://splinterd-alpha:8085' \ --service-id $SERVICE_ID
Display Smart Contract Information
Use scabbard contract list
and scabbard contract show
to verify that the smart contract has been uploaded to the circuit.
Tip: You can run these commands on the first node, or connect to another node’s
scabbard-cli
container (such as scabbard-cli-beta
) and set the
$SERVICE_ID
variable for that node (such as 01234-ABCDE::gsBB
).
-
List all uploaded smart contracts.
root@scabbard-cli-beta:/# scabbard contract list \ -U 'http://splinterd-beta:8085' \ --service-id $SERVICE_ID
The output shows each smart contract’s name, version, and owners, as in this example:
NAME VERSIONS OWNERS . . . pike 0.1 {gridd-alpha_public_key} sawtooth_xo 1.0 {gridd-alpha_public_key} . . .
-
Display the details of the new smart contract (such as
sawtooth_xo
).root@scabbard-cli-beta:/# scabbard contract show sawtooth_xo:1.0 \ -U 'http://splinterd-beta:8085' \ --service-id $SERVICE_ID
The output shows the smart contract name and version, plus the inputs, outputs, and creator’s public key (the person or entity that signed the transaction to upload the smart contract).
sawtooth_xo 1.0 inputs: - 5b7349 outputs: - 5b7349 creator: {gridd-alpha_public_key}