ch.epfl.dedis.byzcoin.contracts

Class SecureDarcInstance

java.lang.Object

ch.epfl.dedis.byzcoin.contracts.SecureDarcInstance

public class SecureDarcInstance
extends Object

DarcInstance represents a contract of a darc in ByzCoin. It is self- sufficient, meaning it has a link to the byzcoin service it runs on. If you evolve the DarcInstance, it will update its internal darc.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ContractId

Constructor Summary

Constructors

Constructor and Description
SecureDarcInstance(ByzCoinRPC bc, DarcId spawnerBaseId, Signer spawnerSigner, Long signerCtr, Darc newDarc) Instantiates a new DarcInstance from an existing darc by sending a spawn instruction to ByzCoin and then creating the instance from the existing darcInstance.

Method Summary

Modifier and Type	Method and Description
void	evolveDarc(Darc newDarc, Signer owner, Long ownerCtr) Takes a new darc, increases its version, creates an instruction and sends it to ByzCoin, without waiting an acknowledgement.
ClientTransactionId	evolveDarcAndWait(Darc newDarc, Signer owner, Long ownerCtr, int wait) Asks byzcoin to evolve the darc and waits until the new darc has been stored in the global state.
ClientTransactionId	evolveDarcAndWait(Darc newDarc, Signer owner, Long ownerCtr, int wait, boolean unrestricted) Asks byzcoin to (unrestricted) evolve the darc and waits until the new darc has been stored in the global state.
Instruction	evolveDarcInstruction(Darc newDarc, Identity id, Long signerCtr) Creates an instruction to evolve the darc in byzcoin.
Instruction	evolveDarcInstruction(Darc newDarc, Identity id, Long signerCtr, boolean unrestricted) Creates an instruction to (unrestricted) evolve the darc in byzcoin.
static SecureDarcInstance	fromByzCoin(ByzCoinRPC bc, Darc d) Instantiates a new DarcInstance given a working ByzCoin service and an instanceId.
static SecureDarcInstance	fromByzCoin(ByzCoinRPC bc, DarcId baseId) Instantiates a new DarcInstance given a working ByzCoin service and an instanceId.
static SecureDarcInstance	fromByzCoin(ByzCoinRPC bc, InstanceId id) Instantiates a new DarcInstance given a working ByzCoin service and an instanceId.
Darc	getDarc()
DarcId	getId()
Instance	getInstance()
SecureDarcInstance	spawnDarcAndWait(Darc d, Signer s, Long signerCounter, int wait) Spawns a new darc from the given darcInstance.
ClientTransactionId	spawnInstance(String contractID, Signer s, Long signerCtr, List<Argument> args) Like spawnInstanceInstruction, but creates a ClientTransaction with only this instruction and sends it to byzcoin.
Proof	spawnInstanceAndWait(String contractID, Signer s, Long signerCtr, List<Argument> args, int wait) Like spawnInstance but waits for the instance to be stored in byzcoin.
Instruction	spawnInstanceInstruction(String contractID, Identity id, Long signerCtr, List<Argument> args) Creates an instruction for spawning an instance.
void	update() Update looks up the darc in ByzCoin and updates to the latest version, if available.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ContractId

public static String ContractId

Constructor Detail

SecureDarcInstance

public SecureDarcInstance(ByzCoinRPC bc,
                          DarcId spawnerBaseId,
                          Signer spawnerSigner,
                          Long signerCtr,
                          Darc newDarc)
                   throws CothorityException

Instantiates a new DarcInstance from an existing darc by sending a spawn instruction to ByzCoin and then creating the instance from the existing darcInstance.

Parameters:

bc - a running ByzCoin service

spawnerBaseId - the base ID of a darc with the rights to spawn new darcs

spawnerSigner - the signer with the rights to spawn new darcs

signerCtr - the monotonically increasing counters for the spawnSigner

newDarc - the new darc to spawn

Throws:

CothorityException - if something goes wrong

Method Detail

update

public void update()
            throws CothorityException

Update looks up the darc in ByzCoin and updates to the latest version, if available.

Throws:

CothorityException - if something goes wrong

evolveDarcInstruction

public Instruction evolveDarcInstruction(Darc newDarc,
                                         Identity id,
                                         Long signerCtr)

Creates an instruction to evolve the darc in byzcoin. The signer must have its identity in the current darc as "invoke:darc:evolve" rule. TODO: allow for evolution if the expression has more than one identity.

Parameters:

newDarc - the darc to replace the old darc, the version, prevID and baseID attributes are ignored and set automatically by this function

signerCtr - is the monotonically increasing counter which must match the signer who will eventually sign the returned instruction.

Returns:

Instruction to be sent to byzcoin

evolveDarcInstruction

public Instruction evolveDarcInstruction(Darc newDarc,
                                         Identity id,
                                         Long signerCtr,
                                         boolean unrestricted)

Creates an instruction to (unrestricted) evolve the darc in byzcoin. The signer must have its identity in the current darc as "invoke:darc.evolve" or "invoke:darc.evolve_unrestricted" rule, depending on the unrestricted flag. TODO: allow for evolution if the expression has more than one identity.

Parameters:

newDarc - the darc to replace the old darc, the version, prevID and baseID attributes are ignored and set automatically by this function

signerCtr - is the monotonically increasing counter which must match the signer who will eventually sign the returned instruction.

unrestricted - whether to use the unrestricted evolution

Returns:

Instruction to be sent to byzcoin

evolveDarc

public void evolveDarc(Darc newDarc,
                       Signer owner,
                       Long ownerCtr)
                throws CothorityException

Takes a new darc, increases its version, creates an instruction and sends it to ByzCoin, without waiting an acknowledgement.

Parameters:

newDarc - the new darc, the version, prevID and baseID attributes are ignored and set automatically by this function

