Antiflood Tokens

[sanity]

Overview

Antiflood tokens increase the cost of abusive behavior like spam and denial of service attacks within Locutus.

To create antiflood tokens, the user must give up something of value to obtain a token generator. A public/private keypair that meets some cryptographically provable criteria - such as a signed certificate of donation to Freenet. This generator releases new tokens at regular time intervals that depend on the token tier. The lowest tier, 30-second tokens, are released every 30 seconds. Higher tiers release less frequently: 1 minute, 10 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 12 hours, or 1 day.

Other systems can require that a token of some minimum tier be issued as a condition of some action like adding a message to an inbox. In the event of bad behavior by the generator owner, the recipient can create a complaint, which will be visible to anyone interacting with the generator.
Initially, this will be a centralized solution. The user must make a cryptographically blinded donation to Freenet to obtain a token generator. In the future, we will provide a decentralized on-network way to create new token generators. We're still at the ideation stage with that, but it will not be based on proof-of-work.

Token Generator

Creating a Token Generator

1. The user creates generator_key_pair and blinds generatorPublicKey to get blind(generator_public_key) before sending it to https://freenet.org/donations
2. Freenet's donation system selected a donation_key_pair based on the donation amount
3. Donation system signs blind(generator_public_key) with donation_private_key to produce signed(donation_public_key, blind(generator_public_key))
4. signed(donation_public_key, blind(generator_public_key)) is sent back to the user
5. The user unblinds it to obtain signed(donation_public_key, generator_public_key), this is the initialization certificate and can be used to prove that the generator has been initialized with a donation

Token Generator Contract

The Token Generator Contract keeps track of tokens that have been assigned

Contract State

The token contract state is a set of token assignments organized by tier (frequency of token release), and then the time the token is released.

The contract verifies that the release times for a tier match the tier. For example, a 15:30 UTC release time isn't permitted for hour_1 tier, but 15:00 UTC is permitted.

Note: Conflicting assignments for the same time slot are not permitted and indicate that the generator is broken or malicious.

struct TokenContractParameters {
    generator_public_key : PublicKey,
    current_date_utc : Date,
}

struct TokenContractState {
   /// A list of issued tokens
   tokens_by_tier : HashMap<Tier, HashMap<DateTime, TokenAssignment>>,
}

struct TokenAssignment {
   tier : Tier,

   issue_time : DateTime,

   /// The assignment, the recipient decides whether this assignment
   /// is valid based on this field. This will often be a PublicKey.
   assigned_to: [u8],

   /// `(tier, issue_time, assigned_to)` must be signed 
   /// by `generator_public_key`
   signature: Signature,
}

enum Tier {
  minute_1, minute_10, minute_30, hour_1, 
  hour_2, hour_4, hour_12, day_1
}

Requirements

For the TokenAssignment to be valid only one TokenAssignment must exist for a given issue_time and tier

Token assignment and verification

For example, consider a contract representing a message inbox, where senders must spend a token to add a message to the inbox. The inbox decides what tier of token is required, this should be made known to senders.

struct InboxContractState {
  messages : Vec<InboxMessage>,
}

struct InboxMessage {
  message: String,

  assignment: TokenAssignment,

  /// `(message, assignment)` signed by generator's public key
  signature: Signature,
}

1. The sender creates an InboxMessage including a valid TokenAssignment
2. The sender attempts to modify the inbox to add the new message
3. The InboxContract verifies that the tier is high enough and the assignment signature matches
4. The InboxContract verifies that the assignment is valid by checking the relevant TokenContractState, ignoring it if it isn't

Complaints

Generator Complaint Contract

A contract that maintains a list of valid complaints for a generator - complaints can be created by a token recepient. Tokens from a generator with an excessive number of complaints may be rejected. The recepient is responsible for adding complaints to this contract.

   struct GeneratorComplaintsParameters {
       generator_public_key: PublicKey,
   }
   
   struct GeneratorComplaintsState { 
      complaints : HashMap<DateTime, HashMap<Tier, Complaint>>,
   }
   
   struct Complaint {
    /// A valid assignment is required for a complaint
    assignment: TokenAssignment,

    /// Reason for the complaint
    reason: String,

    /// `(assignment, reason)` must be signed by the token
    /// recipient to be a valid complaint
    recepient_signature : Signature,
}

Enhancements

• We should randomize the daily changeover time for current_date_utc based on the generator_public_key to avoid a synchronized network change at 0:00 UTC.

• assigned_tofield inTokenAssignmentis redundant in anInboxMessagebecause we already know theassigned_to here. We should avoid wasting these bytes.

• Token recipients can specify a maximum token age, preventing passive accumulation of a large number of tokens over time

• A duplicate token assignment is evidence of malicious behavior by the generator owner and will disable the token generator

