Event chain
Microledger on the private layer
The event chain is a microledger. Normally, a ledger is a hash chain of blocks, with each block containing multiple transactions. The event chain is a hash chain of individual events.
Create an event chain
The event id is generated from the account public key and a random value or a nonce, to prevent collisions.
import LTO from '@ltonetwork/lto';
import { EventChain } from '@ltonetwork/lto/events';
const lto = new LTO('T');
const account = lto.account();
const chain = new EventChain(account); // Creates an empty event chain with a valid id
Adding events
The genesis event determines the purpose of the event chain. For an Ownable, the genesis event contains an instantiate message.
import { EventChain, Event } from '@ltonetwork/lto/events';
const body = {
'@context': 'instantiate_msg.json',
ownable_id: '88pDRu52FpsU3kKHwdvPV21RMkBqVqNnthjfdCesTHQhLnUpanw49n6b2PzGnEy',
package: 'bafybeie4ts4mbcw4pswzh45bj32ulcyztup2dr7zbbjv3y2ym3q3uuejba',
network_id: 'T',
};
const lto = new LTO('T');
const account = lto.account();
const chain = new EventChain(account);
new Event(body).addTo(chain).signWith(account);
Events need to be added to the chain before they can be signed.
Loading an event chain
You can store or submit an event chain as JSON. To create an event chain object from JSON data use the from
method.
import { EventChain } from '@ltonetwork/lto/events';
const data = {
id: '2dZKMnHHsM1MGqTPZ5p3NmmGmAFE4hYFtMwb2e6tGVDMGZT13cBomKoo8DLEWh',
events: [
{
timestamp: 1519882600,
previous: 'A332JTKSBZipjXxjC1xPxQoheF83WkEBMwLYaYs8yUBa',
signKey: {
keyType: 'ed25519',
publicKey: '2KduZAmAKuXEL463udjCQkVfwJkBQhpciUC4gNiayjSJ',
},
signature: '4xn3xqLFXDLVtUjyKXAjTVGfjWkbCbtyQxFSVoYGLRzePGeyRAeEU7a29ZFztgD3ifwBBMWv9T51ecY2ZBNyWvXV',
hash: 'BRFnaH3UFnABQ1gV1SvT9PLo5ZMFzH7NhqDSgyn1z8wD',
mediaType: 'application/json',
data: 'base64:eyJmb28iOiJiYXIiLCJjb2xvciI6InJlZCJ9',
},
{
timestamp: 1519883600,
previous: 'BRFnaH3UFnABQ1gV1SvT9PLo5ZMFzH7NhqDSgyn1z8wD',
signKey: {
keyType: 'ed25519',
publicKey: '2KduZAmAKuXEL463udjCQkVfwJkBQhpciUC4gNiayjSJ',
},
signature: '2hqLhbmh2eX2WhAgbwHhBZqzdpFcjWBYYN5WBj8zcYVKzVbnVH7mESCC9c9acihxWFwfvufnFYxxgFMgJPbpbU4N',
hash: '9Y9DhjXHdrsUE93TZzSAYBWZS5TDWWNKKh2mihqRCGXh',
mediaType: 'application/json',
data: 'base64:eyJmb28iOiJiYXIiLCJjb2xvciI6ImdyZWVuIn0=',
},
{
timestamp: 1519884600,
previous: '9Y9DhjXHdrsUE93TZzSAYBWZS5TDWWNKKh2mihqRCGXh',
signKey: {
keyType: 'ed25519',
publicKey: '2KduZAmAKuXEL463udjCQkVfwJkBQhpciUC4gNiayjSJ',
},
signature: 'BDtUgUJRmbumMMw3V35v7AJrnJ954cBVYQDPyyMc1Hx2x5LZYZkByuUzNJ2zvUWUhCUL3PJF86FQE6WFyQ7VCZU',
hash: 'C2TsRTTsj7V923RQnEARYL596AXvccd1np32N9of4FaP',
mediaType: 'application/json',
data: 'base64:eyJmb28iOiJiYXIiLCJjb2xvciI6ImJsdWUifQ==',
},
],
};
const chain = EventChain.from(data);
Validation
When receiving an event chain from an untrusted source, you should always validate it. The validate
method checks the integrity of the hash chain and verifies the signatures.
chain.validate();
The validate
function does not return any value, but throws an error in case something is wrong with the chain.
Additionally, you may want to check if the signer of the genesis event is the account that created the event chain.
const genesisSigner = lto.account(chain.events[0].signKey);
if (!chain.isCreatedBy(genesisSigner))
throw new Error('Event chain hijacking: genesis event not signed by chain creator');
Partial chain
There are several reasons why you'd only want to get part of the event chain. For instance, you may only need to share added events with another party. To do so, you can startingWith
or startingAfter
method.
const partial1 = chain.startingWith('9Y9DhjXHdrsUE93TZzSAYBWZS5TDWWNKKh2mihqRCGXh');
const partial2 = chain.startingAfter('9Y9DhjXHdrsUE93TZzSAYBWZS5TDWWNKKh2mihqRCGXh');
You can either pass an event hash or an Event
object.
const partial = chain.startAfter(chain.event[1]);
Appending a partial chain
You can append the events of a partial chain to the full chain. If there's an overlap in events, the add
method will skip those events.
If both chains have the same genesis event, but branch off, a MergeConflict
will be thrown.
try {
chain.add(partial);
} catch (error) {
if (!(error instanceof MergeConflict)) throw error;
// handle merge conflict
}
The event chain doesn't have an internal consensus mechanism. Instead, it relies on anchoring events on the public chain to determine which branch should be accepted in case of a merge conflict.
Anchoring events
To detect rollbacks, resolve merge conflicts, and prevent tampering, events should be anchored. Anchoring is the action of writing the event hash to the public chain.
For rollback detection, we use mapped anchoring where the event hash is combined with a state.
import LTO from '@ltonetwork/lto';
const lto = new LTO('T');
const account = lto.account();
const appendedEvents = chain.startingAfter(lastKnownEvent);
const anchorMap = appendedEvents.anchorMap();
await lto.anchor(account, anchorMap);
Last updated