Skip to content

Commit

Permalink
Enhance license documentation (storyprotocol#331)
Browse files Browse the repository at this point in the history 
* feat: Enhance documentation formatting and readability 
* feat: Enhance documentation with security testing guidelines
  • Loading branch information
@savvar9991
savvar9991 authored Dec 10, 2024
1 parent 320e5c1 commit 231401e
Show file tree
Hide file tree
Showing 2 changed files with 125 additions and 71 deletions.
19 changes: 14 additions & 5 deletions GUIDELINES.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The test suite should run automatically for every change in the repository, and

The test suite coverage must be kept as close to 100% as possible, enforced in pull requests.

Test should use Foundry, unless for some reason js or hardhat are needed (for example, upgrades).
Tests should use Foundry, unless for some reason js or hardhat are needed (for example, upgrades).

The test function names will follow

Expand All @@ -29,10 +29,19 @@ In some cases unit tests may be insufficient and complementary techniques should

1. Property-based tests (aka. fuzzing) for math-heavy code.
2. hardhat test using `hardhat-upgrades` OZ plugin to verify storage and upgradeability (until they support Foundry).
3. Fork tests for upgreadeability to new implementations for upgradeable contracts, testing against the deployed contracts.
3. Fork tests for upgradeability to new implementations for upgradeable contracts, testing against the deployed contracts.
4. E2E tests for critical (happy) paths.
5. Formal verification for state machines.

## Security Testing

Critical security aspects that must be tested:
- Access control and permission systems
- Token economics and balance accounting
- Upgrade mechanisms and storage layouts
- External contract interactions and reentrancy guards
- Event emission for state changes

## Documentation

For contributors, project guidelines and processes must be documented publicly.
Expand All @@ -57,7 +66,7 @@ External contributions must be reviewed separately by multiple maintainers.

Automation should be used as much as possible to reduce the possibility of human error and forgetfulness.

Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions worklows](https://github.com/nikitastupin/pwnhub).
Automations that make use of sensitive credentials must use secure secret management, and must be strengthened against attacks such as [those on GitHub Actions workflows](https://github.com/nikitastupin/pwnhub).

Some other examples of automation are:

Expand Down Expand Up @@ -149,7 +158,7 @@ In addition to the official Solidity Style Guide we have a number of other conve

* Unchecked arithmetic blocks should contain comments explaining why overflow is guaranteed not to happen. If the reason is immediately apparent from the line above the unchecked block, the comment may be omitted.

* Interfaces should contain methods an events. Structs showing in an interface should be grouped in a library
* Interfaces should contain methods and events. Structs showing in an interface should be grouped in a library

* Function parameter names will have the **suffix** `_`

Expand All @@ -163,4 +172,4 @@ In addition to the official Solidity Style Guide we have a number of other conve
- `isValid`
- `valid`
- Modifier (prepositionNoun)
- `onlyOwner`
- `onlyOwner`
177 changes: 111 additions & 66 deletions test/foundry/modules/licensing/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,61 +5,77 @@ A license is to make a derivative

Bob owns IP1
1) If Bob adds 1 Policy in IP -> others can mint if they pass verifications ✅
1) If Bob doesn't set Policy in IP -> others can't mint✅
2) Bob can mint Licenses with whatever Policy in any of the above✅
2) If Bob doesn't set Policy in IP -> others can't mint✅
3) Bob can mint Licenses with whatever Policy in any of the above✅

3) Bob can add different policies on IP1 without compatibility checks. Others can mint licenses to make derivatives of IP1 from each different policy, as long as they pass the verifications✅
4) Bob can add different policies on IP1 without compatibility checks. Others can mint licenses to make derivatives of IP1 from each different policy, as long as they pass the verifications✅

4) Bob can mint licenses with different policies, transfer to others, and the holders can make derivatives from each License, regardless of IP1 having several policies set✅
5) Bob can mint licenses with different policies, transfer to others, and the holders can make derivatives from each License, regardless of IP1 having several policies set✅

5) Bob has set P1 and P2 in IP1, and gets license(LE) with PolicyEmergence(PE) from Emergence's World Bible IP (IPE)
6) Bob has set P1 and P2 in IP1, and gets license(LE) with PolicyEmergence(PE) from Emergence's World Bible IP (IPE)
Bobs wants to set IPE as parent of IP1

