@vaultsentry/contracts NPM

@vaultsentry/contracts

Version: 0.1.1-alpha

Warning: This is an experimental version of VaultSentry. The primary purpose of this version is to serve as a proof of concept. Things can break in this version, and should not be used for production.

This library is a group of smart contracts that can be used for creating important events and blocking suspicious events. How this contract works is similar to the name. If a monitored smart contract wants to send funds out, they will be first held in the VaultSentry for a small period of time before releasing them. It also works as a sentry, since in combination with the security node, it will halt any pending transactions that matches to any specified blacklisted rule.

Rules are strings that are able to describe blacklisted patterns that could potentially signify a hack or unintended behaviour. You should input these strings in _buildPattern or buildPattern if you are the VaultSentry manager, and it will give you the rule id used by nodes to specify which rule has been matched.

Syntax

Definition of an Event

EventName(param1,param2,...,paramN);

An event consists of a name, followed by round brackets, separated with commas to denote its parameters. More events can be concated to each other to denote ordering. The start and end of this match can be anywhere. Here are some examples:

Rule: EventA();

// matches
EventA();

// Does not match
EventC();

Rule: EventA();EventB(0);

// matches
EventA();EventB(0);

// Does not match
EventA();EventB(1);
EventB(0);
EventA();

Escape Character `\`

EventA(\=x);

If you want to use any sensitive characters literally in the event name or parameters, such as =\()[]|,+*;, you will need to use the escape character.

Rule: EventA(\=x);

// matches
EventA(=x);

// Does not match
EventA(x);
EventA(\=x);

Types of Parameters

Don't Care `_`

EventA(_);

An event can have a parameter with an underscore, which denotes a don't care value. It will match any EventA, regardless of its parameters.

Rule: EventA(_,3);

// matches
EventA(2,3);
EventA(apples,3);
EventA(0x123456789,3);

// Does not match
EventA(apples,4);
EventC();
EventB(3);

Variable `=<variable>`

EventA(=x);EventB(=x);

A variable as a paramter ensures they are the same. In terms of how the validator works, the first mention of =<variable> sets the variable, and every mention afterwards of the same =<variable> gets the variable to check if they are the same parameter.

Rule: EventA(=x);EventB(=x);

// matches
EventA(2);EventB(2);
EventA(hello);EventB(hello);

// Does not match
EventA(4);EventB(1);
EventA(3);EventA(3);

Warning: There are some limitations on variables, please read the exceptions in Types of Events.

Types of Events

Wildcard `*`

*;

This matches 0 or more of any event. Must be used in conjunction with other events.

Warning: Since there is no anchoring of matches, if the last pattern of the rule is *;, it will have no effect on the statement.

Rule: EventA();*;EventB();

// matches
EventA();EventB();
EventA();EventC();EventD();EventB();

// Does not match
EventA();
EventB();

Quantifier `+`

EventA()+;

This matches 0 or more of the specified event. In this case, we want to match 0 or more instances of EventA().

Warning: Since there is no anchoring of matches, if the last pattern of the rule is ...+;, it will have no effect on the statement.

Rule: EventA();EventB()+;EventC();

// matches
EventA();EventC();
EventA();EventB();EventC();
EventA();EventB();EventB();EventC();

// Does not match
EventA();EventD();EventC();
EventA();EventC();EventC();

Negation `!`

!EventA(0);

This matches any event that isn't EventA(0).

Rule: !EventA(0);

// matches
EventA(1);
EventC(1,2,4);

// Does not match
EventA(0);

Rule: EventA();!EventB()+;EventC();

// matches
EventA();EventC();
EventA();EventD();EventC();
EventA();EventC();EventC();

// Does not match
EventA();EventB();EventC();
EventA();EventB();EventB();EventC();

Warning:

When used in conjunction of +, you will match 0 or more of the negation. See above examples.
You cannot negate *. i.e. !*;.

Groups

[EventA()|EventB()];

This will match with any event specified in the group.

Rule: [EventA()|EventB()];

// matches
EventA();
EventB();

// Does not match
EventC();

The way negation would work applied on the group is that it will match with anything that does not belong in the group.

Rule: ![EventA(0)|EventB(0)];

// matches
EventC();
EventA(1);

// Does not match
EventA(0);
EventB(0);

Warning: There are several limitations on this grouping.

You cannot have a sequence of events (which includes quantifiers) nor another group of events within a group. i.e. [[EventA(0)|EventB(0)]|EventB(0)]; is invalid.
Due to how the on-chain validator currently works and to prevent ambiguity, you cannot set a variable in a event which uses a combination of a grouping and the quantifier +. Here are some examples:
- [EventA(=x)|EventB(=x)]+;EventC(=x); is invalid.
- EventC(=x);[EventA(=x)|EventB(=x)]+;EventC(=x); is valid.