Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

EIP-1753 - Define a smart contract interface for permits and licences #1753

Merged
merged 25 commits into from
Jul 2, 2019
Merged
Show file tree
Hide file tree
Changes from 20 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
249 changes: 249 additions & 0 deletions EIPS/eip-1753.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,249 @@
---
eip: 1753
title: Smart Contract Interface for Licences
author: Lucas Cullen (@BitcoinBrisbane), Kai Yeung (@CivicKai), Anna Crowley <annaelizabethcrowley@gmail.com>, Caroline Marshall <caroline.marshall888@gmail.com>, Katrina Donaghy, <katrina@civicledger.com>
bitcoinbrisbane marked this conversation as resolved.
Show resolved Hide resolved
status: Draft
type: Standards Track
category: ERC
created: 2019-02-06
---

# Abstract
bitcoinbrisbane marked this conversation as resolved.
Show resolved Hide resolved

This Ethereum Improvement Proposal (EIP) proposes an Ethereum standard for the issuance of licences, permits and grants (Licences).

A Licence is a limited and temporary authority, granted to a natural (e.g. you) or legal person (e.g. a corporation), to do something that would otherwise be unlawful pursuant to a legal framework. A public Licence is granted by the government, directly (e.g. by the New South Wales Department of Primary Industries, Australia) or indirectly (e.g. by an agent operating under the government’s authority), and derives its authority from legislation, though this is often practically achieved via delegated legislation such as regulations. This can be contrasted to a private licence – for example, the licence you grant to a visitor who comes onto your property.

A Licence has the following properties:

* granted personally to the licencee (Licencee), though it may be transferrable to another person or company;
* conferring a temporary right to the Licencee to own, use or do something that would otherwise be prohibited, without conferring any property interest in the underlying thing. For example, you may be granted a licence to visit a national park without acquiring any ownership in or over the park itself;
* allowing the government authority responsible for the Licence to amend, revoke, renew, suspend or deny the issuance of the Licence, or to impose conditions or penalties for non-compliance; and
* usually issued only after the payment of a fee or the meeting of some criteria.

Additionally, a Licence may be granted in respect of certain information. For example, a Licence may be issued in respect of a vehicle registration number and attaching to that specific registered vehicle.

## Motivation

Governments are responsible for the issuance and management of Licences. However, maintaining and sharing this data can be complicated and inefficient. The granting of Licences usually requires the filing of paper-based application forms, manual oversight of applicable legislation and data entry into registries, as well as the issuance of paper based Licences. If individuals wish to sight information on Licence registries, they often need to be present at the government office and complete further paper-based enquiry forms in order to access that data (if available publicly).

This EIP seeks to define a standard that will allow for the granting and/or management of Licences via Ethereum smart contracts. The motivation is, in essence, to address the inefficiencies inherent in current licencing systems.

## Specification

## Token
bitcoinbrisbane marked this conversation as resolved.
Show resolved Hide resolved
### Methods

**NOTES**:
- The following specifications use syntax from Solidity `0.4.17` (or above)
- Callers MUST handle `false` from `returns (bool success)`. Callers MUST NOT assume that `false` is never returned!


#### name

Returns the name of the permit - e.g. `"MyPermit"`.

``` js
function name() public view returns (string)
```

#### totalSupply

Returns the total permit supply.

``` js
function totalSupply() public view returns (uint256)
```

#### grantAuthority

Adds an ethereum address to a white list of addresses that have authority to modify a permit.

``` js
function grantAuthority(address who)
```

#### revokeAuthority

Removes an ethereum address from a white list of addresses that have authority to modify a permit.

``` js
function revokeAuthority(address who)
```

#### hasAuthority

Checks to see if the address has authority to grant or revoke permits.

``` js
function hasAuthority(address who)
```

#### issue

Issues an ethereum address a permit between the specified date range.

``` js
function issue(address who, uint256 from, uint256 to) public;
```

#### revoke

Revokes a permit from an ethereum address.

``` js
function revoke(address who) public;
```

#### hasValid

Checks to see if an ethereum address has a valid permit.

``` js
function hasValid(address who) public view returns (boolean);
```

#### purchase

Allows a user to self procure a licence.

``` js
function purchase(uint256 from, uint256 to) public payable;
```

## Rationale

The use of smart contracts to apply for, renew, suspend and revoke Licences will free up much needed government resources and allow for the more efficient management of Licences. The EIP also seeks to improve the end user experience of the Licence system. In an era of open government, there is also an increased expectation that individuals will be able to easily access Licence registries, and that the process will be transparent and fair.

By creating an EIP, we hope to increase the use of Ethereum based and issued Licences, which will address these issues.

The Ethereum blockchain is adaptable to various Licences and government authorities. It will also be easily translatable into other languages and can be used by other governmental authorities across the world. Moreover, a blockchain will more effectively protect the privacy of Licence-holders’ data, particularly at a time of an ever-increasing volume of government data breaches.