6.1) If the policies that IP1 has are in conflict with PE, revert 🚧

6.2) If the policies that IP1 has are not in conflict with PE, OK -> IP1 adds PE, IPE parent of IP1 🚧

6.3) Bob disable conflicting policies, then Adds PE 🚧

# Starting from A Derivative

Bob owns IP1

Bob creates a license L1 with P1

Alice owns IP2

Alice burns L1, P1 is set in IP2

1) P1 does not allow for derivatives
1.1) Don tries to mint a license from P1 in IP2 -> fails ✅
1.2) Alice tries to mint a license from P1 in IP2 -> fails ✅
1.3) Alice tries to set a policy --> fails ✅
1. P1 does not allow for derivatives

1.1. Don tries to mint a license from P1 in IP2 -> fails ✅

1.2. Alice tries to mint a license from P1 in IP2 -> fails ✅

1.3. Alice tries to set a policy --> fails ✅

/*
* Edge case:Alice buys the right from her licensor to make derivatives.
Setting the parent again should work in this case, P2 should be.
*/

1.4. Bob mints L2 with P2 (allows derivatives) and sends it to Alice
Alice burns L2 and P2 is set in IP2
Alice can mint now L3 with P2?

// Edge case, later on, Alice buys the right from her licensor to make derivatives
// Setting the parent again should work in this case, P2 should be
1.4) Bob mints L2 with P2 (allows derivatives) and sends it to Alice
Alice burns L2 and P2 is set in IP2
Alice can mint now L3 with P2?
3. P1 allows for derivatives of this derivatives, but meaning P1 propagates down, no other can be set (reciprocal == true)

2.1. Don tries to mint a license from P1 in IP2 -> License mints, has P1 ✅

1) P1 allows for derivatives of this derivatives, but meaning P1 propagates down, no other can be set (reciprocal == true)
2.1) Don tries to mint a license from P1 in IP2 -> License mints, has P1 ✅
2.2) Alice tries to mint a license from P1 in IP2 -> License mints, has P1 ✅
2.3) Alice tries to set P2 in IP2 -> Fails, reciprocal means no different policies allowed,
and you cannot add the same policy twice ✅
2.2. Alice tries to mint a license from P1 in IP2 -> License mints, has P1 ✅

2.3. Alice tries to set P2 in IP2 -> Fails, reciprocal means no different policies allowed,
and you cannot add the same policy twice ✅

# Setting multiple parents
Bob owns IP1, IP2 and IP3
Bob mints L1 with P1 from IP1
Bob mints L2 with P2 from IP2
Bob mints L3 with P3 from IP3

Alice owns IP4
Alice wants to burn L1,L2 and L3 to link as parents for IP4

1) Reciprocal
1.1) All licenses have the same reciprocal policy -> OK, result has 1 Policy
1.2) Different policies, but at least 1 reciprocal -> Fail

1.1) All licenses have the same reciprocal policy -> OK, result has 1 Policy ✅

1.2) Different policies, but at least 1 reciprocal -> Should Fail ✅

2) NonReciprocal
1.1) All licenses have the same reciprocal policy -> OK, result has 1 Policy
1.2) Different policies, but at least 1 reciprocal -> Fail

2.1) All licenses have the same reciprocal policy -> OK, result has 1 Policy ✅

2.2) Different policies, but at least 1 reciprocal -> Should Fail ✅


| Parameter | Multi parent eval | Reason |
Expand All @@ -82,67 +98,96 @@ Alice wants to burn L1,L2 and L3 to link as parents for IP4

# INTEGRATION