Conclusion

We've now described a mechanism for generating scarce tokens that can be spent to gain access to potentially floodable resources like a message inbox.

[iduartgomez]

• This requires implementing local storage through the node.

#283

[sanity]

Just capturing my thoughts after today's call:

The key question is how to allow an application to request a token assignment, perhaps to send an email to a particular inbox, without allowing a malicious application just to spend all of your tokens. This is an example of a more general problem we need to solve about permissioning in Locutus.

One possibility would be to temporarily direct the user to the antiflood token application UI to make the token assignment, supplying the info it needs to do this in URL query parameters. This is similar to OAUTH authentication mechanisms.

A problem with this is that for some small task like sending an email, this redirection would be too cumbersome, the user experience should be similar to using a normal email app.

Another possibility would be to tie the token allocations to the hash of the application or component requesting the assignment. This would mean that each application gets its own token allocation slots independent of other applications, limiting any damage they can do.

This would require some kind of way for apps/components to communicate with each other through the local node where each knows the hash of the component they're talking to. But then do components need the ability to run independently of the browser? If so they'd be more like plugins (see #283) than in-browser apps.

This approach would prevent malicious applications from harming any other applications' tokens. However, it would also mean that tokens are only a scarce resource within the context of a specific application - rather than being globally scarce, which might make them less effective.

[sanity]

Thinking through the sequence for assigning an antiflood token:

1. User Alice wishes to send a message to user Bob
2. Alice's messaging application looks at Bob's inbox contract to see what the criteria are to send a message, eg.
   • What tier should the anti-flood token be?
   • How recent does it need to be?
3. Alice's messaging application requests a token assignment from her anti-flood token component that meets these criteria
   • The token assignment should include a signature of the message
4. This assignment is attached to the message by Alice's messaging application and added to Bob's inbox
5. Bob's inbox uses the related contract mechanism to verify that Alice's token assignment is present on Alice's
   The anti-flood token generator contract and its signature match the message
6. Bob periodically reads his inbox and clears his inbox contract once the messages are downloaded/read

Questions:

• How is the recency of the token verified by Bob's inbox contract? Will need access to the current time, or must Bob continuously update his contract to specify the oldest permissible message?

[iduartgomez]

5. Bob's inbox uses the related contract mechanism to verify that Alice's token assignment is present on Alice's
   The anti-flood token generator contract and its signature match the message

This is the first time in the description the antiflood token generator contract is mentioned, when is the assignment added to it and when is the contract created for first time? I guess is after steep 3 and before 4.

I take that contract is just the ledger of tokens assigned and it's used to have this double-steep verification (we talked about this before I think) where the token is present in both Alice's ledger and Bob's inbox (to ensure there is no double-spending and that the token has been indeed assigned).

[iduartgomez]

I've an other question regarding code organization and how we structure all this, we have the following requirements:

• Antiflood token component/contract data types must be public so they can be used by other contracts (or the schemas must be in case we are using some deserialization protocol).
• Antiflood token component/contract code needs to be public so it can be instanced/used by applications, it must be a re-usable "component" (or module, to avoid confusion).
• In this particular example, inbox contracts are particular to the application, so they reside at a different namespace. The same as the application code itself.

Right now I created a components directory (this could be its own repository, is just in the same repo to have less friction for now) where we have a Rust crate which contain both the token contract/component code in the same crate (it can be compiled for both purposes, nothing stopping us doing that). Question: should we split the code between component and contract in different libraries? Then we need a third library to share the common types. Right now:
./components/antiflood-tokens/../lib.rs <- library which contains the AFT contract && component
I don't know if is preferable to split the code into different libraries that compile to different WASM objects/modules; or if we should name this in a more appropriate way ("modules" instead of components, for example) so is not confusing.

If we had to split we need to decide how we must export/distribute this stuff. Some options:
Option 1.

./components/aft/../lib.rs \<- AFT component (imports shared)
- components dir description: useful @locutus std reusable components
./contracts/aft/../lib.rs \<- AFT contracts (imports shared)
- contracts dir description: useful @locutus std reusable contracts
./shared/aft/../lib.rs \<- AFT shared data types/logic between contract and component && potentially the app
- shared, or libs/common, or any other name, shared dependencies necessary at compile time

Option 2.

./modules/aft/..
./modules/aft/Cargo.toml \<- workspace of all the AFT "shared component/module" related code
./modules/aft/crates/component/../lib.rs \<- lib for the component code
./modules/aft/crates/contract/../lib.rs \<- lib for the contract code
./modules/aft/crates/shared/../lib.rs \<- lib for shared data types/logic for the component && contract && potentially the app

here module means a reusable functionality in the ecosystem basically (which can be composed of one or more component/contracts that are supposed to work together)