The EIP has been developed following the review of a number of licensing regulations at the national and state level in Australia. The review allowed the identification of the common licence requirements and criteria for incorporation into the EIP. We have included these in the proposed standard but seek feedback on whether these criteria are sufficient and universal.

## Test Case

A real world example of a Licence is a permit required to camp in a national park in Australia (e.g. Kakadu national park in the Northern Territory of Australia) under the Environment Protection and Biodiversity Conservation Regulations 2000 (Cth) (EPBC Act) and the Environment Protection and Biodiversity Conservation Regulations 2000 (the Regulations). Pursuant to the EPBC Act and the Regulations, the Director of National Parks oversees a camping permit system, which is intended to help regulate certain activities in National Parks. Permits allowing access to National Parks can be issued to legal or natural persons if the applicant has met certain conditions.

The current digital portal and application form to camp at Kakadu National Park (the Application) can be accessed at: http://www.environment.gov.au/system/files/resources/b3481ed3-164b-4e72-a9f8-91fc987d90e7/files/kakadu-camping-permit-form-19jan2015-pdf.pdf

The user must provide the following details when making an Application:

* The full name and contact details of each person to whom the permit is to be issued;

* If the applicant is a company or other incorporated body:

o the name, business address and postal address of the company or incorporated body;

o if the applicant is a company—

* the full name of each of the directors of the company;

* the full name and contact details of the person completing the application form;

* the ACN or ABN of the company or other incorporated body (if applicable);

* Details of the proposed camping purpose (e.g. private camping, school group, etc.);

* A start date and duration for the camping (up to the maximum duration allowed by law);

* Number of campers (up to the maximum allowed by law);

* All other required information not essential to the issuance of the Licence (e.g. any particular medical needs of the campers); and

* Fees payable depending on the site, duration and number of campers.

The Regulations also set out a number of conditions that must be met by licensees when the permit has been issued. The Regulations allow the Director of National Parks to cancel, renew or transfer the licence. The above workflow could be better performed by way of a smart contract.

The key criteria required as part of this process form part of the proposed Ethereum standard. We have checked this approach by also considering the issuance of a Commercial Fishing Licence under Part 8 “Licensing and other commercial fisheries management” of the Fisheries Management (General) Regulation 2010 (NSW) (Fisheries Regulations) made pursuant to the Fisheries Management Act 1994 (NSW) (Fisheries Act).

## Implementation

The issuance and ownership of a Licence can be digitally represented on the Ethereum blockchain.

Smart contracts can be used to embed regulatory requirements with respect to the relevant Licence in the blockchain. The Licence would be available electronically in the form of a token. This might be practically represented by a QR code, for example, displaying the current Licence information. The digital representation of the Licence would be stored in a digital wallet, typically an application on a smartphone or tablet computer. The proposed standard allows issuing authorities or regulators to amend, revoke or deny Licences from time to time, with the result of their determinations reflected in the Licence token in near real-time. Licence holders will therefore be notified almost instantly of any amendments, revocations or issues involving their Licence.

## Interface

### Solidity Example
```
interface EIP1753 {
string public name;
uint256 public totalSupply;

function grantAuthority(address who);
function revokeAuthority(address who);
function hasAuthority(address who) pure public returns (bool);

function issue(address who, uint256 from, uint256 to) public;
function revoke(address who) public;

function hasValid(address who) public view returns (boolean);
function purchase(uint256 from, uint256 to) public payable;
}

pragma solidity ^0.5.3;

contract EIP is EIP1753 {

string public name = "Kakadu National Park Camping Permit";
uint256 public totalSupply;

address private _owner;
mapping(address => bool) private _authorities;
mapping(address => Permit) private _holders;

struct Permit {
address issuer;
uint256 start;
uint256 end;
}

constructor() public {
_owner = msg.sender;
}

function grantAuthority(address who) public onlyOwner() {
_authorities[who] = true;
}

function revokeAuthority(address who) public onlyOwner() {
delete _authorities[who];
}

function hasAuthority(address who) public view returns (bool) {
return _authorities[who] == true;
}

function issue(address who, uint256 start, uint256 end) public onlyAuthority() {
_holders[who] = Permit(_owner, start, end);
totalSupply += 1;
}

function revoke(address who) public onlyAuthority() {
delete _holders[who];
}

function hasValid(address who) public view returns (bool) {
return _holders[who].start > now && _holders[who].end < now;
}

function purchase(uint256 from, uint256 to) public payable {
require(msg.value == 1 ether, "Incorrect fee");
issue(msg.sender, from, to);
}

modifier onlyOwner() {
require(msg.sender == _owner, "Only owner can perform this function");
_;
}

modifier onlyAuthority() {
require(hasAuthority(msg.sender) == true, "Only an authority can perform this function");
_;
}
}
```

## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
2 changes: 1 addition & 1 deletion eip-X.md → eip-x.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,4 +51,4 @@ Test cases for an implementation are mandatory for EIPs that are affecting conse
The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.

## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please don't change or rename this file.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought I reverted.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed it for you.