| Demo Use Case | Social Remixing | Commercial Activity |
|---------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------:|
| Purpose | Allow users to add multiple layers of creativity to an original work, with appropriate attribution and control for the source creator | Monetize an original work |
| License flavor | Non-commercial remix with attribution, reciprocal license | Permissionless commercial license with attribution |
| What makes this unique? | Endless remixing - tracking all the uses of a work, and giving the creator full credit | Provides the creator with full control over the uses of her work, while allowing any 3rd party to appropriately use the work for fair economics |
| | | |
| Parameters - all default EXCEPT | | |
| Attribution | Tagged | Tagged |
| Derivatives | Allowed-With-Attribution Allowed-With-Reciprocal License | |
| Commercial Use | | Allowed-With-Attribution |
| License Fee | | One-Time LicenseFee Actual fee TBD by Creator |
| Demo Use Case | Social Remixing | Commercial Activity |
|-----------------------|----------------------------------------------------|----------------------------------------------------|
| Purpose | Allow users to add multiple layers of creativity to an original work, with appropriate attribution and control for the source creator | Monetize an original work |
| License flavor | Non-commercial remix with attribution, reciprocal license | Permissionless commercial license with attribution |
| What makes this unique? | Endless remixing - tracking all the uses of a work, and giving the creator full credit | Provides the creator with full control over the uses of her work, while allowing any 3rd party to appropriately use the work for fair economics |
| Parameters - all default EXCEPT | | |
| Attribution | Tagged | Tagged |
| Derivatives | Allowed-With-Attribution Allowed-With-Reciprocal License | |
| Commercial Use | | Allowed-With-Attribution |
| License Fee | | One-Time LicenseFee Actual fee TBD by Creator |

P1 - Social Remixing
P2 - Commercial Activity

So we have:
- An original work A, has P1 and P2 set
- People can remix A into B and B into C, all of with P1
- People can remix A into B and B into C, all of with P1
- P2 is permissionless (since it's set on A)
- B can buy License from A with P2 and link if it passes verifications
- C can buy License from A with P2 and link if it passes verification

- P2 is NOT permissionless (commercializers are set ) // TODO: commercializer, whitelist or token gating
- P2 is NOT permissionless (commercializers are set)

/*
* TODO: commercializer, whitelist or token gating
*/

- B can buy License from A with P2 and link if CommercializerHelper agrees
- C can buy License from A with P2 and link if CommercializerHelper agrees



# DISPUTED CASES

# Plagiarism
Bob owns IP1
Bob sets P1 in IP1 (he can, since he clains IP1 is original)
## Plagiarism

Bob owns IP1
Bob sets P1 in IP1 (he can, since he claims IP1 is original)
Alice owns IP2
Alice mints L1 from IP1-P1
Alice links IP2 to IP1 with L1
Don finds out IP1 plagiarizes his IP0
Don raises dispute against IP1 for plagiarism
Dispute passes, IP1 is labeled as plagiarism
Bob cannot set policies in IP1
Bob cannot mint licenses from IP1
Alice cannot set policies in IP2
Alice cannot mint licenses from IP2
// TODO: royalties?

# Unattributed derivative
Bob owns IP1
Bob sets P1 in IP1 (he can, since he clains IP1 is original)

1. Don finds out IP1 plagiarizes his IP0

2. Don raises dispute against IP1 for plagiarism

3. Results after dispute passes:

3.1) IP1 is labeled as plagiarism

3.2) Bob cannot set policies in IP1

3.3) Bob cannot mint licenses from IP1

3.4) Alice cannot set policies in IP2

3.5) Alice cannot mint licenses from IP2

/*
* TODO: Handle royalties distribution
*/


## Unattributed derivative

Bob owns IP1
Bob sets P1 in IP1 (he can, since he claims IP1 is original)
Alice owns IP2
Alice mints L1 from IP1-P1
Alice links IP2 to IP1 with L1
Don finds out IP1 is a clear derivative of his IP0
Don raises dispute against IP1 for unatributed derivative
Dispute passes, IP1 is labeled as plagiarism
??? Either:
Bob cannot set policies in IP1
Bob cannot mint licenses from IP1
Alice cannot set policies in IP2
Alice cannot mint licenses from IP2
// TODO: royalties?
???? Or:
IP1 is forced to set IP0 as parent,
All policies from IP1 are disabled and IP0 policy is set instead
// Does this propagate through children/royalties?

1. Don finds out IP1 is a clear derivative of his IP0

2. Don raises dispute against IP1 for unattributed derivative

3. Possible outcomes:

3.1) Option 1:
- Bob cannot set policies in IP1
- Bob cannot mint licenses from IP1
- Alice cannot set policies in IP2
- Alice cannot mint licenses from IP2

/*
* TODO: Handle royalties distribution
*/

3.2) Option 2:
- IP1 is forced to set IP0 as parent
- All policies from IP1 are disabled and IP0 policy is set instead

/*
* Does this propagate through children/royalties?
*/

0 comments on commit 231401e

Please sign in to comment.