Skip to content

Commit

Permalink
update doc
Browse files Browse the repository at this point in the history
  • Loading branch information
rueshyna committed Aug 1, 2023
1 parent d96d939 commit eadf222
Showing 1 changed file with 13 additions and 79 deletions.
92 changes: 13 additions & 79 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# TzSafe
Tzsafe is a multisig wallet aiming at providing better assurance of security and management of ownership than a traditional single-signed wallet.
TzSafe is a multisig wallet aiming at providing better assurance of security and management of ownership than a traditional single-signed wallet. TzSafe adheres to the [TZIP26](https://gitlab.com/tezos/tzip/-/blob/master/drafts/current/draft-proof-of-event/proof_of_event.md) standard, which is known as "Proof of event."

Multi-signature (also multisig) wallet allows to share the ownership of an account by a smart contract. Each owner can create a proposal to propose transferring Tez or executing other contracts. Signer provides approval stored on-chain by performing Tezos transaction. Once gathering the minimal approvals, the multisig will perform the proposal.

Expand All @@ -9,69 +9,7 @@ The contract is written in cameligo. Please follow [the instructions of installa
The minimal required version can be found by performing `make ligo-version`.

# Usage
## Create multisig wallet

To create a multisig wallet, you can use the default contracts that we provided or customize by yourself.

If purpose is to transfer Tez in and out only, the `app/main_unit.mligo` is recommended. Please run `make build` to compile the contract in Michelson which can be found in `_build/app/multisig_unit.tez`. See the Deploy section for the origination of the contract.

On the other hand, if executing other contracts is required, you can either use `app/main_bytes.mligo` or the multisig library to customize your own.

In the case of using `app/main_bytes.mligo`, you need to `pack` a parameter of the target contract as bytes and include it while creating a proposal. Once the minimal approvals are gathered, multisig will start executing the target contract. The target contract needs to `unpack` bytes by itself to get meaningful data.

```mermaid
sequenceDiagram
actor User
participant My Multisig Wallet
participant My Business Contract
Note right of My Business Contract: type parameter = Buy tez | Sell tez
User ->> User: params = pack (Buy 10tez)
User ->> My Multisig Wallet: create_proposal(..., params, ... )
Note over User,My Business Contract: gathering required approval
My Multisig Wallet ->> My Business Contract:execute(..., params, ...)
My Business Contract ->> My Business Contract: unpack(params), ...
```

Last, if you want a unpacked type, customizing your wallet is possible. First, in `package.json`, add `multi-signature` library in dependencies. In the library, we provide `contract` function with type variable `a`.

```
let contract (type a) (request : a parameter_types * a storage_types) : a result = ...
```
where `a` is the type of your contract parameter. You will need to use the function to define an entry of multisig. For example,

```ocaml
#import "ligo-multisig/src/lib.mligo" Multisig
type action
= Action1 of nat
| Action2 of string
(* your main entry *)
let main (input : action * storage) : operation list * storage =
(* the multisig entry *)
let multisig (input : action Multisig.parameter_types * action Multisig.storage_types) : action Multisig.result =
Multisig.contract input
```
Finally, compile the contracts with LIGO.

```bash
# compile your contract
ligo compile contract your_contract.mligo --entry-point main

# compile multisig contract
ligo compile contract your_contract.mligo --entry-point multisig
```

Note that the `Execute_lambda` is also provided another solutions for executing other contracts.

## Entrypoints of multisig

### default
This entrypoint can receive Tez from any source.
- Emit event
Expand All @@ -82,9 +20,9 @@ This entrypoint can receive Tez from any source.
Each owner can create proposal through this entrypoint. The entrypoint supports creating a batch of transactions. The batch is atomic and execution by order. If modifing settings are proposed, the modified setting will NOT apply in this batch immediately. The setting will effect on a next batch/transaction.

- proposal that owner can create
- `Transfer of { target:address; parameter:unit; amount:tez}`
- `Transfer of { target:address; parameter:unit; amount:tez }`
- transfer amount only
- `Execute of { target:address; parameter:'a; amount:tez}`
- `Execute of { target:address; parameter:'a; amount:tez }`
- execute contract with type of parameter `'a`
- `Execute_lambda of { metadata: bytes option; lambda: (unit -> operation)}`
- execute lambda, note that the cost of using `Transfer` and `Execute`is cheaper than `Execute_lambda`
Expand All @@ -99,28 +37,23 @@ Each owner can create proposal through this entrypoint. The entrypoint supports
- tag: `create_proposal`
- data: `(proposal id, created proposal)`

### sign_and_resolve_proposal
Signers can provide an approval or a disapproval through this entrypoint. The owner who is statisfied the minimal requestment of approvals will also trigger the execution of proposal. After the proposal has been resolved, owners can not provide their approvals.
### sign_proposal
Signers can provide an approval or a disapproval through this entrypoint.

- Emit event
- tag: `sign_proposal`
- data: `(proposal id, owner, agreement)`
- tag: `resolve_proposal` (only when proposal is resolved)
- data: `(proposal id, owner)`

# sign_proposal_only
Signers can provide an approval or a disapproval through this entrypoint. Unlike `sign_and_resolve_proposal`, the proposal won't be resolve in any case.

- Emit event
- tag: `sign_proposal`
- data: `(proposal id, owner, agreement)`
### proof_of_event_challenge
The adaptation to the TZIP-26 standard includes renaming the `resolve_proposal` entrypoint as `proof_of_event_challenge`. In this context, the `challenge_id` now represents the `proposal_id`, while the payload corresponds to the content of the proposal.

# resolve_proposal
Signers can resolve proposal when minimal requestment is statisfied.

- Emit event
- tag: `resolve_proposal`
- data: `(proposal id, owner)`
- tag: `proof_of_event`
- data: `(chellenge_id, payload)`

# Deploy
We provide several steps for quick deploying contracts in `app/` to ghostnet.
Expand All @@ -131,6 +64,7 @@ We provide several steps for quick deploying contracts in `app/` to ghostnet.
1. go [faucet](https://faucet.marigold.dev/) to request some XTZ.
1. run `make deploy` to deploy contracts

# TODO
- support a different kind of threshold
- support FA2.1
# Changelog
- 0.1.x: (release-1.0)
- 0.2.x: base on 0.1.x and support the ticket (main branch)
- 0.3.x: base on 0.1.x and support TZIP-26 (release-3.0)

0 comments on commit eadf222

Please sign in to comment.