owner - a signer allowed to evolve the darc

ownerCtr - a monotonically increasing counter which must map to the owners

Throws:

CothorityException - if something goes wrong

evolveDarcAndWait

public ClientTransactionId evolveDarcAndWait(Darc newDarc,
                                             Signer owner,
                                             Long ownerCtr,
                                             int wait)
                                      throws CothorityException

Asks byzcoin to evolve the darc and waits until the new darc has been stored in the global state.

Parameters:

newDarc - the darc to replace the old darc, the version, prevID and baseID attributes are ignored and set automatically by this function

owner - is the owner that can sign to evolve the darc

ownerCtr - a monotonically increasing counter which must map to the owners

wait - the maximum number of blocks to wait

Returns:

ClientTransactionId of the accepted transaction

Throws:

CothorityException - if something goes wrong

evolveDarcAndWait

public ClientTransactionId evolveDarcAndWait(Darc newDarc,
                                             Signer owner,
                                             Long ownerCtr,
                                             int wait,
                                             boolean unrestricted)
                                      throws CothorityException

Asks byzcoin to (unrestricted) evolve the darc and waits until the new darc has been stored in the global state.

Parameters:

newDarc - the darc to replace the old darc, the version, prevID and baseID attributes are ignored and set automatically by this function

owner - is the owner that can sign to evolve the darc

ownerCtr - a monotonically increasing counter which must map to the owners

wait - the maximum number of blocks to wait

unrestricted - whether to use the unrestricted evolution

Returns:

ClientTransactionId of the accepted transaction

Throws:

CothorityException - if something goes wrong

spawnInstanceInstruction

public Instruction spawnInstanceInstruction(String contractID,
                                            Identity id,
                                            Long signerCtr,
                                            List<Argument> args)

Creates an instruction for spawning an instance.

TODO: allow for multi-signatures

Parameters:

contractID - the id of the instance to create

signerCtr - the next counter which the signer should use

args - arguments to give to the contract

Returns:

the instruction to be added to the ClientTransaction

spawnInstance

public ClientTransactionId spawnInstance(String contractID,
                                         Signer s,
                                         Long signerCtr,
                                         List<Argument> args)
                                  throws CothorityException

Like spawnInstanceInstruction, but creates a ClientTransaction with only this instruction and sends it to byzcoin.

Parameters:

contractID - the id of the instance to create

s - the signer that is authorized to spawn this contract-type

signerCtr - a monotonically increasing counter which must map to the signer s

args - arguments to give to the contract

Returns:

the client transaction ID

Throws:

CothorityException - if something goes wrong

spawnInstanceAndWait

public Proof spawnInstanceAndWait(String contractID,
                                  Signer s,
                                  Long signerCtr,
                                  List<Argument> args,
                                  int wait)
                           throws CothorityException

Like spawnInstance but waits for the instance to be stored in byzcoin.

Parameters:

contractID - the id of the instance to create

s - the signer that is authorized to spawn this contract

signerCtr - a monotonically increasing counter which must map to the signer s

args - arguments to give to the contract

wait - how many blocks to wait for the instance to be stored (0 = do not wait)

Returns:

the Proof of inclusion

Throws:

CothorityException - if something goes wrong

spawnDarcAndWait

public SecureDarcInstance spawnDarcAndWait(Darc d,
                                           Signer s,
                                           Long signerCounter,
                                           int wait)
                                    throws CothorityException

Spawns a new darc from the given darcInstance. The current darc needs to have the "spawn:darc" rule with an expression that can be evaluated to true by the signer s.

Parameters:

d - the new darc to store on ByzCoin

s - the signer allowed to spawn a new darc

wait - how many blocks to wait. If it is 0, the call returns directly

Returns:

a new DarcInstance, might be null if wait == 0

Throws:

CothorityException - if something goes wrong if something went wrong

getId

public DarcId getId()

Returns:

the id of the darc being held

getDarc

public Darc getDarc()

Returns:

the darc of this instance.

getInstance

public Instance getInstance()

Returns:

the instance of the contract.

fromByzCoin

public static SecureDarcInstance fromByzCoin(ByzCoinRPC bc,
                                             InstanceId id)
                                      throws CothorityException

Instantiates a new DarcInstance given a working ByzCoin service and an instanceId. This instantiator will contact byzcoin and try to get the current darcInstance. If the instance is not found, or is not of contractId "darc", an exception will be thrown.

Parameters:

bc - is a running ByzCoin ledger

id - of the darc-instance to connect to

Returns:

DarcInstance representing the latest version of the darc given in id

Throws:

CothorityException - if something goes wrong

fromByzCoin

public static SecureDarcInstance fromByzCoin(ByzCoinRPC bc,
                                             DarcId baseId)
                                      throws CothorityException

Instantiates a new DarcInstance given a working ByzCoin service and an instanceId. This instantiator will contact byzcoin and try to get the current darcInstance. If the instance is not found, or is not of contractId "darc", an exception will be thrown.

Parameters:

bc - is a running ByzCoin ledger that is running

baseId - of the darc-instance to connect to

Returns:

DarcInstance representing the latest version of the given baseId

Throws:

CothorityException - if something goes wrong

fromByzCoin

public static SecureDarcInstance fromByzCoin(ByzCoinRPC bc,
                                             Darc d)
                                      throws CothorityException

Instantiates a new DarcInstance given a working ByzCoin service and an instanceId. This instantiator will contact byzcoin and try to get the current darcInstance. If the instance is not found, or is not of contractId "darc", an exception will be thrown.

Parameters:

bc - is a running ByzCoin ledger

d - of which the base id will be taken to search in ByzCoin

Returns:

DarcInstance representing the latest version of the given baseId

Throws:

CothorityException - if somethings goes wrong